Documentación para desarrolladores

Integra una operación pieza por pieza.

La API v1 crea órdenes, aplica flujos versionados, acepta movimientos idempotentes, registra COD y produce etiquetas. Cada solicitud operativa está aislada por empresa.

Abrir especificación OpenAPI

Disponibilidad verificable

Una ruta implementada no significa que su proveedor esté activo. Google, mensajería y PAC fallan de forma explícita hasta que sus credenciales y pruebas de producción estén aprobadas.

Autenticación y contexto

Personas y aplicaciones móviles usan un token de Google Identity Platform. Las integraciones servidor a servidor usan clientes OAuth rotables y con alcances. Los roles siempre se obtienen de la membresía verificada, nunca de encabezados enviados por el cliente.

Authorization: Bearer <short-lived-token>
x-tenant-id: <tenant-uuid>
Idempotency-Key: <unique-operation-key>

Superficie disponible

GET/api/health

Estado del servicio

Disponible

GET / POST/v1/orders

Listar y crear órdenes

Disponible

POST/v1/workflows/{id}/validate

Validar un flujo

Disponible

POST/v1/workflows/transition

Aplicar un movimiento con evidencia

Disponible

POST/v1/cod

Registrar una entrada COD

Disponible

GET/v1/orders/{uuid}/labels

PDF, ZPL o TSPL

Disponible

POST/v1/routes/optimize

Solicitar optimización Google

Proveedor requerido

Eventos offline e idempotencia

Cada dispositivo conserva un deviceEventId estable y la versión del flujo. El servidor deduplica, vuelve a validar rol, transición y evidencia, y solo entonces aplica el movimiento.

{
  "deviceEventId": "device-42:scan:000812",
  "pieceId": "<piece-uuid>",
  "transitionCode": "RECEIVE",
  "workflowVersion": 3,
  "evidence": { "scanned": true },
  "capturedAt": "2026-08-10T19:30:00.000Z"
}

Webhooks

Los endpoints HTTPS reciben firmas HMAC-SHA256, timestamp e identificador de entrega para protección contra repetición.

Activación controlada

El destino se valida contra redes privadas y cada tenant puede rotar o revocar su secreto.

Etiquetas

Solicita PDF, ZPL o TSPL por perfil, dimensiones y DPI. Cada pieza entregable conserva una etiqueta independiente.

GET /v1/orders/{uuid}/labels?output=zpl&widthMm=100&heightMm=150&dpi=203

Optimización de rutas

La API valida rol, límites y modelo antes de invocar Google Route Optimization. Si el proveedor no está configurado, no devuelve rutas inventadas.

Activación separada

Requiere Workload Identity, cuota, alertas de costo y una prueba autorizada de producción.

Límites operativos

10 escaneos/segundo sostenidos por tenant100 escaneos/segundo de ráfagaCorrecciones mediante eventos compensatoriosPaginación y claves idempotentes obligatorias