> ## Documentation Index
> Fetch the complete documentation index at: https://docs.listo.delivery/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Notes on the Listo Partner Delivery API:
> - Every endpoint is under `https://api.listo.delivery/v1/` and authenticates with a bearer API key.
> - This documentation site is at https://docs.listo.delivery. The full machine-readable reference is the OpenAPI document at https://api.listo.delivery/docs/openapi.yaml (served by the API host, not by this site).
> - Any page of this site is also available as raw markdown by appending `.md` to its URL, for example https://docs.listo.delivery/en/guides/webhooks.md. The index of every page is https://docs.listo.delivery/llms.txt and all of them in one file is https://docs.listo.delivery/llms-full.txt.
> - Every page is published in English under https://docs.listo.delivery/en/ and in Spanish under https://docs.listo.delivery/es/, with the same path after the language. The API reference is under https://docs.listo.delivery/api-reference/ in English and https://docs.listo.delivery/es/api-reference/ in Spanish.
> - To debug an integration yourself: `GET /v1/request_logs` lists the calls your keys made with what you sent and what was answered, `GET /v1/events` lists the events Listo emitted, `GET /v1/webhook_deliveries` lists every attempt to deliver them, `POST /v1/events/{id}/resend` sends one event again and `POST /v1/test_webhooks` sends a sample event (`"test": true`). The page https://docs.listo.delivery/en/guides/debugging describes them. A resent event is a snapshot from when it happened; `GET /v1/deliveries` is still how you recover current state.
> - Every error response has `error.doc_url`, a page that explains that error code and what to do, and `error.request_id`, the same value as the `X-Request-Id` response header. All the pages are listed at https://docs.listo.delivery/en/errors. Filter `GET /v1/request_logs` with `request_id` to read the logged call.
> - A `409 account_exists` from `POST /v1/stores` means the restaurant already has its own Listo account: connect it instead of creating it, as the page https://docs.listo.delivery/en/guides/connect-existing-account describes.
> - Every live store carries one Plan Listo, charged to the partner. The exception is a connected restaurant that had already paid its current month: it keeps paying its own plan until its next renewal, shown as `paid_by: "store"` with the handover date in `pending_paid_by_on`. A `402 plan_required` from a quote, a delivery create or a retry means the store's plan is not paid or has ended; the page https://docs.listo.delivery/en/guides/plan-and-billing describes the plan, the `plan` block on a store and how to end or restart it.
> - An AI assistant (Claude Code, Cursor, Codex) can act through the same API key at `https://api.listo.delivery/mcp`, an MCP server over Streamable HTTP authenticated with `Authorization: Bearer <API key>`. Every tool runs the matching `/v1/` endpoint, and each one that moves money first previews and then needs a confirmation token; the page https://docs.listo.delivery/en/guides/connect-ai-client lists the tools and describes the two steps.

# Sal a producción

> Qué revisar antes de cambiar una llave de prueba por una real.

Salir a producción es cambiar una credencial por otra. No hay otro host, no hay
cambio de versión y no hay una forma distinta de armar las peticiones: el mismo
código que despachó a un repartidor simulado despacha a uno real en cuanto manda
una llave real.

Por eso vale la pena leer el resto de esta página. Nada te va a avisar que se te
pasó algo; la primera señal va a ser un repartidor real en una dirección real.

## Qué cambia de verdad

| | Llave de prueba | Llave real |
| - | - | - |
| El repartidor | Simulado, recorre el ciclo de vida por su cuenta | Una persona real |
| El dinero | Dinero ficticio, recargado desde el panel | Real, y se gasta de verdad |
| El efectivo | Nadie cobra nada | El repartidor cobra en la puerta |
| Los retiros | Se resuelven solos unos minutos después | Una transferencia real a tu banco |
| La tarjeta | Solo tarjetas de prueba | Tarjetas reales, liquidación real |
| El Plan Listo | Ninguno: una tienda de prueba no tiene plan | Uno por tienda, se te cobra cada mes |
| Tiendas, cotizaciones, envíos | Su propio conjunto | Su propio conjunto |

Todo lo demás es idéntico: los mismos endpoints, las mismas formas de los
objetos, los mismos errores, los mismos eventos, el mismo esquema de firma.

## Antes de hacer el cambio

