RutaDocs

API

El objeto entrega

Todas las llamadas de entregas (crear, consultar, listar, corregir, cancelar, simular) responden con este mismo objeto. Siempre trae todos los campos: los que no aplican vienen en null.

Ciclo de vida

Estado Significa Qué podés hacer
CREATED Cargada, sin repartidor. Corregir o cancelar.
ASSIGNED Asignada a un repartidor. Corregir o cancelar.
OUT_FOR_DELIVERY El repartidor salió a entregar. Si la inició por error, puede volver a ASSIGNED (mismo repartidor e intento). Consultar y seguir.
DELIVERED Entregada. Si había cobro, collectedAmount, collectionMethod, collectedAt y collectedCurrency dicen lo declarado. Pedir el comprobante.
FAILED No se pudo entregar (failureReasonCode). Esperar el reintento: vuelve a CREATED (o a ASSIGNED, si el reintento ya tiene repartidor) con attemptNumber + 1.
CANCELLED Cancelada. Nada: es final.

Consejo

Para probar el recorrido completo sin repartidores, usá una clave de prueba y el simulador: cada paso dispara los mismos webhooks que en producción.

Campos

Generada del contrato del servidor: siempre coincide con lo que responde la API.

Campo Tipo Qué es
id texto o null Id de la entrega (UUID). Usalo en las demás llamadas.
status CREATED · ASSIGNED · OUT_FOR_DELIVERY · DELIVERED · FAILED · CANCELLED o null Estado actual. Ver el ciclo de vida.
externalReference texto o null El número de tu pedido, si lo mandaste. Único por empresa y comercio.
customerName texto o null Nombre del destinatario.
address texto o null Dirección de entrega, tal como se cargó (Ruta no la geocodifica).
recipientPhone texto o null Teléfono del destinatario en formato E.164 (+59899123456).
recipientEmail texto o null Email del destinatario para los avisos por email (sin espacios, en minúsculas), o null.
instructions texto o null Indicaciones para el repartidor.
trackingUrl texto o null Página pública de seguimiento para compartir con el destinatario.
scheduledDate texto o null Día programado (YYYY-MM-DD), si la entrega se programó.
windowStart texto o null Inicio de la franja horaria (HH:mm).
windowEnd texto o null Fin de la franja horaria (HH:mm).
scheduleTimeZone texto o null Zona horaria de la programación, por ejemplo America/Montevideo.
amountToCollect texto o null Monto a cobrar contra entrega, como texto decimal ("1250.00"), en la moneda de currency.
shipperId texto o null Comercio al que pertenece la entrega.
zoneId texto o null Zona asignada.
destinationLat número o null Latitud del punto marcado a mano (grados decimales).
destinationLng número o null Longitud del punto marcado a mano (grados decimales).
attemptNumber entero Número de intento: empieza en 1 y sube con cada reintento.
failureReasonCode texto o null Motivo del último fallo: RECIPIENT_ABSENT, ADDRESS_NOT_FOUND, ACCESS_UNAVAILABLE, RECIPIENT_REFUSED, UNSAFE_LOCATION, PACKAGE_ISSUE u OTHER.
createdAt fecha y hora ISO 8601 o null Cuándo se creó.
startedAt fecha y hora ISO 8601 o null Cuándo salió a entregar.
deliveredAt fecha y hora ISO 8601 o null Cuándo se entregó.
failedAt fecha y hora ISO 8601 o null Cuándo falló el último intento.
cancelledAt fecha y hora ISO 8601 o null Cuándo se canceló.
collectedAmount texto o null Monto que el repartidor declaró cobrado al entregar, en la moneda de collectedCurrency.
collectionMethod CASH · TRANSFER · OTHER o null Cómo se cobró.
collectedAt fecha y hora ISO 8601 o null Cuándo se declaró el cobro.
settledAt fecha y hora ISO 8601 o null Cuándo el courier le rindió el cobro al comercio.
test booleano true si la entrega es del entorno de prueba.
quotaHeld booleano true mientras la entrega está retenida porque llegó con el cupo mensual del courier completo: sigue en CREATED, sin repartidor, y sale sola cuando hay cupo.
quotaHeldAt fecha y hora ISO 8601 o null Desde cuándo está retenida, o null.
currency UYU · USD o null Moneda del cobro: UYU (pesos) o USD (dólares); null sin monto a cobrar. Los montos de la entrega están en esa moneda y Ruta nunca convierte.
collectedCurrency UYU · USD o null Moneda de collectedAmount: UYU o USD; null hasta que se cobre. Es distinta de currency cuando el repartidor cobró en la otra moneda (por ejemplo, una entrega en dólares pagada en pesos); Ruta no convierte.

Ejemplo

JSON
{
  "id": "6f1c1d0e-2f5e-4bb5-9c1a-1c1b1f0e9a77",
  "status": "DELIVERED",
  "externalReference": "1042",
  "customerName": "Ana Pérez",
  "address": "Av. Italia 1234, apto 5",
  "recipientPhone": "+59899123456",
  "recipientEmail": "ana@ejemplo.com",
  "instructions": "Timbre 5",
  "trackingUrl": "https://<tu-courier>/track/0b6d…",
  "scheduledDate": null, "windowStart": null, "windowEnd": null, "scheduleTimeZone": null,
  "amountToCollect": "1250.00",
  "shipperId": null, "zoneId": null,
  "destinationLat": null, "destinationLng": null,
  "attemptNumber": 1, "failureReasonCode": null,
  "createdAt": "2026-10-10T15:04:05.123456Z",
  "startedAt": "2026-10-10T16:10:00Z",
  "deliveredAt": "2026-10-10T16:42:13Z",
  "failedAt": null, "cancelledAt": null,
  "collectedAmount": "1250.00", "collectionMethod": "CASH",
  "collectedAt": "2026-10-10T16:42:13Z", "settledAt": null,
  "test": false,
  "quotaHeld": false, "quotaHeldAt": null,
  "currency": "UYU",
  "collectedCurrency": "UYU"
}

Si el destinatario pagó en la otra moneda (por ejemplo, una entrega de "currency": "USD" pagada en pesos), collectedCurrency es "UYU" y collectedAmount está en pesos. Ruta nunca convierte: comparalo con amountToCollect sólo si las dos monedas coinciden.

La API nunca muestra la identidad ni la ubicación del repartidor, ni notas internas del courier.

Ver en Markdown