StardDevelopersداشبورد

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

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

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

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

Stard Shop Bot یک ربات تلگرام آماده و متن‌باز با مجوز MIT است که استارز تلگرام، تلگرام پریمیوم و گیفت‌های استارزی را می‌فروشد. قیمت‌ها و سفارش‌ها مستقیم به Stard API وصل‌اند؛ مالک ربات فقط درصد سود خودش را روی قیمت API می‌گذارد و سفارش‌ها خودکار ثبت و تحویل می‌شوند. کد کامل: 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_KEYsk_test_… یا sk_live_…الزامی
STARD_BASE_URLآدرس APIhttps://stard-market.ir/api/v1
STARD_PAY_CURRENCYIRT یا TONپیش‌فرض داشبورد
DATABASE_PATHمسیر SQLitedata/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 اجرا می‌شود و نتیجه‌ی سفارش را هم می‌شود شبیه‌سازی کرد.

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

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