API de OnBox

Una sola API para conectar tu sistema con el nuestro en las dos direcciones: nos mandás pedidos, te devolvemos estado, stock y seguimiento, y te avisamos apenas algo cambia.

Es REST sobre HTTPS, con JSON en los dos sentidos y autenticación por clave. No hay SDK que instalar: si podés hacer un POST, ya podés integrarte.

Lo que resuelve

Base URL

https://api.onboxservicioslogisticos.com

Todas las rutas cuelgan de /v1. Las respuestas siempre traen ok: si es true mirás data, si es false mirás error.

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

{
  "ok": false,
  "error": {
    "code": "unknown_sku",
    "message": "...",
    "details": [ ... ]
  }
}

Toda respuesta incluye el header X-Request-Id. Guardalo en tus logs: con ese identificador ubicamos la llamada exacta, sin adivinar.

Empezar en 5 minutos

Cuatro llamadas y ya tenés la integración funcionando de punta a punta.

1 · Verificá la clave

curl https://api.onboxservicioslogisticos.com/v1/ping \
  -H "Authorization: Bearer obx_test_tuClave"

Te dice a qué cuenta pertenece, qué permisos tiene y si es de prueba o de producción.

2 · Mirá qué SKU tenés

curl https://api.onboxservicioslogisticos.com/v1/stock?limit=10 \
  -H "Authorization: Bearer obx_test_tuClave"

Los SKU del alta tienen que existir en tu catálogo. Si no existen, rechazamos el pedido entero.

3 · Creá un pedido

curl -X POST https://api.onboxservicioslogisticos.com/v1/orders \
  -H "Authorization: Bearer obx_test_tuClave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-primer-pedido" \
  -d '{
    "externalId": "MI-0001",
    "buyer":    { "name": "Juan Perez", "phone": "1155667788" },
    "shipping": { "address": "Av. Mitre 750", "city": "Avellaneda", "zip": "1870" },
    "items": [ { "sku": "TU-SKU", "quantity": 1, "unitPrice": 15400 } ]
  }'

Mandá la misma llamada dos veces: la segunda te devuelve duplicate: true y el mismo pedido. Eso es lo que te protege de los timeouts.

4 · Enterate de los cambios

curl -X POST https://api.onboxservicioslogisticos.com/v1/webhooks \
  -H "Authorization: Bearer obx_test_tuClave" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tu-sistema.com/hooks", "events": ["*"] }'

Guardá el secret que te devolvemos: se muestra una sola vez.

Autenticación

Una clave por integración, en un header. Sin OAuth, sin tokens que vencen a mitad de un proceso.

Authorization: Bearer obx_live_tuClaveSecreta

Dos entornos, dos claves

El endpoint /v1/ping te dice en cuál estás, en el campo mode. Si tu código no está seguro de qué clave cargó, preguntale a la API antes de operar.

Permisos

Cada clave lleva sólo los permisos que necesita. Si le falta uno, la llamada devuelve 403 forbidden diciendo exactamente cuál falta.

Vencimiento y rotación

Una clave puede tener fecha de vencimiento. Si venció, devolvemos 401 key_expired: no es que falle la llamada, es que hay que renovarla. Para rotar sin ventana de corte emitimos la nueva y dejamos la anterior viva 24 horas; en ese lapso las dos funcionan y podés desplegar tranquilo.

Seguridad

Lo que hacemos de nuestro lado, y lo que necesitamos del tuyo.

De nuestro lado

• La clave se guarda hasheada con SHA-256. Ni nosotros podemos volver a verla: si se pierde, se revoca y se emite otra.
• Cada clave está atada a una cuenta y sólo ve los datos de esa cuenta. No hay forma de leer pedidos ajenos.
• Podemos atar una clave a una lista de IPs. Si la llamada viene de otra, devolvemos 403 ip_not_allowed.
• Los avisos van firmados con HMAC-SHA256 para que puedas comprobar que salieron de nosotros.
• Queda registro de cada llamada con su identificador, código y duración. Vos lo ves en /v1/logs.
• Sólo HTTPS. Los webhooks también: no aceptamos una URL http://.

