Endpoint danh mục

Danh mục có cấu trúc cây ba cấp: danh mục lớn chứa danh mục, danh mục chứa danh mục con, và danh mục con là mặt hàng bạn thực sự mua. Các endpoint này giúp bạn sao chép cây đó vào cơ sở dữ liệu của mình và lấy giá một mặt hàng ngay trước khi đặt đơn.

GET

/catalog/big-categories

Danh sách danh mục lớn

Trả về toàn bộ danh mục cấp cao nhất (ví dụ: Game mobile, Game PC, Thẻ quà tặng).

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản (dùng chung cho mọi endpoint danh mục sản phẩm)

Tham số query

TênKiểuBắt buộcMô tảVí dụ
for_uibooleanKhôngTrả kèm URL hình ảnh trong phản hồi.true
Yêu cầu
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/big-categories?for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
Phản hồi mẫu
{
  "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

Danh sách danh mục

Lấy danh mục, có thể lọc theo danh mục lớn. Mỗi danh mục là một game hoặc dịch vụ.

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản (dùng chung cho mọi endpoint danh mục sản phẩm)

Tham số query

TênKiểuBắt buộcMô tảVí dụ
bigCategoryIdnumberKhôngLọc theo ID danh mục lớn.1
for_uibooleanKhôngTrả kèm URL hình ảnh trong phản hồi.true
Yêu cầu
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1&for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
Phản hồi mẫu
{
  "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

Danh sách danh mục con (sản phẩm)

Danh sách sản phẩm/mệnh giá hiện có. Mỗi danh mục con là một mặt hàng có thể mua.

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản (dùng chung cho mọi endpoint danh mục sản phẩm)

Lưu ý: product_type là 'topup' khi sản phẩm nạp trực tiếp vào tài khoản người chơi và 'voucher' khi sản phẩm giao mã. fulfillment_type ('api' khi nạp trực tiếp, 'voucher' khi giao mã) và returns_voucher (true khi giao mã) đã lỗi thời vì chỉ lặp lại thông tin của product_type. Nếu có trường id, giá trị của trường này bằng item_id.

Tham số query

TênKiểuBắt buộcMô tảVí dụ
categoryIdnumberKhôngLọc theo ID danh mục.12
Yêu cầu
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategories?categoryId=12" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
Phản hồi mẫu
{
  "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

Lấy giá sản phẩm

Lấy giá đã giảm hiện tại của một danh mục con/sản phẩm. Gọi endpoint này trước khi tạo đơn để biết chính xác số tiền phải trả.

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản (dùng chung cho mọi endpoint danh mục sản phẩm)

Lưu ý: unit_price là đơn giá bạn sẽ phải trả. Dùng giá trị này cho expected_unit_price khi tạo đơn hàng.

Tham số đường dẫn

TênKiểuBắt buộcMô tảVí dụ
itemIdnumberCóID danh mục con/sản phẩm.999
Yêu cầu
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategory/999/price" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
Phản hồi mẫu
{
  "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

Lấy trường yêu cầu của danh mục

Trả về các trường yêu cầu động của một danh mục. Các trường này cho biết cần thông tin gì khi kiểm tra người chơi hoặc tạo đơn hàng (ví dụ: ID người chơi, server, khu vực).

Giới hạn tần suất5000 yêu cầu / 60 giây mỗi tài khoản (dùng chung cho mọi endpoint danh mục sản phẩm)

Lưu ý: Dùng các trường trả về để dựng form động cho bước kiểm tra người chơi và tạo đơn. Mỗi trường có data_type (text, number, single_select, multi_select), còn trường dạng chọn sẽ kèm danh sách lựa chọn.

Tham số đường dẫn

TênKiểuBắt buộcMô tảVí dụ
categoryIdnumberCóID danh mục cần lấy trường yêu cầu.12
Yêu cầu
curl -s "https://shop2topup.com/api/endpoints/v1/catalog/category/12/requirements" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"
Phản hồi mẫu
{
  "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"
      ]
    }
  ]
}

Gửi yêu cầu thật ngay trên trang này

Dán khóa API để gọi trực tiếp các endpoint này. Khóa chỉ nằm trong tab trình duyệt này và chỉ được gửi tới chính API.

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

Chọn endpoint

Enter your API key above to try this endpoint.

Response will appear here after sending a request.

Duyệt danh mục

Catalog Explorer

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

Enter your API key above to browse the catalog.

Nếu bạn mới dùng nền tảng, hãy bắt đầu với trang tổng quan API nạp game dành cho đại lý, hoặc đọc tổng quan chương trình đại lý SHOP2TOPUP để biết tài khoản đối tác hoạt động ra sao.

Tài liệu API danh mục: danh mục lớn, danh mục và giá