اندپوینت‌های کاتالوگ

کاتالوگ یک درخت سه‌سطحی است: دسته‌های بزرگ شامل دسته‌ها هستند، دسته‌ها شامل زیردسته‌ها و زیردسته همان آیتمی است که واقعاً می‌خرید. این اندپوینت‌ها به شما امکان می‌دهند همان درخت را در پایگاه داده خودتان بازتاب دهید و درست پیش از سفارش، قیمت یک آیتم را بگیرید.

GET

/catalog/big-categories

فهرست دسته‌بندی‌های اصلی

همه دسته‌بندی‌های سطح بالا را دریافت کنید (مثلاً بازی‌های موبایل، بازی‌های PC، گیفت کارت‌ها).

محدودیت نرخ۵۰۰۰ درخواست در هر ۶۰ ثانیه برای هر حساب (مشترک بین همه اندپوینت‌های کاتالوگ)

پارامترهای کوئری

نامنوعالزامیتوضیحنمونه
for_uibooleanخیرURL تصاویر را هم در پاسخ برمی‌گرداند.true
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/big-categories?for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "big_categories": [
    {
      "id": 1,
      "name": "Mobile Games",
      "description": "Popular mobile game top-ups"
    },
    {
      "id": 2,
      "name": "PC Games",
      "description": "PC game credits and items"
    }
  ]
}
GET

/catalog/categories

فهرست دسته‌بندی‌ها

دسته‌بندی‌ها را دریافت کنید؛ در صورت نیاز می‌توانید آنها را بر اساس دسته‌بندی اصلی فیلتر کنید. هر دسته‌بندی یک بازی یا سرویس است.

محدودیت نرخ۵۰۰۰ درخواست در ۶۰ ثانیه برای هر حساب (مشترک بین همه اندپوینت‌های کاتالوگ)

پارامترهای کوئری

نامنوعالزامیتوضیحنمونه
bigCategoryIdnumberخیرفیلتر بر اساس شناسه دسته‌بندی اصلی.1
for_uibooleanخیرURL تصاویر را هم در پاسخ برمی‌گرداند.true
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1&for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "categories": [
    {
      "id": 12,
      "name": "Free Fire",
      "description": "Garena Free Fire diamonds",
      "big_category_id": 1,
      "big_category_name": "Mobile Games"
    }
  ]
}
GET

/catalog/subcategories

فهرست زیردسته‌ها (محصولات)

محصولات و بسته‌های موجود را برمی‌گرداند. هر زیردسته یک آیتم قابل خرید است.

محدودیت نرخ۵۰۰۰ درخواست در ۶۰ ثانیه برای هر حساب (مشترک بین همه اندپوینت‌های کاتالوگ)

نکته: مقدار product_type برای شارژ مستقیم حساب بازیکن 'topup' و برای محصولی که کد تحویل می‌دهد 'voucher' است. فیلدهای fulfillment_type ('api' برای شارژ، 'voucher' برای کد) و returns_voucher (برای کد true) منسوخ شده‌اند و فقط همان product_type را تکرار می‌کنند. اگر فیلد id وجود داشته باشد، مقدار آن با item_id برابر است.

پارامترهای کوئری

نامنوعالزامیتوضیحنمونه
categoryIdnumberخیرفیلتر بر اساس شناسه دسته‌بندی.12
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategories?categoryId=12" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "subcategories": [
    {
      "item_id": 999,
      "name": "FF 100 Diamonds",
      "description": "100 Free Fire Diamonds",
      "category_id": 12,
      "category_name": "Free Fire",
      "price": "0.99",
      "product_type": "topup",
      "fulfillment_type": "api",
      "returns_voucher": false
    }
  ]
}
GET

/catalog/subcategory/:itemId/price

دریافت قیمت آیتم

قیمت فعلی با تخفیف را برای یک زیردسته یا آیتم مشخص برمی‌گرداند. پیش از ثبت سفارش آن را بگیرید تا هزینه دقیق را بدانید.

محدودیت نرخ۵۰۰۰ درخواست در ۶۰ ثانیه برای هر حساب (مشترک بین همه اندپوینت‌های کاتالوگ)

نکته: مبلغی که از شما کسر می‌شود همان unit_price است. هنگام ثبت سفارش، همین مقدار را برای expected_unit_price بفرستید.

پارامترهای مسیر

نامنوعالزامیتوضیحنمونه
itemIdnumberبلهشناسه زیردسته یا آیتم.999
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategory/999/price" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "price": {
    "item_id": 999,
    "item_name": "FF 100 Diamonds",
    "unit_price": "0.950000",
    "currency": "USD",
    "original_price": "0.990000",
    "discount_applied": true,
    "timestamp": "2024-06-15T12:00:00Z"
  }
}
GET

/catalog/category/:categoryId/requirements

دریافت الزامات دسته‌بندی

فیلدهای الزامی پویای یک دسته‌بندی مشخص را برمی‌گرداند. این فیلدها نشان می‌دهند برای اعتبارسنجی بازیکن یا ثبت سفارش چه اطلاعاتی لازم است (مثلاً شناسه بازیکن، سرور، منطقه).

محدودیت نرخ۵۰۰۰ درخواست در ۶۰ ثانیه برای هر حساب (مشترک بین همه اندپوینت‌های کاتالوگ)

نکته: با فیلدهای برگشتی، فرم‌های پویا برای اعتبارسنجی بازیکن و ثبت سفارش بسازید. هر فیلد data_type خود را مشخص می‌کند (text، number، single_select، multi_select) و برای فیلدهای انتخابی، گزینه‌های موجود را هم دارد.

پارامترهای مسیر

نامنوعالزامیتوضیحنمونه
categoryIdnumberبلهشناسه دسته‌بندی‌ای که الزامات آن را می‌خواهید.12
درخواست
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/category/12/requirements" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
نمونه پاسخ
{
  "success": true,
  "requirements": [
    {
      "field_name": "player_id",
      "data_type": "text",
      "placeholder": "Enter player ID"
    },
    {
      "field_name": "server",
      "data_type": "single_select",
      "placeholder": "Select server",
      "select_options": [
        "Asia",
        "Europe",
        "America"
      ]
    }
  ]
}

یک درخواست واقعی را از همین صفحه بفرستید

برای فراخوانی زنده این اندپوینت‌ها یک کلید API را بچسبانید. کلید در همین تب مرورگر می‌ماند و تنها به خود API فرستاده می‌شود.

Enter your API key to use the interactive playground. Get your API key

یک اندپوینت انتخاب کنید

Enter your API key above to try this endpoint.

Response will appear here after sending a request.

کاوشگر کاتالوگ

Catalog Explorer

Browse the product hierarchy and copy IDs for use in API calls.

Enter your API key above to browse the catalog.

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

مرجع API کاتالوگ — دسته‌ها، محصولات و قیمت‌ها