Endpoints del catálogo

El catálogo es un árbol de tres niveles: las grandes categorías contienen categorías, las categorías contienen subcategorías, y una subcategoría es el artículo que realmente se compra. Estos endpoints le permiten replicar ese árbol en su propia base de datos y consultar el precio de un artículo justo antes de pedirlo.

GET

/catalog/big-categories

Listar categorías principales

Obtén todas las categorías de nivel superior (por ejemplo, Juegos móviles, Juegos de PC, Tarjetas de regalo).

Límite de solicitudes5000 solicitudes / 60 s por cuenta (límite compartido por todos los endpoints del catálogo)

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
for_ui	boolean	No	Incluye las URL de las imágenes en la respuesta.	true

Solicitud

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

Respuesta de ejemplo

{
  "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

Listar categorías

Devuelve las categorías, con filtro opcional por categoría principal. Cada categoría corresponde a un juego o servicio.

Límite de solicitudes5000 solicitudes / 60 s por cuenta (límite compartido por todos los endpoints del catálogo)

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
bigCategoryId	number	No	Filtra por ID de categoría principal.	1
for_ui	boolean	No	Incluye las URL de las imágenes en la respuesta.	true

Solicitud

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

Respuesta de ejemplo

{
  "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

Listar subcategorías (productos)

Consulta los productos y denominaciones disponibles. Cada subcategoría es un artículo que se puede comprar.

Límite de solicitudes5000 solicitudes / 60 s por cuenta (límite compartido por todos los endpoints del catálogo)

Nota: product_type vale 'topup' para una recarga directa a la cuenta del jugador y 'voucher' para un producto que entrega un código. fulfillment_type ('api' para una recarga, 'voucher' para un código) y returns_voucher (true para un código) están obsoletos: solo repiten product_type. Cuando aparece un campo id, su valor es igual a item_id.

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
categoryId	number	No	Filtra por ID de categoría.	12

Solicitud

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategories?categoryId=12" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Respuesta de ejemplo

{
  "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

Obtener precio del ítem

Obtén el precio actual con descuento de una subcategoría o artículo específico. Úsalo antes de crear un pedido para saber el costo exacto.

Límite de solicitudes5000 solicitudes / 60 s por cuenta (límite compartido por todos los endpoints del catálogo)

Nota: unit_price es lo que se te cobrará. Usa este valor en expected_unit_price al crear pedidos.

Parámetros de ruta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
itemId	number	Sí	ID de la subcategoría o artículo.	999

Solicitud

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategory/999/price" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Respuesta de ejemplo

{
  "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

Obtener requisitos de la categoría

Trae los campos de requisitos dinámicos de una categoría específica. Estos campos indican qué datos se necesitan para validar a un jugador o crear un pedido (por ejemplo, ID del jugador, servidor, región).

Límite de solicitudes5000 solicitudes / 60 s por cuenta (límite compartido por todos los endpoints del catálogo)

Nota: Usa los campos devueltos para generar formularios dinámicos de validación de jugadores y creación de pedidos. Cada campo indica su data_type (text, number, single_select, multi_select) y las opciones disponibles para los campos de selección.

Parámetros de ruta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
categoryId	number	Sí	ID de la categoría cuyos requisitos quieres obtener.	12

Solicitud

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/category/12/requirements" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Respuesta de ejemplo

{
  "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"
      ]
    }
  ]
}

Envíe una solicitud real desde esta página

Pegue una clave de API para llamar a estos endpoints en vivo. La clave se queda en esta pestaña del navegador y solo se envía a la propia API.

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

Elija un endpoint

Include images (for_ui=true)

Enter your API key above to try this endpoint.

Response will appear here after sending a request.

Explorador del catálogo

Catalog Explorer

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

Enter your API key above to browse the catalog.

¿Recién llega a la plataforma? Empiece por la presentación de la API de recargas de juegos para revendedores, o lea la presentación del programa de revendedores de SHOP2TOPUP para ver cómo funciona la cuenta de socio.