De tu lado

• La clave va en el servidor. Nunca en una app móvil, en el navegador ni en un repositorio.
• Validá la firma de cada webhook antes de creerle. Está explicado más abajo, con código.
• Rechazá lo viejo: si el t de la firma tiene más de 5 minutos, descartá el aviso.
• Si sospechás que la clave se filtró, avisanos: la revocamos en el momento.

Entorno de prueba

Integrá completo sin ensuciar producción ni mover una unidad de stock.

Con una clave obx_test_… la API se comporta igual: mismas validaciones, mismos errores, mismos formatos. La diferencia es que los pedidos quedan en un espacio aparte, no llegan al depósito y no tocan el stock real. El stock que consultás sí es el de verdad, para que trabajes con datos creíbles.

Simular el recorrido de un pedido

En producción el estado lo mueve la operación. En prueba lo movés vos, y los webhooks salen igual que si fuera real:

curl -X POST https://api.onboxservicioslogisticos.com/v1/sandbox/orders/MI-0001/advance \
  -H "Authorization: Bearer obx_test_tuClave" \
  -H "Content-Type: application/json" \
  -d '{ "status": "Despachado", "tracking": "OCA-123456" }'

Sin status avanza al siguiente estado natural: Pendiente → En preparación → Despachado → En camino → Entregado. Así probás la secuencia completa en cuatro llamadas.

Ver qué te mandamos

Si todavía no tenés endpoint donde recibir, apuntá el webhook a https://api.onboxservicioslogisticos.com/dev/echo y consultá GET /dev/echo: ahí ves el aviso tal cual sale, con la firma ya verificada de nuestro lado. Sirve para comparar contra tu implementación cuando la firma no te da.

Estados de un pedido

Un pedido viaja por una serie de estados. Integrá tu lógica contra el código estable, no contra el texto.

Cada pedido trae dos campos de estado:

• status — el texto en castellano que ve nuestra operación (Pendiente, En preparación, Despachado…). Es para mostrar. Puede cambiar de redacción sin aviso.
• statusCode — un código estable que no cambia nunca. Es contra este que tenés que programar.

El statusCode viene en el detalle del pedido, en el listado, en el seguimiento y en el data de cada webhook (junto con previousStatusCode, el estado anterior).

Idempotencia

Reintentar tiene que ser seguro. Acá lo es, por diseño.

Un timeout no significa que la operación falló: puede haber entrado igual. Por eso el alta de pedidos está protegida dos veces:

1. Por externalId. Es el identificador del pedido en tu sistema. Si mandás uno que ya existe, no creamos otro: te devolvemos el que hay, con duplicate: true y HTTP 200.
2. Por Idempotency-Key. Si mandás ese header, guardamos la respuesta exacta de ese intento y ante un reenvío te devolvemos la misma, byte por byte.

La consecuencia práctica: ante cualquier error de red o un 5xx, reintentá. Es la conducta correcta y no vas a duplicar pedidos ni descontar stock dos veces.

Las claves de idempotencia se conservan 7 días. Después, el que sigue mandando es el externalId.

Paginación y sincronización

Dos formas de leer: recorrer todo una vez, o traer sólo lo que cambió.

Recorrer

Pedís una página, y si paging.nextCursor no es null, volvés a llamar pasándolo en cursor. Cuando viene null, terminaste.

GET /v1/orders?limit=100
GET /v1/orders?limit=100&cursor=89696349

Sincronizar

Para mantenerte al día no barras todo: pedí sólo lo modificado desde la última vez.

GET /v1/orders?updatedSince=2026-08-18T13:00:00Z&limit=200

Guardá el updatedAt más alto que recibiste y usalo en la llamada siguiente. Si te vuelve una página llena, seguí paginando antes de dormir.

Límites de uso

Si te pasás del límite devolvemos 429 con el header Retry-After en segundos. Esperá eso y reintentá; como todo es idempotente, reintentar no rompe nada.

