Documentación de la API para revendedores

La API para revendedores de SHOP2TOPUP es una API REST JSON para vender recargas de juegos y códigos de gift card desde su propia tienda, sitio o bot. Esta referencia documenta cada endpoint público, sus parámetros y sus respuestas.

URL base y transporte

Todas las rutas de esta referencia son relativas a la URL base de abajo. Las solicitudes y respuestas son JSON sobre HTTPS, los importes son cadenas de texto para que no se cuele ningún redondeo de coma flotante, y toda marca de tiempo está en UTC con formato ISO 8601.

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

Autenticación

Cada solicitud lleva un único encabezado. El par de claves se emite desde la página API Access de su panel de revendedor y se puede restringir a una lista de IP permitidas; una llamada desde cualquier otra dirección se rechaza con IP_NOT_ALLOWED antes de llegar a cualquier lógica de negocio.

Encabezado de la solicitud

Authorization: Bearer <keyId>.<secret>

Una primera llamada

Nada que instalar. Ponga su propia clave y esto devuelve datos del catálogo en vivo.

Solicitud - cURL

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

Convenciones de respuesta

Cada respuesta lleva un campo booleano success, así que una sola condición separa el camino feliz de cualquier fallo.
Los fallos devuelven un objeto error con un código estable, un mensaje legible y detalles opcionales. Ramifique según el código, nunca según el mensaje.
El dinero siempre es una cadena decimal, por ejemplo "0.950000" en USD. No lo convierta a un flotante binario antes de compararlo o sumarlo.
Los endpoints de lista devuelven un objeto pagination con page, limit, total y total_pages.
La creación de pedidos es idempotente sobre el UUID de order_id que usted proporciona, así que un reintento nunca puede cobrar dos veces.

Respuesta de error

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

Secciones de la referencia

CatálogoEl 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.Validación de jugadorLa validación de jugador resuelve una cuenta dentro del juego antes de mover dinero. Confirma que el identificador existe para ese producto, devuelve el nombre dentro del juego para que su comprador lo revise, y expone la región para que un pedido de otra región se rechace temprano en lugar de fallar después del pago.PedidosLos pedidos se crean con un UUID que usted genera. Ese UUID es la clave de idempotencia: repetirlo devuelve el pedido original en lugar de cobrar dos veces. El estado se consulta después pedido por pedido, en lotes de hasta cincuenta, o como una lista paginada.Cuenta y autenticaciónCada solicitud lleva un único encabezado. GET /account es el endpoint al que llama para comprobar que una clave funciona, leer el saldo de la billetera de la que salen sus pedidos y confirmar que la cuenta está habilitada antes de arrancar un proceso por lotes.Códigos de errorTodo fallo devuelve un código estable y legible por máquina junto al estado HTTP. Ramifique según el código, nunca según el texto del mensaje: los mensajes están escritos para personas y pueden reescribirse, mientras que los códigos forman parte del contrato.

Límites de solicitudes

Los límites son por cuenta sobre una ventana deslizante. Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, y una llamada limitada responde 429 con un encabezado Retry-After.

Ruta	Solicitudes	Ventana	Se cuentan por
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

Webhooks

Los resultados de los pedidos se envían a un endpoint HTTPS que usted registra, firmados con HMAC-SHA256 sobre el cuerpo crudo. La lista de eventos, la de encabezados, la forma del contenido y un fragmento de verificación están documentados en la página de presentación de la API.

Leer la referencia de contenido y firma de los webhooks

¿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.