CoboxCobox
API Docs

Documentación de la API

Un único endpoint REST para todos los módulos. Cambia el campo action según la operación.

POST https://plataforma.coboxlogistic.com/functions/coboxApi

🔑 Tu API Key (para probar endpoints protegidos)

Obtén tu API Key en el panel → API & Webhooks.

La API de Cobox usa un único endpoint POST al que se le indica la operación mediante el campo action. Compatible con cualquier lenguaje o plataforma.

🔗 Endpoint único

Toda la API usa un único endpoint. Cambia el campo action para indicar la operación.

POST https://plataforma.coboxlogistic.com/functions/coboxApi

🔑 Autenticación

Los endpoints protegidos requieren una API Key en el header HTTP.

# Header requerido para endpoints protegidos:
X-API-Key: TU_API_KEY_AQUI
orders.readLeer pedidos
orders.createCrear pedidos
tracking.readConsultar tracking
webhooks.manageGestionar webhooks

🌎 Países de operación — operation_country

Cada pedido debe indicar el país mediante operation_country. Esto enruta el pedido al equipo correcto y aplica la moneda local para tarifas y cotizaciones.Campo obligatorio en orders.create y orders.quote.

🇵🇪PE
PerúPEN (Soles)
🇪🇸ES
EspañaEUR (Euros)
🇵🇹PT
PortugalEUR (Euros)
🇨🇴CO
ColombiaCOP (Pesos)
🇪🇨EC
EcuadorUSD (Dólares)
🇵🇾PY
ParaguayPYG (Guaraníes)
⚠️ Importante: Si no envías operation_country, el pedido se asigna por defecto a PE (Perú). Para integraciones multi-país, siempre envía este campo explícitamente.

📦 Estados de pedido y eventos webhook

cotizacionorder.createdPedido creado (inicial)
programadoorder.scheduledProgramado para recojo
confirmadoorder.confirmedConfirmado por operaciones
listo_para_recojoorder.ready_for_pickupListo — transportista va a recoger🔔
recogidoorder.picked_upRecogido por transportista🔔
en_transitoorder.in_transitEn tránsito hacia destino🔔
en_agenciaorder.at_agencyPaquete llegó a agencia destino🔔
listo_para_recojo_agenciaorder.agency_readyListo para retirar en agencia/locker🔔
retirado_en_agenciaorder.agency_picked_upDestinatario retiró de agencia🔔
devuelto_por_vencimientoorder.agency_expiredVenció plazo de retiro en agencia🚨
entregadoorder.deliveredEntregado al destinatario🔔
incidenciaorder.incidentNovedad / incidencia registrada🚨
en_devolucionorder.return_in_progressDevolución en proceso🚨
devuelto_al_origenorder.returnedDevuelto al remitente🚨
canceladoorder.cancelledPedido cancelado🚨
cobro_pendienteorder.cod_pendingCOD pendiente de liquidar
liquidadoorder.settledLiquidado
—settlement.createdNueva liquidación generada (webhook)💰

💰 Webhooks financieros — COD, liquidaciones y controversias

Además de los eventos de estado de pedido, Cobox dispara webhooks para eventos financieros. Usa el campo commerce_id en cada payload para filtrar.

cod.collectedCOD cobrado por rider al entregar — pendiente de conciliación
Por pedido
cod.reconciledCOD confirmado tras incluirse en una liquidación de Cobox
Por pedido
settlement.createdNueva liquidación de comercio generada
Comercio
seller_settlement.createdLiquidación interna de vendedor creada (pendiente)
Vendedor
seller_settlement.paidLiquidación de vendedor marcada como pagada
Vendedor
rider_settlement.createdLiquidación de rider creada (pendiente)
Rider
rider_settlement.paidLiquidación de rider marcada como cobrada
Rider
controversy.openedControversia abierta por el comercio
Controversia
controversy.resolvedControversia resuelta por admin
Controversia
# Ejemplo: cod.collected
{
"event": "cod.collected",
"timestamp": "2026-06-30T14:00:00Z",
"data": {
"order_id": "abc123",
"order_number": "COBOX-1001",
"cod_amount_collected": 120.00,
"cod_status": "pending_reconciliation",
"commerce_id": "commerce-123"
}
}
💡 Filtros: Suscríbete a ["cod.*"] para recibir cod.collected + cod.reconciled, o ["seller_settlement.*"] para todos los eventos de vendedores.

👤 Account — Estado de tu cuenta

El endpoint orders.account devuelve el estado completo de tu cuenta: servicios activos, países de operación, plan de suscripción, saldo de billetera y crédito disponible.

# Request:
{ "action": "orders.account" }
# Response:
{
"success": true,
"account": {
"commerce_id": "...",
"company_name": "Mi Tienda",
"subscription_plan": "ecommerce",
"services": [
{ "key": "shipping", "name": "Envío última milla" },
{ "key": "call_center", "name": "Call Center" }
],
"operation_countries": ["PE"],
"wallet": {
"balance_pen": 1500.00,
"payment_type": "contado",
"credit_available": 0
}
}
}

💳 Wallet Status — Saldo segregado (contable vs. corriente)

El endpoint wallet.status devuelve el estado financiero segregado del comercio: saldo confirmado (disponible para retiro) y COD en proceso (cobrado por riders, pendiente de conciliación).

