راهنما · PayStars

PayStars API برای توسعه‌دهندگان: جریان کامل فروش Stars و Premium در ربات شما

PayStars REST API از ابتدا تا انتها چگونه کار می‌کند: X-API-Key، بررسی نام کاربری، قیمت USD با max_usd، سفارش‌های تکرار-ایمن، خطای 409 price_changed و تأیید TxId، به‌عنوان طرح یکپارچه‌سازی.

منتشرشده: · به‌روزرسانی‌شده:

PayStars API برای توسعه‌دهندگان: جریان کامل فروش Stars و Premium در ربات شما

می‌خواهید Telegram Stars و Premium را داخل ربات، فروشگاه یا برنامه خود بفروشید؟ PayStars API یک رابط HTTPS و موجودی USD مشترک با وب‌سایت به شما می‌دهد. به‌جای تکرار مرجع API، این مقاله نشان می‌دهد چگونه یکپارچه‌سازی را از ابتدا تا انتها بسازید.

معماری در یک نگاه

سامانه شما سه کار انجام می‌دهد: موجودی را با USDT شارژ می‌کند، قیمت می‌پرسد و سفارش می‌سازد. بقیه کارها، از جمله تحویل از طریق جریان خرید رسمی Telegram، در سمت PayStars انجام می‌شود.

بخشکارکرد
دسترسیهدر X-API-Key؛ کلیدها در داشبورد ساخته می‌شوند
موجودیUSD، شارژ با USDT (TON، BEP20 یا TRC20)
قیمتقیمت Fragment × 1.05، گردشده به سنت بالاتر
محدودیت10 درخواست در ثانیه برای هر کلید
شفافیتیک TxId عمومی برای هر سفارش تکمیل‌شده

مرحله 1: شارژ موجودی

POST /usd/invoice با مبلغ و زنجیره ("ton"، "bsc" یا "trc20") مبلغ دقیقی برمی‌گرداند که 30 دقیقه معتبر است. حداقل 0.1 USDT است.

مرحله 2: تأیید گیرنده

POST /api/v1/check-username گیرنده را بررسی می‌کند و یک توکن تأیید کوتاه‌مدت برمی‌گرداند. این کار از پرداخت به نام‌کاربری‌هایی که وجود ندارند جلوگیری می‌کند: اگر مشتری اشتباه تایپ کند، پیش از هر کسر متوجه می‌شوید.

مرحله 3: گرفتن و سقف‌گذاری قیمت

POST /api/v1/usd/quote قیمت فعلی (usd) و اضافه بها (markup_percent: 5) را برمی‌گرداند. قیمت از بازار پیروی می‌کند، پس:

  • پیش از هر سفارش یک قیمت تازه بگیرید؛
  • max_usd را برابر مبلغ اعلام‌شده بفرستید؛
  • همیشه currency: "USD" را بفرستید، وگرنه ترجیح ذخیره‌شده حساب به‌کار می‌رود.

مرحله 4: ساخت سفارش

POST /api/v1/stars/buy یا /api/v1/premium/buy. هر درخواست باید Idempotency-Key داشته باشد تا اگر اتصال قطع شد و دوباره تلاش کردید، دوبار کسر نشود. کلید را کنار شناسه سفارش در پایگاه داده خود ذخیره کنید.

مرحله 5: پیگیری وضعیت

GET /api/v1/order/{id} و /api/v1/orders وضعیت‌ها و تاریخچه را می‌دهند. بیشتر سفارش‌ها ظرف چند دقیقه تحویل می‌شوند. سفارش تکمیل‌شده یک TxId می‌گیرد که هم شما و هم مشتری‌تان می‌توانید آن را در دفترکل عمومی PayStars بررسی کنید.

مدیریت درست خطاها

  • 409 price_changed یعنی قیمت از max_usd بالاتر رفته و چیزی کسر نشده است. قیمت جدید بگیرید و قیمت به‌روز را به مشتری نشان دهید.
  • محدودیت نرخ: از 10 درخواست در ثانیه بیشتر نشوید؛ صف یا تأخیر تدریجی اضافه کنید.
  • تلاش مجدد: همیشه همان Idempotency-Key را دوباره استفاده کنید.

پیش از راه‌اندازی

  1. کلید API را در متغیر محیطی سرور نگه دارید، نه در کد.
  2. کل جریان را با یک سفارش واقعی کوچک 50 Stars اجرا کنید.
  3. TxId را به مشتریان نشان دهید؛ این اعتماد می‌سازد.

مستندات کامل و شروع سریع: PayStars Stars API و قیمت‌گذاری USD برای API. برای پرداخت درون ربات، کالاهای دیجیتال در ربات‌ها فقط با Stars پرداخت می‌شوند را ببینید.

پرسش‌های متداول

آیا محیط آزمایشی وجود دارد؟

محیط آزمایشی جداگانه‌ای وجود ندارد؛ هنگام یکپارچه‌سازی با سفارش‌های واقعی کوچک (50 Stars) آزمایش کنید.

کدام زبان‌های برنامه‌نویسی کار می‌کنند؟

هر زبانی که بتواند درخواست HTTPS بفرستد. راهنمای شروع سریع برای Python، Node.js و PHP وجود دارد.

چگونه موجودی را شارژ کنم؟

با USDT روی TON، BEP20 یا TRC20، حداقل 0.1 USDT؛ هر فاکتور مبلغ دقیقی دارد که 30 دقیقه معتبر است.

منابع

خرید Stars و Premium با دلار (USDT)

با کلید API: قیمت Fragment، ۰٪ (وب‌سایت: ۵٪).

شروع کنید