مستندات API نمایندگی

API نمایندگی SHOP2TOPUP یک JSON REST API برای فروش شارژ بازی، شارژ حساب بازی و کدهای ووچر از فروشگاه، ویترین یا بات خودتان است. این مرجع همه اندپوینت‌های عمومی، پارامترها و پاسخ‌هایشان را مستند می‌کند.

آدرس پایه و انتقال

هر مسیر در این مرجع نسبت به آدرس پایه زیر است. درخواست‌ها و پاسخ‌ها JSON روی HTTPS هستند، مبالغ به‌صورت رشته می‌آیند تا خطای گرد کردن اعشاری پیش نیاید و هر زمان به‌صورت UTC در قالب ISO 8601 است.

https://shop2topup.com/api/endpoints/v1

احراز هویت

هر درخواست یک هدر حمل می‌کند. جفت کلید از صفحه API Access پنل نمایندگی شما صادر می‌شود و می‌توان آن را به یک فهرست IP مجاز محدود کرد؛ فراخوانی از هر آدرس دیگری پیش از رسیدن به هر منطق تجاری با IP_NOT_ALLOWED رد می‌شود.

هدر درخواست

Authorization: Bearer <keyId>.<secret>

اولین فراخوانی

چیزی برای نصب نیست. کلید خودتان را جایگذاری کنید تا داده زنده کاتالوگ برگردد.

درخواست — cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

قراردادهای پاسخ

هر پاسخ یک فیلد بولی success دارد، بنابراین یک شرط، مسیر موفق را از هر خطایی جدا می‌کند.
خطاها یک شیء error با یک code پایدار، یک message خوانا برای انسان و details اختیاری برمی‌گردانند. بر اساس code شرط بگذارید، نه message.
پول همیشه یک رشته اعشاری مانند "0.950000" به دلار است. پیش از مقایسه یا جمع زدن، آن را به عدد اعشاری دودویی تبدیل نکنید.
اندپوینت‌های فهرستی یک شیء pagination با فیلدهای page، limit، total و total_pages برمی‌گردانند.
ثبت سفارش نسبت به UUID که در order_id می‌فرستید idempotent است، بنابراین تکرار درخواست هرگز نمی‌تواند دو بار کسر کند.

پاسخ خطا

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

بخش‌های مرجع

کاتالوگکاتالوگ یک درخت سه‌سطحی است: دسته‌های بزرگ شامل دسته‌ها هستند، دسته‌ها شامل زیردسته‌ها و زیردسته همان آیتمی است که واقعاً می‌خرید. این اندپوینت‌ها به شما امکان می‌دهند همان درخت را در پایگاه داده خودتان بازتاب دهید و درست پیش از سفارش، قیمت یک آیتم را بگیرید.اعتبارسنجی بازیکناعتبارسنجی بازیکن پیش از جابه‌جایی هر پولی حساب درون‌بازی را مشخص می‌کند. تأیید می‌کند که شناسه برای آن محصول وجود دارد، نام درون‌بازی را برمی‌گرداند تا خریدارتان آن را بررسی کند و منطقه را نشان می‌دهد؛ بنابراین سفارش بین‌منطقه‌ای از ابتدا رد می‌شود و پس از پرداخت شکست نمی‌خورد.سفارش‌هاسفارش‌ها با UUID ای ساخته می‌شوند که خودتان تولید می‌کنید. همان UUID کلید idempotency است: تکرار آن به‌جای کسر دوباره، همان سفارش اصلی را برمی‌گرداند. وضعیت سپس برای هر سفارش، در دسته‌های حداکثر پنجاه‌تایی یا در قالب فهرست صفحه‌بندی‌شده خوانده می‌شود.حساب و دسترسیهر درخواست یک هدر حمل می‌کند. GET /account همان اندپوینتی است که صدا می‌زنید تا ثابت کنید کلید کار می‌کند، موجودی کیف پولی را که سفارش‌ها از آن کسر می‌شوند بخوانید و پیش از شروع یک اجرای دسته‌ای مطمئن شوید حساب فعال است.کدهای خطاهر خطا در کنار وضعیت HTTP یک کد پایدار و ماشین‌خوان برمی‌گرداند. بر اساس کد شرط بگذارید، نه بر اساس متن پیام: پیام‌ها برای انسان نوشته شده‌اند و ممکن است بازنویسی شوند، در حالی که کدها بخشی از قرارداد هستند.

محدودیت‌های نرخ

محدودیت‌ها به‌ازای هر حساب و روی یک پنجره لغزان اعمال می‌شوند. هر پاسخ هدرهای X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را حمل می‌کند و یک فراخوانی محدودشده با هدر Retry-After پاسخ 429 می‌گیرد.

مسیر	درخواست	پنجره	شمارش بر اساس
GET /catalog/* (all five)	80	60s	per account
POST /orders/create	120	60s	per account
GET /orders/:orderId	3	60s	per account + order id
POST /orders/batch	2	60s	per account
GET /orders	2	60s	per account
GET /account	60	60s	per account
POST /player/validate	dedicated limiter	—	per account

وب‌هوک‌ها

نتیجه سفارش‌ها به اندپوینت HTTPS ای که ثبت می‌کنید فرستاده می‌شود و با HMAC-SHA256 روی بدنه خام امضا می‌شود. فهرست رویدادها، فهرست هدرها، ساختار محتوا و یک نمونه بررسی امضا در صفحه معرفی API مستند شده‌اند.

خواندن مرجع محتوا و امضای وب‌هوک

تازه با پلتفرم آشنا شده‌اید؟ از معرفی API شارژ بازی برای نمایندگان فروش شروع کنید، یا معرفی برنامه نمایندگی SHOP2TOPUP را بخوانید تا ببینید حساب شریک چگونه کار می‌کند.