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

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

GET

/catalog/big-categories

List Big Categories

Get all top-level categories (e.g., Mobile Games, PC Games, Gift Cards).

محدودیت نرخ80 req / 60s per user (shared across all catalog endpoints)

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

نامنوعالزامیتوضیحنمونه
for_uibooleanخیرInclude image URLs in the response.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

List Categories

Get categories, optionally filtered by big category. Each category represents a game or service.

محدودیت نرخ80 req / 60s per user (shared across all catalog endpoints)

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

نامنوعالزامیتوضیحنمونه
bigCategoryIdnumberخیرFilter by big category ID.1
for_uibooleanخیرInclude image URLs in the response.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

List Subcategories (Products)

Get available products/denominations. Each subcategory is a purchasable item.

محدودیت نرخ80 req / 60s per user (shared across all catalog endpoints)

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

نامنوعالزامیتوضیحنمونه
categoryIdnumberخیرFilter by category ID.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",
      "fulfillment_type": "api",
      "returns_voucher": false
    }
  ]
}
GET

/catalog/subcategory/:itemId/price

Get Item Price

Get the current discounted price for a specific subcategory/item. Use this before creating an order to know the exact cost.

محدودیت نرخ80 req / 60s per user (shared across all catalog endpoints)

نکته: The unit_price is what you will be charged. Use this value for expected_unit_price when creating orders.

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

نامنوعالزامیتوضیحنمونه
itemIdnumberبلهThe subcategory/item ID.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

Get Category Requirements

Get the dynamic requirement fields for a specific category. These fields describe what information is needed when validating a player or creating an order (e.g., player ID, server, region).

محدودیت نرخ80 req / 60s per user (shared across all catalog endpoints)

نکته: Use the returned fields to build dynamic forms for player validation and order creation. Each field specifies its data_type (text, number, single_select, multi_select) and available options for select fields.

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

نامنوعالزامیتوضیحنمونه
categoryIdnumberبلهThe category ID to get requirements for.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 کاتالوگ — دسته‌ها، محصولات و قیمت‌ها