RutaDocs

Empezar

Entorno de prueba

Las claves de prueba (ruta_test_…) trabajan en un espacio aislado de tu empresa. Sirven para integrar y probar sin ensuciar la operación del courier.

Qué cambia y qué no

Real (producción) De prueba
Endpoints, cuerpos y errores Iguales Iguales
Validaciones (texto, teléfono, zona, comercio, programación, cobro) y funciones del plan Sí Sí, las mismas
Cupo mensual del plan Cuenta No cuenta
Aparece en el panel, la app del repartidor, el seguimiento y los reportes Sí Nunca
Avisos (webhooks) A webhooks reales Sólo a webhooks De prueba
test en cada entrega y cada aviso false true

Además:

  • Una clave de prueba no ve entregas reales y una clave de producción no ve entregas de prueba (404).
  • trackingUrl tiene la forma de siempre (…/track/test-…) pero no abre una página real.
  • El comprobante es una imagen de muestra y la etiqueta PDF lleva el sello «PRUEBA - SIN VALIDEZ».
  • Hasta 1000 entregas de prueba por empresa; se borran solas a los 30 días.
  • Las zonas (GET /api/v1/zones) son las reales de la empresa.

Simular el recorrido

POST /api/v1/deliveries/{id}/simulate (permiso deliveries:write, sólo claves de prueba; con una clave de producción responde 403 TEST_KEY_REQUIRED) avanza la entrega como lo haría el actor real:

action Desde Hasta Avisos
ASSIGN CREATED ASSIGNED delivery.assigned
PICK_UP ASSIGNED, OUT_FOR_DELIVERY (una vez por intento) sin cambio de estado delivery.picked_up
START ASSIGNED OUT_FOR_DELIVERY delivery.out_for_delivery
DELIVER OUT_FOR_DELIVERY DELIVERED (con comprobante de muestra; si había monto a cobrar, se declara cobrado entero) delivery.delivered, delivery.proof_added
FAIL OUT_FOR_DELIVERY FAILED delivery.failed
RETRY FAILED CREATED con attemptNumber + 1 delivery.retry_scheduled
SETTLE DELIVERED con cobro sin cambio de estado (settledAt) delivery.collection_settled

Cada cambio de estado emite también delivery.status_changed. Un paso que el estado no permite responde 409 DELIVERY_STATE_INVALID.

Opcionales: failureReasonCode sólo con FAIL (RECIPIENT_ABSENT por defecto; también ADDRESS_NOT_FOUND, ACCESS_UNAVAILABLE, RECIPIENT_REFUSED, UNSAFE_LOCATION, PACKAGE_ISSUE, OTHER) y collectionMethod sólo con DELIVER (CASH por defecto, TRANSFER, OTHER).

Terminal
curl -X POST "$RUTA_API/api/v1/deliveries/$ID/simulate" \
  -H "Authorization: Bearer $RUTA_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"action": "FAIL", "failureReasonCode": "ADDRESS_NOT_FOUND"}'

Responde 200 con la entrega actualizada.

Ver en Markdown