En cada respuesta va X-RateLimit-Remaining: cuántas llamadas te quedan en el minuto en curso.

Errores

Todos los errores que la API puede devolver. Si te encontrás con uno que no está acá, es un bug nuestro: escribinos con el X-Request-Id.

El formato es siempre el mismo. Cuando el error es de datos, details trae la lista exacta de qué está mal, campo por campo: no tenés que adivinar.

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "El pedido tiene campos inválidos.",
    "details": [
      { "field": "buyer.name", "message": "Requerido: nombre de quien recibe." },
      { "field": "items[0].quantity", "message": "Entero mayor a cero." }
    ]
  }
}

Qué reintentar

Sí: 429, 500, 502 y cualquier error de red — con espera creciente y la misma Idempotency-Key.
No: 4xx de datos (422, 409). Van a fallar igual hasta que corrijas lo que te decimos.

Webhooks

En vez de preguntarnos cada rato, te avisamos nosotros.

Registrás una URL y te mandamos un POST con JSON cada vez que pasa algo. La URL tiene que ser https y de un dominio público.

Eventos

Si querés todos, mandá ["*"]. Un cambio a "Entregado" dispara order.status_changed y order.delivered: suscribite a lo que uses, no a los dos, para no procesar dos veces.

Lo que recibís

POST /tu-endpoint
X-OnBox-Event: order.status_changed
X-OnBox-Delivery: 118
X-OnBox-Timestamp: 1786898527
X-OnBox-Signature: t=1786898527,v1=6f08c3d87ab6352b75e39e31f136755f…

{
  "event": "order.status_changed",
  "createdAt": "2026-08-18T13:22:07.000Z",
  "data": {
    "id": "SM-10045",
    "status": "Despachado",
    "statusCode": "shipped",
    "previousStatus": "En preparación",
    "previousStatusCode": "processing",
    "tracking": "OCA-123456",
    "updatedAt": "2026-08-18T13:22:05.000Z"
  }
}

Validar la firma

El header X-OnBox-Signature trae t (el momento) y v1 (la firma). La firma es HMAC-SHA256 de <t>.<cuerpo crudo> con tu secret.

const crypto = require('crypto');

function verificar(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header || '');
  if (!m) return false;
  const [, t, firma] = m;
  // Descartar lo viejo: protege contra reenvíos.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const esperado = crypto.createHmac('sha256', secret)
    .update(t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(firma), Buffer.from(esperado));
}

// Express: guardá el cuerpo crudo
app.use('/hooks', express.json({ verify: (req, _res, buf) => { req.raw = buf.toString(); } }));
app.post('/hooks', (req, res) => {
  if (!verificar(req.raw, req.get('X-OnBox-Signature'), process.env.ONBOX_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);          // contestá primero
  procesarEnSegundoPlano(req.body);
});

<?php
function verificar(string $rawBody, ?string $header, string $secret): bool {
    if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', (string)$header, $m)) return false;
    [, $t, $firma] = $m;
    if (abs(time() - (int)$t) > 300) return false;
    $esperado = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($esperado, $firma);
}

$raw = file_get_contents('php://input');
if (!verificar($raw, $_SERVER['HTTP_X_ONBOX_SIGNATURE'] ?? null, getenv('ONBOX_WEBHOOK_SECRET'))) {
    http_response_code(401); exit;
}
http_response_code(200);
$evento = json_decode($raw, true);

import hmac, hashlib, re, time

def verificar(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.match(r"t=(\d+),v1=([a-f0-9]+)", header or "")
    if not m:
        return False
    t, firma = m.group(1), m.group(2)
    if abs(time.time() - int(t)) > 300:
        return False
    esperado = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, firma)

Cómo contestar

• Devolvé 2xx rápido y procesá después. Si tardás más de 12 segundos lo tomamos como fallido y reintentamos.
• Cualquier respuesta que no sea 2xx cuenta como fallo.
• Los avisos pueden llegar más de una vez. Usá X-OnBox-Delivery para descartar repetidos.
• No asumas orden. Si te llegan dos cambios juntos, ordenalos por data.updatedAt.

Reintentos

Si no contestás 2xx, reintentamos a los 1 min, 5, 15, 1 h, 3 h, 6 h y 12 h. Después marcamos la entrega como fallida y queda en el historial. En GET /v1/webhooks/{id}/deliveries ves cada intento con lo que devolviste, así podés diagnosticar sin escribirnos.

Versiones y cambios

La ruta /v1 es estable. No rompemos lo que ya funciona.

Podemos agregar campos a una respuesta o endpoints nuevos sin avisar: tu integración tiene que ignorar lo que no conoce en vez de romperse. Si alguna vez hubiera que cambiar o sacar algo, sale una /v2 y /v1 sigue andando con al menos 6 meses de aviso.

Historial

Antes de salir a producción

Si podés tildar todo esto, la integración está sana.

Diagnóstico

curl https://api.onboxservicioslogisticos.com/v1/ping \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "sellerId": "CLI-0042",
  "mode": "live",
  "scopes": [
    "orders:read",
    "orders:write"
  ],
  "rateLimit": {
    "limit": 120,
    "remaining": 119
  },
  "apiVersion": "2.2.0",
  "time": "2026-08-18T13:00:00.000Z"
}