* **Lee los [Términos para Partners](https://listo.delivery/terminos-partners).**
  Se suman a los términos generales de Listo y cubren la API, tus llaves, el
  modo de prueba y el modo real, el nivel de acceso de cada tienda, quién paga
  cada envío y cómo reportas un incidente en uno. Una persona de tu equipo los
  acepta en el panel por todo el equipo. Mientras nadie los haya aceptado, la API
  y el panel siguen funcionando, pero no puedes presentar reportes de
  incidentes.
* **Emite una llave real y guárdala como una contraseña.** Las llaves se
  muestran una sola vez y pueden hacer todo lo que su modo permite, salvo que las
  emitas de solo lectura (pueden leer y nada más, así que son las que conviene
  darle a un agente de IA o a una herramienta de monitoreo). Mantenlas del lado
  del servidor y fuera de tu repositorio. Si
  se filtra una, revócala en el panel; la revocación surte efecto de inmediato.
* **Apunta un endpoint de webhooks real a producción, con su propio secreto.**
  Los dos modos tienen URLs de endpoint y secretos distintos. Un endpoint real
  sin configurar simplemente significa que los eventos no se mandan, y nada se
  va a quejar.
* **Fondea el plan antes de crear una tienda.** Cada tienda real lleva un Plan
  Listo que se te cobra a ti, y su primer mes se cobra en la misma petición
  `POST /v1/stores` que la crea. Fondea primero el saldo real o guarda una
  tarjeta en el panel, y manda un `Idempotency-Key` en cada creación real para
  que un reintento no empiece un segundo plan. Una tienda cuyo cargo falla se
  crea de todos modos, pero sus envíos se rechazan con `402 plan_required` hasta
  que se pague el mes. Ve [plan y cobro](https://docs.listo.delivery/es/guides/plan-and-billing.md).
* **Crea tus tiendas reales.** Una tienda pertenece al mundo en el que se creó,
  así que tus tiendas de prueba no existen para una llave real. Dale a cada una
  el teléfono al que de verdad puede llamar un repartidor y sus instrucciones
  reales de recolección. Un restaurante que ya usa Listo con una cuenta propia se
  conecta en lugar de crearse: ve
  [conecta un restaurante que ya usa Listo](https://docs.listo.delivery/es/guides/connect-existing-account.md).
* **Fondea el saldo real**, y ponte un piso contra el cual alertar. Ve
  [saldo y retiros](https://docs.listo.delivery/es/guides/balance-and-withdrawals.md).
* **Registra la cuenta bancaria** a la que van los retiros.
* **Termina el alta de tarjeta si vas a cobrar con tarjeta.** Lee
  [`GET /v1/stores/{id}/stripe_status`](https://docs.listo.delivery/es/api-reference/card-onboarding/read-a-stores-card-readiness)
  para cada tienda real y confirma que dice `connected`. Hasta que lo diga, una
  creación con tarjeta se rechaza con `card_not_ready`. Los pedidos en efectivo
  y prepagados no necesitan nada de esto.
* **Revisa que tus `external_id` y tus llaves de idempotencia sean únicos en
  producción.** Los dos son únicos por modo, así que un valor que reusaste sin
  cuidado entre corridas de prueba tiene que ser genuinamente único entre tus
  pedidos reales.

## Atiende las fallas que te saltaste

El modo de prueba rara vez produce las interesantes. Antes de mover pedidos
reales, asegúrate de que cada una de estas haga algo sensato en tu código:

* `402 insufficient_balance`: el pedido no se despachó. Hazlo visible para
  alguien que pueda recargar.
* `503 provider_unavailable` y `409 cancel_failed`: los dos traen
  `"retryable": true`, y los dos significan que nada cambió. Reintenta; no los
  trates como un pedido fallido.
* `409 no_couriers_available`: todos los repartidores cerca del viaje están
  ocupados. Trae `"retryable": true` y no se creó nada, pero no es una caída:
  reintenta en unos minutos, un número limitado de veces, y después avísale a
  una persona.
* `429 rate_limited`: espera los segundos que diga `Retry-After`.
* `no_courier`: un desenlace real, no un error. Decide si lo reintentas
  automáticamente o le preguntas a una persona, y lee `failure_reason` para
  elegir.
* Una creación que se va a timeout: repítela con el *mismo* `Idempotency-Key`.
  Una llave nueva manda un segundo repartidor.

Ramifica solo sobre `error.code`. `error.message` es prosa pensada para quien
lea tus logs y su redacción no forma parte del contrato. Manda
`Accept-Language: es-MX` y esos mensajes llegan en español, que vale la pena si
van a acabar frente a personal que habla español.

## Límites de tasa

600 peticiones por minuto por llave, y 300 por minuto de esas sobre
`POST /v1/quotes`, que es la única llamada que le cuesta a Listo una petición
hacia arriba. Al pasarte de cualquiera de los dos límites recibes
`429 rate_limited` con un encabezado `Retry-After`.

Los límites son por llave, no por IP, así que varios servidores que comparten
una llave comparten un presupuesto.

## Ya que estés en producción

* Guarda el `id` o tu `external_id` de cada envío. Entre los dos, todo sobre un
  pedido se puede leer de vuelta.
* `support_reference` viene en cada envío. Cítalo cuando contactes a Listo por
  un pedido en particular; es el camino más rápido al viaje correcto.
* Está pendiente de los eventos `store.updated`. Que una tienda esté lista para
  cobrar con tarjeta puede cambiar sin que tú llames a nada.
* Concilia con `GET /v1/ledger` y no con los eventos que guardaste. Es el
  registro de cada movimiento de tu saldo, y ahí es donde te va a estar esperando
  un costo que cayó después de que el pedido terminó. Ve
  [saldo y retiros](https://docs.listo.delivery/es/guides/balance-and-withdrawals.md).

> [!TIP]
>
> **Conserva la llave de prueba**
>
> El modo de prueba no caduca y no cuesta nada. Apunta tu ambiente de staging ahí
> de forma permanente en vez de probar contra producción, y tendrás un ciclo de
> vida real, eventos reales y firmas reales contra los cuales desarrollar mientras
> viva la integración.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.