Pedidos
y su estado

Listar pedidos

GET /api/v1/external/orders

Devuelve los pedidos del tenant, paginados, con filtros opcionales. Requiere scope orders:read.

Query parameters

Request

curl "https://api.nuvlyx.com/api/v1/external/orders?status=COMPLETED&limit=10" \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Response 200

{
  "data": [
    {
      "id": "f3a1…",
      "orderNumber": "ORD-001234",
      "status": "COMPLETED",
      "totalAmount": "10000.00",
      "currencyCode": "COP",
      "createdAt": "2026-05-17T18:42:12.000Z",
      "user": { "id": "…", "name": "Juan Pérez", "phone": "+573001234567" },
      "items": [
        { "id": "…", "variationId": "…", "pricePaid": "10000.00", "status": "DELIVERED" }
      ]
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 47 }
}

Detalle de un pedido

GET /api/v1/external/orders/:id

Devuelve un pedido específico con todas sus items, instrucciones post-venta y, si fueron entregadas, las credenciales de las licencias asignadas (desencriptadas). Requiere scope orders:read.

Request

curl https://api.nuvlyx.com/api/v1/external/orders/f3a1… \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Seguridad: las credenciales solo se envían sobre HTTPS y nunca se incluyen en logs. Trate la respuesta como información sensible.

Crear un pedido

POST /api/v1/external/orders

Crea un pedido en nombre de un cliente. El cliente se identifica por customerId o por customerPhone (E.164, debe estar vinculado en su perfil). Requiere scope orders:write.

Forma de pago: el monedero del cliente. Si el saldo no alcanza para el total, la API responde 400 con un mensaje claro — recargue primero el monedero con POST /external/customers/:id/wallet/recharge y reintente.

Body

curl -X POST https://api.nuvlyx.com/api/v1/external/orders \
  -H "Authorization: Bearer nvl_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerPhone": "+573001234567",
    "items": [
      { "variationId": "abc12345-…" },
      { "variationId": "abc12345-…" }
    ]
  }'

{
  "orderId": "f3a1…",
  "orderNumber": "ORD-001234",
  "status": "COMPLETED",
  "totalAmount": "20000.00",
  "newBalance": "5000.00"
}