Pedidos

Flujo general de pedido

El ciclo recomendado es:

1. Consultas el detalle del servicio.
2. Construyes el formulario según inputSchema.
3. Creas el pedido con POST /api/v1/orders.
4. Guardas orderId, requestId y tu referencia interna.
5. Consultas detalle o estado hasta resolución final.

POST /api/v1/orders

Crea un pedido con el precio final ya calculado para tu cuenta API.

Headers recomendados

Authorization: Bearer clx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Idempotency-Key: ik_01K5CB0V2N8M7Q6W5E4R3T2Y1U
Content-Type: application/json

Body de ejemplo

{
  "serviceId": "srv_01K5CB4D6F7G8H9J0K1L2M3N4P",
  "clientReference": "sale_20260319_000101",
  "inputs": {
    "IMEI": "352099001761482"
  }
}

Qué significa cada campo

• serviceId: ID público del servicio en CelMex.
• clientReference: referencia opcional de tu propio sistema.
• inputs: objeto con los campos requeridos por ese servicio.

Ejemplo de pedido con recarga

{
  "serviceId": "srv_01K5CB7V8B9N0M1Q2W3E4R5T6Y",
  "clientReference": "topup_20260319_000044",
  "inputs": {
    "number": "5550000002",
    "amount": "20"
  }
}

Idempotencia

Si tu infraestructura reintenta requests por timeout o red, usa siempre Idempotency-Key.

Eso evita pedidos duplicados cuando tu servidor reenvía la misma operación.

Qué es Idempotency-Key

Es una llave única que tú generas en tu backend para identificar un intento de creación de pedido.

No la genera CelMex.

Cómo generarla

Puedes usar cualquier identificador único generado por tu sistema. Recomendaciones comunes:

• UUID
• ULID
• NanoID
• un identificador propio con prefijo, por ejemplo ik_...

Ejemplo válido:

Idempotency-Key: ik_01K5CB0V2N8M7Q6W5E4R3T2Y1U

Cuándo reutilizar la misma llave

Reutiliza la misma Idempotency-Key solo cuando estés reintentando exactamente el mismo pedido con el mismo payload.

Cuándo usar una llave nueva

Genera una nueva Idempotency-Key cuando:

• cambia el serviceId;
• cambia cualquier campo dentro de inputs;
• cambia tu clientReference;
• se trata de una venta nueva.

Ejemplo de respuesta exitosa

{
  "success": true,
  "requestId": "req_01K5CBC7D8F9G0H1J2K3L4M5N6",
  "timestamp": "2026-03-19T16:35:42.123Z",
  "data": {
    "order": {
      "orderId": "ord_01K5CBF9P8O7I6U5Y4T3R2E1W0",
      "clientReference": "sale_20260319_000101",
      "status": "PROCESSING",
      "supplierStatus": null,
      "supplierReference": "ext_demo_48291",
      "refunded": false,
      "quantity": 1,
      "totalPaid": 149.90,
      "currency": "MXN",
      "createdAt": "2026-03-19T16:35:42.123Z",
      "resolvedAt": null,
      "service": {
        "serviceId": "srv_01K5CB4D6F7G8H9J0K1L2M3N4P",
        "name": "Premium Android Remote Unlock",
        "type": "REMOTE"
      }
    },
    "submission": {
      "accepted": true,
      "pendingVerification": false,
      "reference": "ext_demo_48291",
      "message": "Order accepted successfully."
    }
  }
}

Estados de pedido

Los estados más comunes que debes esperar son:

• PENDING: el pedido fue creado pero aún no enviado.
• PROCESSING: fue enviado y sigue en proceso.
• COMPLETED: se resolvió correctamente.
• FAILED: terminó en rechazo o error terminal.
• REJECTED: rechazo explícito del proveedor o flujo interno.

Qué hacer con cada estado

GET /api/v1/orders

Lista los pedidos creados por la cuenta API actual.

Úsalo para:

• mostrar historial en tu panel;
• sincronizar pedidos con tu sistema;
• construir vistas de soporte;
• reconciliar ventas de un periodo.

GET /api/v1/orders/:orderId

Devuelve el detalle completo del pedido.

Este endpoint está pensado para que puedas construir una vista similar a la ficha de pedido de CelMex, incluyendo:

• servicio;
• precio unitario y total;
• inputs enviados;
• respuesta del proveedor o partner;
• eventos de estado;
• timestamps operativos;
• referencias.

GET /api/v1/orders/:orderId/status

Devuelve una vista resumida del estado actual.

Es útil cuando solo quieres refrescar:

• un badge de estado;
• una tabla de pedidos;
• una vista rápida de seguimiento.

Qué debes guardar en cada pedido

Para operar bien y auditar tu integración, guarda siempre:

• orderId
• requestId
• clientReference
• serviceId
• payload enviado
• respuesta recibida
• timestamps del flujo

Recomendación de implementación

Si tu sistema hace ventas automáticamente:

• crea el pedido con idempotencia;
• guarda la respuesta completa;
• refresca el estado hasta resolución final;
• no crees un segundo pedido solo porque el frontend se quedó esperando.