Documentación de la APIVersión 1

Comprobación de vida, sin autenticar. Sirve para monitoreo.

curl https://portal.centraloneglobal.com/api/v1/health

{ "status": "ok", "request_id": "..." }

Prueba autenticada. Confirma que tu llave sirve. No devuelve ningún dato de negocio.

curl https://portal.centraloneglobal.com/api/v1/ping \
  -H "Authorization: Bearer $CO_API_KEY"

{ "ok": true, "request_id": "..." }

Los productos habilitados para ti, con tu precio. Un producto que no tienes habilitado no aparece.

• product_id es el valor que mandas como catalog_item_id al crear un pedido. Es el mismo identificador con dos nombres: uno nombra el producto y el otro la línea que estás comprando.
• Guarda el catálogo en tu sistema y actualízalo cada cierto tiempo; cada 15 minutos alcanza. No lo pidas en cada visita de un comprador: vas a alcanzar el límite de 60 peticiones por minuto.
• Los precios siguen el costo del proveedor, así que cambian durante el día, a veces varias veces. Una copia de hace un día puede estar lejos del precio real. price_updated_at dice cuándo se fijó el precio actual; si tu copia es anterior, actualízala. updated_at es la fecha del registro del producto, no la del precio. En cualquier caso, lo que se cobra es el total_sale_amount que devuelve POST /orders.
• in_stock dice si el producto se puede comprar ahora. available_stock es cuántas unidades hay; null significa que el proveedor no informa cantidad: no se sabe, que no es lo mismo que cero. Usa in_stock para decidir si ofreces el producto, y available_stock sólo como tope cuando trae un número. El stock sale de la última lectura del proveedor, así que un pedido igual puede recibir 409 insufficient_stock.
• Agrupa por product_family_id, nunca parseando el nombre ni el SKU. Todos los productos de Free Fire traen el mismo product_family_id, así que puedes mostrar un juego con sus denominaciones debajo. El nombre lo escribe el proveedor y cambia; el formato del SKU a propósito no es un contrato.
• product_family_id se deriva del nombre de la familia, no es una clave permanente. Si un proveedor renombra la familia, el id cambia con ella. Úsalo para agrupar el catálogo que acabas de pedir; no lo guardes como clave fija de tu lado.
• requires_target y target_fields te dicen qué necesita el producto para poder entregarse. false con la lista vacía es que no necesita nada: una gift card se entrega sin datos del comprador. true significa que cada nombre de la lista es una clave OBLIGATORIA dentro de items[].target_payload al crear el pedido. target_schema es esa misma lista con lo que cada campo acepta de verdad: el tipo "text" es texto libre, y el tipo "select" significa que el proveedor sólo acepta los valores de sus options — se manda el value de la opción, no su label. Cualquier otro valor falla en el proveedor, con el pedido ya cobrado. target_fields sigue funcionando igual que siempre; target_schema se agrega.
• Léelos por producto, no los escribas fijos. Hoy conviven varias formas en el catálogo vivo — game_user_id sola, game_user_id más game_zone_id, player_id, player_id más server, user_id más region — las define cada proveedor al publicar y cambian producto por producto. Una lista copiada en tu código se desactualiza en silencio y te enteras cuando una compra falla.
• Si mandas un target_payload al que le falta un campo obligatorio, el pedido se rechaza antes de que se mueva dinero: no se retiene ni se cobra nada.
• Los precios traen CUATRO decimales y viajan como texto. No los redondees a dos: el margen vive en el tercer y cuarto decimal, así que 0,7010 redondeado a 0,70 es un error de 0,14% — más que el margen entero de ese producto.

curl https://portal.centraloneglobal.com/api/v1/catalog \
  -H "Authorization: Bearer $CO_API_KEY"

