{"openapi":"3.0.3","info":{"title":"API خرید استارز و پریمیوم تلگرام","version":"1.0.0","description":"API عمومی REST برای خرید «استارز تلگرام» و «تلگرام پریمیوم» از طریق فرگمنت. احراز هویت با کلید API (هدر Authorization: Bearer sk_live_…)، مبالغ به تومان (عدد صحیح)، زمان‌ها ISO 8601 (UTC). هر کلید به‌طور پیش‌فرض ۶۰ درخواست در دقیقه دارد (هدرهای X-RateLimit-*). ثبت سفارش از Idempotency-Key پشتیبانی می‌کند."},"servers":[{"url":"https://www.team404.ir/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"عمومی"},{"name":"قیمت"},{"name":"سفارش"},{"name":"کیف پول"}],"paths":{"/openapi.json":{"get":{"tags":["عمومی"],"summary":"مشخصات OpenAPI (بدون نیاز به کلید)","security":[],"responses":{"200":{"description":"JSON"}}}},"/ping":{"get":{"tags":["عمومی"],"summary":"بررسی کلید API","responses":{"200":{"description":"کلید معتبر است","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ping"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prices":{"get":{"tags":["قیمت"],"summary":"قیمت استارز و بسته‌های پریمیوم","responses":{"200":{"description":"قیمت‌ها","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Prices"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stars/price":{"get":{"tags":["قیمت"],"summary":"قیمت یک تعداد مشخص استارز","parameters":[{"name":"quantity","in":"query","schema":{"type":"integer","minimum":50,"default":50}}],"responses":{"200":{"description":"قیمت","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StarsPrice"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"تعداد نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/premium/prices":{"get":{"tags":["قیمت"],"summary":"قیمت بسته‌های پریمیوم","responses":{"200":{"description":"بسته‌ها","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PremiumPrices"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recipients/{username}":{"get":{"tags":["سفارش"],"summary":"بررسی وجود گیرنده در فرگمنت","description":"پیش از ثبت سفارش می‌توانید بررسی کنید که یوزرنیم قابل دریافت استارز یا پریمیوم است (این درخواست به فرگمنت می‌رود؛ حداکثر ۲۰ بار در دقیقه).","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string","enum":["stars","premium"],"default":"stars"}},{"name":"quantity","in":"query","description":"تعداد استارز (برای type=stars)","schema":{"type":"integer","default":50}},{"name":"months","in":"query","description":"مدت (برای type=premium)","schema":{"type":"integer","enum":[3,6,12],"default":3}}],"responses":{"200":{"description":"گیرنده پیدا شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipient"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"گیرنده پیدا نشد (recipient_not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet":{"get":{"tags":["کیف پول"],"summary":"موجودی کیف پول","responses":{"200":{"description":"موجودی","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions":{"get":{"tags":["کیف پول"],"summary":"تراکنش‌های کیف پول","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"تراکنش‌ها","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionList"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"tags":["سفارش"],"summary":"ثبت سفارش","description":"مبلغ بلافاصله از کیف پول کم می‌شود و سفارش برای خرید از فرگمنت در صف می‌رود. اگر تحویل قطعاً ناموفق شود و TON ای فرستاده نشده باشد، مبلغ خودکار برمی‌گردد (status=failed).","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":64},"description":"برای جلوگیری از ثبت دوباره هنگام تکرار درخواست"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIn"}}}},"responses":{"201":{"description":"سفارش ثبت شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"200":{"description":"تکرار همان Idempotency-Key؛ همان سفارش برگردانده شد (هدر Idempotent-Replay: true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"کلید نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"موجودی کیف پول کافی نیست (insufficient_funds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"کلید اجازه‌ی سفارش ندارد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key با درخواست دیگری استفاده شده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"ورودی نامعتبر","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ یا سقف روزانه","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"سرویس در دسترس نیست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["سفارش"],"summary":"فهرست سفارش‌ها","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","completed","failed","cancelled","refunded"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"فهرست","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderList"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"tags":["سفارش"],"summary":"وضعیت یک سفارش","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"شناسه‌ی سفارش (مثل T-7KQ2M9XA)"}],"responses":{"200":{"description":"سفارش","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/cancel":{"post":{"tags":["سفارش"],"summary":"لغو سفارشی که ارسالش شروع نشده","description":"فقط وقتی ممکن است که خرید از فرگمنت هنوز شروع نشده باشد (status=queued یا review). مبلغ به کیف پول برمی‌گردد.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"لغو شد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"کلید API نامعتبر یا ارسال‌نشده","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"محدودیت نرخ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"پیدا نشد","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"دیگر قابل لغو نیست (not_cancellable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_funds"},"message":{"type":"string"},"details":{"type":"object"}}}}},"Ping":{"type":"object","properties":{"ok":{"type":"boolean"},"key":{"type":"object"},"time":{"type":"string","format":"date-time"}}},"Prices":{"type":"object","properties":{"stars":{"type":"object","properties":{"unit_price":{"type":"integer"},"min":{"type":"integer"},"max":{"type":"integer"}}},"premium":{"type":"array","items":{"type":"object","properties":{"months":{"type":"integer"},"price":{"type":"integer"}}}},"available":{"type":"boolean","description":"آیا هم‌اکنون سفارش‌گیری فعال است"},"currency":{"type":"string","example":"IRT"}}},"StarsPrice":{"type":"object","properties":{"quantity":{"type":"integer"},"unit_price":{"type":"integer"},"price":{"type":"integer"},"currency":{"type":"string"}}},"PremiumPrices":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object"}},"currency":{"type":"string"}}},"Recipient":{"type":"object","properties":{"found":{"type":"boolean"},"username":{"type":"string"},"name":{"type":"string"}}},"Wallet":{"type":"object","properties":{"balance":{"type":"integer"},"currency":{"type":"string"}}},"TransactionList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"OrderIn":{"type":"object","required":["recipient"],"properties":{"type":{"type":"string","enum":["stars","premium"],"default":"stars"},"recipient":{"type":"string","description":"یوزرنیم تلگرام گیرنده (با @ یا بدون @)","example":"durov"},"quantity":{"type":"integer","description":"تعداد استارز (type=stars)","example":100},"months":{"type":"integer","enum":[3,6,12],"description":"مدت پریمیوم (type=premium)"},"metadata":{"type":"object","description":"داده‌ی دلخواه شما (حداکثر ۲ کیلوبایت)؛ در پاسخ سفارش برمی‌گردد"}}},"Order":{"type":"object","properties":{"id":{"type":"string","example":"T-7KQ2M9XA"},"type":{"type":"string"},"status":{"type":"string","enum":["pending","queued","review","processing","completed","failed","cancelled","refunded"]},"recipient":{"type":"string"},"quantity":{"type":"integer"},"months":{"type":"integer"},"amount":{"type":"integer"},"currency":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","nullable":true},"tx_hash":{"type":"string","nullable":true,"description":"هش تراکنش TON (فقط وقتی completed)"},"refunded":{"type":"boolean"},"error":{"type":"object","description":"علت شکست (status=failed) یا آخرین خطای قابل‌تلاش‌مجدد (status=processing)"}}},"OrderList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}}