curl https://api.onboxservicioslogisticos.com/v1/logs?limit=20 \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "request_id": "req_2ac903e5c69fb8db",
      "method": "POST",
      "path": "/v1/orders",
      "status": 201,
      "ms": 174,
      "created_at": "2026-08-18T13:02:11.204Z"
    }
  ]
}

Pedidos

curl https://api.onboxservicioslogisticos.com/v1/orders?limit=20 \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "id": "SM-10045",
      "internalId": 89696349,
      "status": "Pendiente",
      "statusCode": "pending",
      "amount": 30800,
      "buyer": "Juan Perez",
      "platform": "API · Seller Manager",
      "shippingType": null,
      "tracking": null,
      "orderDate": "2026-08-18",
      "createdAt": "2026-08-18T13:02:11.204Z",
      "updatedAt": "2026-08-18T13:02:11.400Z"
    }
  ],
  "paging": {
    "limit": 50,
    "nextCursor": null
  }
}

curl https://api.onboxservicioslogisticos.com/v1/orders/SM-10045 \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": {
    "id": "SM-10045",
    "internalId": 89696349,
    "status": "Pendiente",
    "statusCode": "pending",
    "amount": 30800,
    "buyer": "Juan Perez",
    "platform": "API · Seller Manager",
    "shippingType": null,
    "tracking": null,
    "orderDate": "2026-08-18",
    "createdAt": "2026-08-18T13:02:11.204Z",
    "updatedAt": "2026-08-18T13:02:11.400Z",
    "address": "Av. Mitre 750",
    "city": "Avellaneda",
    "zip": "1870",
    "province": "Buenos Aires",
    "lines": [
      {
        "sku": "ABC-123",
        "name": "Producto de ejemplo",
        "qty": 2,
        "unitPrice": 15400
      }
    ]
  }
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/orders \
  -H "Authorization: Bearer obx_live_tuClave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9c-1" \
  -d '{
    "externalId": "SM-10045",
    "buyer": {
      "name": "Juan Perez",
      "phone": "1155667788"
    },
    "shipping": {
      "address": "Av. Mitre 750",
      "city": "Avellaneda",
      "zip": "1870",
      "province": "Buenos Aires"
    },
    "items": [
      {
        "sku": "ABC-123",
        "quantity": 2,
        "unitPrice": 15400
      }
    ],
    "amount": 30800
  }'

{
  "ok": true,
  "duplicate": false,
  "data": {
    "id": "SM-10045",
    "internalId": 89696349,
    "status": "Pendiente",
    "statusCode": "pending",
    "amount": 30800,
    "buyer": "Juan Perez",
    "platform": "API · Seller Manager",
    "shippingType": null,
    "tracking": null,
    "orderDate": "2026-08-18",
    "createdAt": "2026-08-18T13:02:11.204Z",
    "updatedAt": "2026-08-18T13:02:11.400Z",
    "externalId": "SM-10045",
    "items": [
      {
        "sku": "ABC-123",
        "name": null,
        "quantity": 2,
        "unitPrice": 15400
      }
    ]
  }
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/orders/SM-10045/cancel \
  -H "Authorization: Bearer obx_live_tuClave" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "El comprador se arrepintió"
  }'