{
  "items": [
    {
      "product_id": "11111111-2222-3333-4444-555555555555",
      "sku": "STEAM-GC-10",
      "name": "Steam Gift Card 10 USD",
      "category": "gift_card",
      "product_type": "gift_card",
      "market": "GLOBAL",
      "region": "GLOBAL",
      "currency": "USD",
      "reseller_price": "24.9975",
      "status": "active",
      "updated_at": "2026-08-28T14:03:11.482913Z",
      "product_family_id": "steam",
      "product_family_name": "Steam",
      "requires_target": false,
      "target_fields": [],
      "target_schema": [],
      "in_stock": true,
      "available_stock": 152,
      "price_updated_at": "2026-10-01T20:16:17.160858Z"
    },
    {
      "product_id": "22222222-3333-4444-5555-666666666666",
      "sku": "ML-100-DIAMONDS",
      "name": "Mobile Legends 100 Diamonds",
      "category": "gaming_topup",
      "product_type": "game_topup",
      "market": "GLOBAL",
      "region": "GLOBAL",
      "currency": "USD",
      "reseller_price": "1.9013",
      "status": "active",
      "updated_at": "2026-09-17T11:20:04.118273Z",
      "product_family_id": "mobile-legends",
      "product_family_name": "Mobile Legends",
      "requires_target": true,
      "target_fields": ["player_id", "server"],
      "target_schema": [
        { "key": "player_id", "label": "Player ID", "type": "text", "options": null },
        {
          "key": "server",
          "label": "Server",
          "type": "select",
          "options": [
            { "value": "os_usa", "label": "America" },
            { "value": "os_euro", "label": "Europe" },
            { "value": "os_asia", "label": "Asia" }
          ]
        }
      ],
      "in_stock": true,
      "available_stock": null,
      "price_updated_at": "2026-10-02T09:00:34.222519Z"
    }
  ]
}

Tu saldo, en exactamente cuatro campos.

• held_balance es el dinero retenido por pedidos en curso. Un pedido nuevo se paga contra available_balance, no contra total_balance.
• Todos los importes de la API son strings con cuatro decimales, nunca números de punto flotante. Parsea con una librería decimal, no con parseFloat. Cuatro y no dos: los precios se guardan con cuatro decimales y ahí vive el margen — un precio de "0.7010" devuelto como "0.70" se va por 0,14%, que es más que el margen completo del producto.

curl https://portal.centraloneglobal.com/api/v1/balance \
  -H "Authorization: Bearer $CO_API_KEY"

{
  "available_balance": "470.00",
  "held_balance": "30.00",
  "total_balance": "500.00",
  "currency": "USD"
}

Crea un pedido, retiene el saldo y reserva el inventario en una sola transacción.

• La cabecera Idempotency-Key es obligatoria. Ver la sección de Idempotencia más abajo.
• No existe ningún campo de precio. El importe lo calcula el servidor leyendo el catálogo. Una línea que traiga un campo desconocido (price, total, reseller_id) se rechaza entera con 400, en vez de ignorarlo en silencio: si lo ignorara, creerías que compraste a un precio que nunca cotizaste.
• Límites de la petición: cuerpo máximo 16 KB, Content-Type: application/json.

curl -X POST https://portal.centraloneglobal.com/api/v1/orders \
  -H "Authorization: Bearer $CO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2026-08-28-000123" \
  -d '{
        "items": [
          { "catalog_item_id": "11111111-2222-3333-4444-555555555555",
            "quantity": 2 },
          { "catalog_item_id": "22222222-3333-4444-5555-666666666666",
            "quantity": 1,
            "target_payload": { "game_user_id": "123456789",
                                "game_zone_id": "2001" } }
        ],
        "note": "pedido del cliente 42"
      }'

{
  "order": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "reference_code": "CO-ORD-20260828-A1B2C3",
    "status": "confirmed",
    "total_sale_amount": "50.00",
    "currency": "USD",
    "created_at": "2026-08-28T14:03:11.482913Z"
  }
}

Tus pedidos, del más reciente al más antiguo.

• Paginación: si next_cursor es una cadena, pide la siguiente página con ?cursor=<ese valor>. Cuando llega null, terminaste. El cursor es opaco y se valida byte a byte: no lo construyas ni lo modifiques.
• Un status inválido, un limit fuera de rango o un cursor manipulado invalidan TODA la petición con 400. No se ignoran en silencio.

