Depurar tu integración

​

Registro de solicitudes

curl "https://api.listo.delivery/v1/request_logs?status=failed" \
  -H "Authorization: Bearer $LISTO_API_KEY"

{
  "data": [
    {
      "id": "req_4f9c2b7e1a8d3056b1c2d3e4",
      "method": "POST",
      "path": "/v1/deliveries",
      "endpoint": "api/v1/deliveries#create",
      "status": 422,
      "error_code": "validation_failed",
      "duration_ms": 118,
      "request_id": "0b1f6c9a-7e2d-4c53-9a41-5d8e3f2a6b10",
      "api_key_prefix": "lst_test_Ab1",
      "test": true,
      "created_at": "2026-11-06T16:02:11Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

• Las llamadas que identificaron una llave. Una llamada sin llave, o con una equivocada o revocada, no pertenece a nadie y no está en tu registro, y tampoco una llamada rechazada por límite de frecuencia. Si estás seguro de haber hecho una llamada y no aparece, la razón es una de esas.
• Las llaves y los enlaces de un solo uso se enmascaran. Una llave de API en cualquier cuerpo aparece como sus primeros caracteres seguidos de [key masked], y el enlace de la respuesta de POST /v1/connect_requests o de una llamada de onboarding de Stripe aparece como [redacted: one-time link], porque tener ese enlace es la autoridad para usarlo. Lo que tú recibiste no se toca; solo se enmascara la copia guardada. Los encabezados nunca se guardan.
• Un cuerpo se corta a 64 KB. Uno más largo se guarda como un objeto con _listo_truncated: true, los original_bytes que tenía y los primeros 64 KB de su text, así que siempre se te avisa que no estás leyendo todo.
• Las tres lecturas de depuración no guardan cuerpos. Leer el registro de solicitudes, los eventos o las entregas de webhook también queda registrado, pero sin cuerpos: si no, el registro se copiaría a sí mismo cada vez que lo lees. Su request_body y response_body son null.
• Las filas se conservan. No hay ventana de retención contra la que correr. Una fila de antes de que existiera este registro no tiene path ni request_id, ambos null.

​

Eventos

​

Entregas de webhook

{
  "id": "whd_8d2e5f1a7c3b9046a1b2c3d4",
  "event_id": "evt_9pQ2vX7mKdR4tYb1nZ3sLwCe",
  "event_type": "delivery.status_changed",
  "attempt": 2,
  "resent": false,
  "url": "https://example.com/listo/webhooks",
  "status_code": null,
  "error_message": "execution expired",
  "response_body": null,
  "duration_ms": 5000,
  "succeeded": false,
  "created_at": "2026-11-06T16:04:31Z"
}

​

Reenviar un evento

curl -X POST "https://api.listo.delivery/v1/events/evt_9pQ2vX7mKdR4tYb1nZ3sLwCe/resend" \
  -H "Authorization: Bearer $LISTO_API_KEY"

• El mismo evento. Tiene el mismo id y un cuerpo idéntico byte por byte, así que un receptor que deduplica por id, como debe, lo trata como el evento que ya vio. Para ejercitar tu manejador otra vez, borra primero ese registro.
• Firmado ahora. La firma lleva la hora actual y el secreto vigente, así que verifica aunque el evento tenga días.
• Enviado a la URL actual. Si cambiaste tu endpoint desde que ocurrió el evento, el reenvío va al nuevo.
• Una sola vez. No hay reintentos detrás. Si tu endpoint falla, ves un intento fallido y tú decides qué sigue.
• Con límite. Un evento se puede reenviar 5 veces por hora. El sexto se rechaza con 429 resend_limit_reached, que se puede reintentar pasada la hora. Retry-After dice cuántos segundos faltan para que puedas enviar de nuevo.
• Nunca una posición de repartidor. Un evento delivery.courier_location lo reemplaza el siguiente en segundos, así que pedir reenviar uno es 409 event_not_resendable.
• Necesita un endpoint. Sin URL de webhook configurada para el modo de la llave, la respuesta es 409 webhook_endpoint_not_configured.

​

Enviar un webhook de prueba

curl -X POST "https://api.listo.delivery/v1/test_webhooks" \
  -H "Authorization: Bearer $LISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "delivery.status_changed"}'

{
  "id": "evt_3kM7qR2vX9pNdY4tB6nZ1sLw",
  "type": "delivery.status_changed",
  "created_at": "2026-11-06T16:10:02Z",
  "test": true,
  "data": {
    "id": "dlv_test_sample_000000000000",
    "external_id": "order-841",
    "status": "en_route"
  }
}

• "test": true va en el sobre. Un evento real no trae ese campo. Revísalo antes de hacer cualquier cosa con consecuencias.
• Sus ids no resuelven a nada. data es una muestra realista del tipo, pero el envío, la tienda, el retiro o la cotización que nombra no existe, así que GET /v1/deliveries/{id} con ese id responde 404. Un manejador que vuelve a leer el objeto, como debe, no encontrará nada, y esa es la prueba de que es de prueba.
• Funciona en los dos modos. Una llave de prueba envía a tu endpoint de prueba y una llave de producción envía al de producción, así que puedes verificar un endpoint de producción sin hacer un pedido. Ese endpoint de producción sí recibe el evento de prueba, así que asegúrate de que ahí se ignore.
• Tiene límite. 30 eventos de prueba por hora por modo, y luego 429 test_webhook_limit_reached, y Retry-After dice cuántos segundos faltan para que puedas enviar de nuevo. Un type que no es un nombre publicado es 422 validation_failed con param: "type", y un modo sin URL de webhook es 409 webhook_endpoint_not_configured.

​

Con qué rechazan estos endpoints

​

En el panel

• Registro de solicitudes lista tus llamadas con los mismos filtros, y cada llamada se abre para ver sus cuerpos de solicitud y respuesta.
• Webhooks guarda la configuración del endpoint y muestra cada intento. Reenviar está en cada intento de un evento que se puede reenviar, y Enviar webhook de prueba manda un evento sintético al endpoint de arriba.

​

Depura con tu asistente de IA

​

Una forma de trabajar

1. Reproduce el problema con una llave de prueba, para que nada real esté en juego.
2. Abre la llamada en el registro de solicitudes. El estatus, el error.code y el message del cuerpo de la respuesta, y tu propio cuerpo de solicitud, contestan la mayoría de las preguntas.
3. Si era un evento que esperabas, encuéntralo en GET /v1/events, y luego sus intentos en GET /v1/webhook_deliveries.
4. Arregla el manejador y luego reenvía ese evento, o envía un webhook de prueba, hasta que el intento diga succeeded.
5. Comprueba lo mismo en el endpoint de producción con un webhook de prueba antes de depender de él.