Endpoints de pedidos

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

POST

/orders/create

Crear pedido

Haz un nuevo pedido. Debes enviar un UUID único como order_id para la idempotencia. El cargo a la billetera se hace de inmediato.

Límite de solicitudes5000 solicitudes / 60 s por cuenta

Nota: order_id es tu clave de idempotencia. Si reintentas con el mismo UUID, recibes el pedido existente en lugar de crear un duplicado.

Cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
order_id	string (UUID)	Sí	UUID único para este pedido (cualquier formato: v1, v4, v7, etc.). Se usa como clave de idempotencia.	01912345-6789-7abc-8def-0123456789ab
sub_category_id	number	Sí	ID de subcategoría del producto.	999
quantity	number	Sí	Cantidad de unidades a pedir (entero positivo).	1
requirements	object	Sí	Datos de entrega del jugador. Incluye todos los campos que devuelve el endpoint Obtener requisitos de la categoría.	{"player_id": "123456789", "server": "Asia"}
expected_unit_price	string	No	Protección de precio. Si el precio actual supera este valor, el pedido se rechaza.	0.950000

Solicitud

curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/create" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "01912345-6789-7abc-8def-0123456789ab",
  "sub_category_id": 999,
  "quantity": 1,
  "requirements": {
    "player_id": "123456789",
    "server": "Asia"
  },
  "expected_unit_price": 0.95
}'

Respuesta de ejemplo

{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "pending",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z"
  }
}

GET

/orders/:orderId

Consultar estado del pedido

Revisa el estado actual y los detalles de un pedido específico.

Límite de solicitudes3 solicitudes / 60 s por cuenta + order_id

Nota: El estado del pedido puede ser pending, completed, refunded o partial (partial = algunas unidades se entregaron y el resto se reembolsó). Cada sub_transactions[].status puede ser pending, completed o refunded; una unidad sigue en pending hasta que se entrega o se reembolsa. El campo sub_transactions[].id es el índice de la unidad dentro del pedido (1…n), no un id de base de datos. Si aparecen retry_count y max_retries, están obsoletos y siempre valen 0.

Parámetros de ruta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
orderId	string (UUID)	Sí	ID del pedido que quieres consultar.	01912345-6789-7abc-8def-0123456789ab

Solicitud

curl -s "https://shop2topup.com/api/endpoints/v1/orders/01912345-6789-7abc-8def-0123456789ab" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Respuesta de ejemplo

{
  "success": true,
  "order": {
    "order_id": "01912345-6789-7abc-8def-0123456789ab",
    "status": "completed",
    "player_id": "123456789",
    "player_name": "ProGamer99",
    "subcategory_name": "FF 100 Diamonds",
    "quantity": 1,
    "charged_amount": "0.950000",
    "currency": "USD",
    "created_at": "2024-06-15T12:00:00Z",
    "completed_at": "2024-06-15T12:00:05Z",
    "vouchers": [],
    "sub_transactions": [
      {
        "id": 1,
        "status": "completed",
        "player_id": "123456789",
        "player_name": "ProGamer99",
        "amount": "0.950000",
        "created_at": "2024-06-15T12:00:00Z",
        "completed_at": "2024-06-15T12:00:05Z"
      }
    ]
  }
}

POST

/orders/batch

Consultar pedidos en lote

Recupera varios pedidos a la vez por sus ID. Máximo 50 ID de pedido por solicitud.

Límite de solicitudes2 solicitudes / 60 s por cuenta

Cuerpo de la solicitud

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
order_ids	string[]	Sí	Array de UUID de pedidos (máximo 50).	["uuid-1", "uuid-2"]

Solicitud

curl -s -X POST "https://shop2topup.com/api/endpoints/v1/orders/batch" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "order_ids": [
    "uuid-1",
    "uuid-2"
  ]
}'

Respuesta de ejemplo

{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "charged_amount": "0.950000"
    }
  ],
  "not_found": [
    "uuid-that-does-not-exist"
  ]
}

GET

/orders

Listar pedidos

Lista tus pedidos con paginación y filtros opcionales por estado y rango de fechas.

Límite de solicitudes2 solicitudes / 60 s por cuenta

Parámetros de consulta

Nombre	Tipo	Obligatorio	Descripción	Ejemplo
page	number	No	Número de página (predeterminado: 1).	1
limit	number	No	Resultados por página, de 1 a 100 (por defecto: 50).	50
status	string	No	Filtra por estado: pending, completed, refunded, partial.	completed
created_after	string (ISO 8601)	No	Filtra los pedidos creados después de esta fecha.	2024-01-01T00:00:00Z
created_before	string (ISO 8601)	No	Filtra los pedidos creados antes de esta fecha.	2024-12-31T23:59:59Z

Solicitud

curl -s "https://shop2topup.com/api/endpoints/v1/orders?page=1&limit=50&status=completed&created_after=2024-01-01T00:00:00Z&created_before=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Respuesta de ejemplo

{
  "success": true,
  "orders": [
    {
      "order_id": "01912345-6789-7abc-8def-0123456789ab",
      "status": "completed",
      "subcategory_name": "FF 100 Diamonds",
      "quantity": 1,
      "charged_amount": "0.950000",
      "created_at": "2024-06-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "total_pages": 1
  }
}

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

Order Details

Enter your API key above to try this endpoint.

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