---
title: ربات فروشگاهی آماده‌ی تلگرام (Stard Shop Bot)
url: https://stard-market.ir/docs/shop-bot
markdown: https://stard-market.ir/docs/shop-bot.md
language: fa
updated: 2026-11-18
description: ربات متن‌باز فروش استارز، پریمیوم و گیفت تلگرام؛ فقط توکن ربات و کلید Stard API را بده، درصد سودت را بگذار و فروشگاه خودت را داشته باش.
---

# ربات فروشگاهی آماده‌ی تلگرام (Stard Shop Bot)

> ربات متن‌باز فروش استارز، پریمیوم و گیفت تلگرام؛ فقط توکن ربات و کلید Stard API را بده، درصد سودت را بگذار و فروشگاه خودت را داشته باش.

**جواب کوتاه:** Stard Shop Bot یک ربات فروشگاهی آماده و رایگان برای فروش استارز، پریمیوم و گیفت تلگرام است؛ با توکن ربات و کلید Stard API در چند دقیقه راه می‌افتد و سود هر فروش مال خودت است.

## ربات فروشگاهی استارد چیست؟

**Stard Shop Bot** یک ربات تلگرام آماده و متن‌باز با مجوز MIT است که استارز تلگرام، تلگرام پریمیوم و گیفت‌های استارزی را می‌فروشد. قیمت‌ها و سفارش‌ها مستقیم به [Stard API](https://stard-market.ir/docs) وصل‌اند؛ مالک ربات فقط درصد سود خودش را روی قیمت API می‌گذارد و سفارش‌ها خودکار ثبت و تحویل می‌شوند. کد کامل: [github.com/arad-afray/stard-shop-bot](https://github.com/arad-afray/stard-shop-bot).

## امکانات

### برای کاربر

- فروشگاه دسته‌بندی‌شده: استارز (آماده یا دلخواه)، پلن‌های پریمیوم، گیفت‌ها
- کیف پول داخلی با شارژ کارت‌به‌کارت و رسید
- پیش‌فاکتور و دکمه‌ی «برای خودم»
- تاریخچه‌ی سفارش با وضعیت لحظه‌ای و اعلان خودکار
- پشتیبانی از اعداد فارسی و عربی

### برای مالک

- درصد سود کلی و جدا برای هر دسته
- آمار فروش، سود خالص و سفارش‌های در جریان
- تایید یا رد شارژها با یک دکمه
- مدیریت کاربر، موجودی و مسدودسازی
- پیام همگانی
- نمایش موجودی کیف پول Stard API و محیط test/live
- باز و بسته کردن فروشگاه

### قابلیت اطمینان

- کسر موجودی اتمیک
- Idempotency-Key روی هر سفارش
- `quote_id` برای قفل قیمت
- برگشت خودکار پول سفارش ناموفق، فقط یک بار
- دفتر کل (ledger) برای هر تومان
- تلاش دوباره روی 429، 5xx و قطعی شبکه

## راه‌اندازی در ۷ قدم

1. **ساخت ربات**: در @BotFather یک ربات بساز و توکنش را بردار.
2. **ساخت کلید API**: در داشبورد توسعه‌دهندگان استارد یک کلید sk_test_ بساز (برای تست بدون پول واقعی).
3. **دریافت کد**: مخزن stard-shop-bot را از گیت‌هاب clone کن و فایل .env.example را به .env کپی کن.
4. **تنظیم**: در .env مقدار BOT_TOKEN، ADMIN_IDS و STARD_API_KEY را بنویس.
5. **اجرا**: با docker compose up -d --build یا python -m bot اجرا کن.
6. **تنظیمات فروشگاه**: در ربات /start بزن، از پنل مدیریت شماره کارت، نام صاحب کارت و درصد سود را تنظیم کن.
7. **رفتن به live**: حساب تلگرام را در داشبورد وصل کن، کیف پول Stard را شارژ کن و کلید sk_live_ بگذار.

```
git clone https://github.com/arad-afray/stard-shop-bot.git
cd stard-shop-bot
cp .env.example .env
# BOT_TOKEN, ADMIN_IDS, STARD_API_KEY
docker compose up -d --build
```

## متغیرهای محیطی

| متغیر | توضیح | پیش‌فرض |
|---|---|---|
| `BOT_TOKEN` | توکن ربات از BotFather | الزامی |
| `ADMIN_IDS` | آیدی عددی مدیرها، با کاما | — |
| `STARD_API_KEY` | sk_test_… یا sk_live_… | الزامی |
| `STARD_BASE_URL` | آدرس API | https://stard-market.ir/api/v1 |
| `STARD_PAY_CURRENCY` | IRT یا TON | پیش‌فرض داشبورد |
| `DATABASE_PATH` | مسیر SQLite | data/shop.db |
| `DEFAULT_PROFIT_PERCENT` | سود اولیه٪ | 10 |
| `POLL_INTERVAL_SECONDS` | فاصله‌ی پیگیری سفارش | 20 |

## جریان سفارش

1. کاربر محصول را انتخاب می‌کند؛ ربات با `POST /orders/quote` قیمت و `quote_id` (قفل ۲ دقیقه‌ای) می‌گیرد.
2. قیمت فروش = قیمت × (۱ + سود٪).
3. با تایید کاربر، موجودی کسر و `POST /orders` با Idempotency-Key ثبت می‌شود.
4. worker هر ۲۰ ثانیه وضعیت را می‌پرسد؛ completed ← «تحویل شد»، failed یا refunded ← برگشت پول.

*⚠️*

در live، موجودی کیف پول Stard باید از مجموع سفارش‌های در جریان بیشتر باشد؛ وگرنه سفارش با insufficient_funds رد و پول کاربر برگردانده می‌شود.

## پرسش‌های رایج

**ربات فروشگاهی استارد چیست؟**

یک ربات تلگرام آماده و متن‌باز (MIT) که استارز، تلگرام پریمیوم و گیفت تلگرام را می‌فروشد و قیمت و تحویل را از Stard API می‌گیرد. مالک فقط توکن ربات و کلید API را می‌دهد و درصد سود خودش را تعیین می‌کند.

**برای راه‌اندازی برنامه‌نویسی لازم است؟**

نه. کافی است توکن ربات، آیدی عددی مدیر و کلید API را در فایل .env بنویسی و با Docker اجرا کنی.

**سود من چطور حساب می‌شود؟**

قیمت فروش = قیمت Stard × (۱ + درصد سود). درصد سود را از پنل مدیریت ربات، کلی یا جدا برای هر دسته، تعیین می‌کنی.

**اگر سفارش انجام نشود پول کاربر چه می‌شود؟**

سفارش ناموفق، لغوشده یا برگشتی خودکار و فقط یک بار به کیف پول کاربر برمی‌گردد و کاربر پیام می‌گیرد.

**آیا ممکن است یک سفارش دو بار خریده شود؟**

نه. هر سفارش Idempotency-Key دارد و کسر موجودی اتمیک است؛ قطعی شبکه هم باعث خرید تکراری نمی‌شود.

**می‌توانم بدون پول واقعی امتحان کنم؟**

بله. با کلید sk_test_ همه‌چیز در محیط test اجرا می‌شود و نتیجه‌ی سفارش را هم می‌شود شبیه‌سازی کرد.

**کاربران چطور پرداخت می‌کنند؟**

کیف پول داخلی ربات را با کارت‌به‌کارت و ارسال عکس رسید شارژ می‌کنند و مدیر با یک دکمه تایید می‌کند.