{
  "ok": true,
  "data": {
    "id": "SM-10045",
    "internalId": 89696349,
    "status": "Cancelado",
    "statusCode": "pending",
    "amount": 30800,
    "buyer": "Juan Perez",
    "platform": "API · Seller Manager",
    "shippingType": null,
    "tracking": null,
    "orderDate": "2026-08-18",
    "createdAt": "2026-08-18T13:02:11.204Z",
    "updatedAt": "2026-08-18T13:02:11.400Z"
  }
}

Stock

curl https://api.onboxservicioslogisticos.com/v1/stock?limit=20 \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "sku": "ABC-123",
      "name": "Producto de ejemplo",
      "available": 42
    }
  ]
}

Seguimiento

curl https://api.onboxservicioslogisticos.com/v1/tracking/SM-10045 \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": {
    "reference": "SM-10045",
    "status": "En camino",
    "statusCode": "in_transit",
    "carrier": "OCA",
    "carrierTracking": "OCA-123456",
    "eta": "2026-08-20",
    "timeline": [
      {
        "date": "2026-08-19T10:11:00-03:00",
        "label": "Retirado del depósito"
      }
    ]
  }
}

Webhooks

curl https://api.onboxservicioslogisticos.com/v1/webhooks \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "id": 7,
      "url": "https://tu-sistema.com/hooks/onbox",
      "events": [
        "*"
      ],
      "active": true,
      "consecutive_failures": 0
    }
  ]
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/webhooks \
  -H "Authorization: Bearer obx_live_tuClave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-sistema.com/hooks/onbox",
    "events": [
      "order.status_changed",
      "order.delivered"
    ],
    "description": "Producción"
  }'

{
  "ok": true,
  "data": {
    "id": 7,
    "url": "https://tu-sistema.com/hooks/onbox",
    "events": [
      "order.status_changed",
      "order.delivered"
    ],
    "active": true,
    "secret": "whsec_…"
  }
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/webhooks/SM-10045/test \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": {
    "deliveryId": 118,
    "httpStatus": 200,
    "error": null
  }
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/webhooks/SM-10045/rotate-secret \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": {
    "id": 7,
    "secret": "whsec_…",
    "anteriorValidoHasta": "2026-08-19T13:00:00.000Z"
  }
}

curl https://api.onboxservicioslogisticos.com/v1/webhooks/SM-10045/deliveries \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "id": 118,
      "event": "order.status_changed",
      "order_key": "SM-10045",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "last_error": null
    }
  ]
}

curl -X POST https://api.onboxservicioslogisticos.com/v1/webhooks/SM-10045/delete \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "deleted": 7
}

Entorno de prueba

curl -X POST https://api.onboxservicioslogisticos.com/v1/sandbox/orders/SM-10045/advance \
  -H "Authorization: Bearer obx_live_tuClave" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Despachado",
    "tracking": "OCA-123456"
  }'

{
  "ok": true,
  "data": {
    "id": "SM-10045",
    "status": "Despachado",
    "tracking": "OCA-123456"
  }
}

curl https://api.onboxservicioslogisticos.com/dev/echo \
  -H "Authorization: Bearer obx_live_tuClave"

{
  "ok": true,
  "data": [
    {
      "delivery_id": 118,
      "headers": {
        "x-onbox-event": "ping"
      },
      "signature_ok": true
    }
  ]
}

Objetos

Pedido

Un pedido tuyo dentro de nuestro sistema.

Linea

Una línea de producto de un pedido.

NuevoPedido

Lo que nos mandás para crear un pedido.

Stock

Disponibilidad por SKU.

Seguimiento

Estado vivo de un envío.

Webhook

Una URL tuya a la que te avisamos.