curl "https://portal.centraloneglobal.com/api/v1/orders?limit=10&status=confirmed,processing" \
  -H "Authorization: Bearer $CO_API_KEY"

{
  "orders": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "reference_code": "CO-ORD-20260828-A1B2C3",
      "status": "confirmed",
      "total_sale_amount": "50.00",
      "currency": "USD",
      "line_count": 1,
      "reseller_note": "pedido del cliente 42",
      "created_at": "2026-08-28T14:03:11.482913Z",
      "updated_at": "2026-08-28T14:03:11.482913Z"
    }
  ],
  "pagination": { "limit": 10, "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..." }
}

Un pedido con sus líneas. Este es el endpoint de estado: el que consultas después de crear un pedido.

• delivered_count te dice si esta línea tiene códigos esperando. 0 significa que no entrega ninguno — una recarga directa al ID del jugador no deja nada que revelar. Mayor que 0 significa que hay esa cantidad esperando en GET /orders/{id}/codes.
• Los códigos NO vienen en esta respuesta, a propósito. Un código es valor al portador: quien lo lee puede canjearlo. Vive detrás de su propio permiso y cada revelación queda registrada.

curl https://portal.centraloneglobal.com/api/v1/orders/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  -H "Authorization: Bearer $CO_API_KEY"

{
  "order": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "reference_code": "CO-ORD-20260828-A1B2C3",
    "status": "confirmed",
    "total_sale_amount": "50.00",
    "currency": "USD",
    "line_count": 1,
    "reseller_note": "pedido del cliente 42",
    "created_at": "2026-08-28T14:03:11.482913Z",
    "updated_at": "2026-08-28T14:03:11.482913Z",
    "items": [
      {
        "id": "cccccccc-dddd-eeee-ffff-000000000000",
        "product_sku": "STEAM-GC-10",
        "product_name": "Steam Gift Card 10 USD",
        "category": "gift_card",
        "product_type": "gift_card",
        "region": "GLOBAL",
        "quantity": 2,
        "unit_sale_price": "25.00",
        "total_sale_price": "50.00",
        "status": "reserved",
        "created_at": "2026-08-28T14:03:11.482913Z",
        "delivered_count": 0
      }
    ]
  }
}

Los códigos que compraste: códigos de gift card y PIN. Aquí es donde se entrega el producto.

• Pídelo cuando GET /orders/{id} muestre delivered_count mayor que 0 en una línea. Solo las líneas completed tienen códigos; una que sigue en reserved o processing todavía no tiene nada.
• Necesita el scope codes:read, que es el ÚNICO permiso que no viene marcado al emitir una llave. Si vendes gift cards o PIN lo necesitas — pídelo y di para qué. Sin él este endpoint responde 403 insufficient_scope.
• Cada llamada queda en la auditoría, con qué llave leyó qué pedido. Es a propósito: es el registro de quién manipuló un código que se canjea una sola vez.
• Algunos proveedores devuelven el PIN junto con un serial. En ese caso el código llega como "PIN - SERIAL": la primera parte es la que canjea tu cliente, la segunda es el número de control del proveedor.

curl https://portal.centraloneglobal.com/api/v1/orders/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/codes   -H "Authorization: Bearer $CO_API_KEY"

{
  "order": {
    "order_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "reference_code": "CO-ORD-20260828-A1B2C3",
    "items": [
      {
        "id": "cccccccc-dddd-eeee-ffff-000000000000",
        "product_sku": "FF-110-DIAMONDS-PIN",
        "product_name": "Free Fire 110 Diamonds (PIN)",
        "product_type": "game_topup",
        "status": "completed",
        "quantity": 1,
        "delivered_at": "2026-09-18T22:04:42.312387Z",
        "codes": ["A995E04D-6980-42AA-9488-BF88039B1C3D - 80980592"]
      }
    ]
  }
}