# Request:
{ "action": "wallet.status" }
# Response:
{
"success": true,
"wallet_status": {
"currency": "PEN",
"confirmed_balance": 1500.00,
"pending_cod_reconciliation": 450.50,
"pending_cod_orders_count": 3,
"total_in_process": 1950.50,
"last_update": "2026-06-30T14:00:00Z"
}
}

🏷️ Rótulo (Label) de envío

Cada pedido tiene un rótulo listo para imprimir. El enlace se devuelve en label_url.

# label_url incluido en orders.create y orders.get:
"label_url": "https://plataforma.coboxlogistic.com/Label?order_number=COBOX-1001"

🧑‍💼 ¿Quién vendió? — sold_by

El campo sold_by permite identificar si un pedido lo vendió la tienda directamente o un vendedor externo (remitente). Útil para marketplaces y comercios con equipo de ventas.

commerce
La tienda vendió

El comercio vendió directamente. sender_name es el remitente logístico (opcional).

seller
Un vendedor vendió

Un vendedor/remitente externo hizo la venta. sender_name y sender_phone identifican al vendedor.

# En orders.create y en el payload del webhook:
"sold_by": "seller",
"sender_name": "Carlos Rodríguez",
"sender_phone": "+51 987 654 321"
💡 rider_instructions: Cuando el rider agrega indicaciones durante la entrega (ej: solicitudes de contacto con el vendedor), se incluyen en el webhook y en orders.evidence.

🏪 Origen del envío — origin_warehouse_city

El campo origin_warehouse_city es el método preferido para definir el origen de un envío. El sistema resuelve automáticamente el almacén registrado del comercio en esa ciudad y usa su dirección y tipo.

Escenario 1 — Preferido

origin_warehouse_city enviado

El sistema busca el almacén del comercio en esa ciudad y usa su dirección + tipo automáticamente.

Escenario 2 — Libre

pickup_address + pickup_city enviados

Se trata como dirección externa libre (comportamiento clásico). origin_warehouse_type por defecto = propio.

Escenario 3 — Ninguno

Sin campos de origen

El pedido se crea sin dirección de recogida explícita. Operaciones asignará origen manualmente.

# Escenario 1: origin_warehouse_city (preferido)
{
"action": "orders.create",
"origin_warehouse_city": "Lima",
"recipient_name": "Juan Pérez",
"delivery_city": "Arequipa",
...
}
# El sistema resuelve el almacén del comercio en Lima y usa su dirección.
💡 Retrocompatibilidad: El campo origin_warehouse_type (propio|cobox) se sigue aceptando. Si se envía origin_warehouse_city, este se sobrescribe con el tipo del almacén resuelto.

📨 Webhooks — Payload recibido

Cuando ocurre un evento, tu servidor recibirá un POST con esta estructura:

X-Cobox-Event: order.picked_up
X-Cobox-Timestamp: 2024-01-15T14:30:00Z
X-Cobox-Signature: sha256=...

{
  "event": "order.picked_up",
  "timestamp": "2024-01-15T14:30:00Z",
  "delivery_id": "uuid-unico",
  "is_critical": true,
  "data": {
    "order_number": "COBOX-1001",
    "status": "recogido",
    "previous_status": "listo_para_recojo",
    "operation_country": "PE",
    "sold_by": "seller",
    "sender_name": "Carlos Rodríguez",
    "sender_phone": "+51 987 654 321",
    "carrier_name": "Carrier Asignado",
    "service_guide": "GUIA-123456",
    "label_url": "https://plataforma.coboxlogistic.com/Label?order_number=COBOX-1001",
    "tracking_url": "https://plataforma.coboxlogistic.com/PublicTracking?order=COBOX-1001",
    "rider_instructions": "Cliente solicita contactar al vendedor para confirmar talla",
    "updated_at": "2024-01-15T14:30:00Z"
  }
}
💡 Tip: Suscríbete a ["*"] para recibir todos los eventos, o lista los específicos que necesitas (🔔/🚨).

🎫 Webhooks de Tickets de Soporte

Cuando configures un webhook en la creación de un ticket vía API, recibirás notificaciones automáticas cuando el soporte responda o resuelva el ticket:

X-Cobox-Event: ticket.updated

          {
          "event": "ticket.updated",
          "timestamp": "2024-01-20T15:30:00Z",
          "ticket_id": "abc-123-def",
          "ticket_number": "TKT-2024XXXXX",
          "status": "resuelto",
          "action_type": "resolution",
          "message": "Hemos resuelto tu problema. El pedido fue entregado.",
          "resolved_at": "2024-01-20T15:30:00Z",
          "ticket_url": "https://plataforma.coboxlogistic.com/TicketsManagement?ticket=abc-123-def",
          "commerce_id": "commerce-123",
          "commerce_name": "Mi Tienda Online"
          }

📝 Cómo usar:

  1. Al crear un ticket, incluye webhook_url en la solicitud
  2. Nuestro sistema enviará notificaciones a esa URL cada vez que haya una actualización
  3. action_type puede ser "comment" (respuesta) o "resolution" (resuelto)
  4. Usa el ticket_url para enlazar directamente al panel de control
© 2026 Cobox Logistic · Documentación pública ·tech@coboxlogistic.com