> ## 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.

# Construye con IA

> Apunta a un agente de código a los archivos correctos, dale una llave que no puede mover dinero y empieza con prompts que nombran las páginas exactas que debe leer.

Un agente de código con IA integra mejor cuando lee la documentación real en lugar
de adivinar de memoria. Esta página lista los archivos que conviene darle a un
agente, cómo entregarle una llave que no pueda usar mal y varios prompts para
copiar que nombran las páginas que el agente debe leer primero.

## Archivos hechos para agentes

Cada dirección de abajo está escrita completa: los archivos raíz están en `api.listo.delivery` y los archivos de la documentación están en `docs.listo.delivery`.

* **Índice raíz**: `https://api.listo.delivery/llms.txt`. El primer archivo que busca un agente. Solo apunta a los demás.
* **Instrucciones para agentes**: `https://api.listo.delivery/AGENTS.md`. Las reglas breves para un agente que trabaja en una integración, en markdown.
* **Índice de la documentación**: `https://docs.listo.delivery/llms.txt`. Cada guía y cada página de conceptos con una descripción de una línea.
* **Todas las guías en un archivo**: `https://docs.listo.delivery/llms-full.txt`. Una sola descarga con el texto completo de cada guía, para un agente que no puede navegar.
* **Documento OpenAPI**: `https://api.listo.delivery/docs/openapi.yaml`. La referencia completa de `/v1/`, en el formato que mejor leen los generadores de código y los agentes.
* **Cualquier página en markdown**: la URL de la página con `.md` al final. Por ejemplo `https://docs.listo.delivery/es/guides/webhooks.md`.

Las páginas de la referencia generada también tienen una copia en markdown, en la
misma dirección con `.md` al final, por ejemplo
`https://docs.listo.delivery/es/api-reference/deliveries/create-a-delivery.md`.
Para la referencia completa en un solo documento, dale al agente el documento OpenAPI.

## Dale a un agente una llave de solo lectura

Un agente que solo tiene que leer, listar o depurar nunca debería tener una llave
que pueda crear o cancelar algo. En el [panel de socios](https://partners.listo.delivery),
emite la llave con **Llave de solo lectura** marcada. Una llave de solo lectura
puede llamar los endpoints `GET` y `HEAD` (saldo, movimientos, envíos, registros
de llamadas, eventos) y cualquier otra llamada, incluido reenviar un evento o
enviar un webhook de prueba, responde `403 read_only_key`.

Una llave es de solo lectura o de acceso completo desde que se emite y nunca
cambia, así que para darle más poder a un agente emites otra llave y revocas la
primera. En ambos casos empieza con una **llave de prueba**: actúa en modo de
prueba, donde nada real ocurre. [Modo de prueba](https://docs.listo.delivery/es/concepts/test-mode.md)
explica qué hace el repartidor simulado, y [Sal a producción](https://docs.listo.delivery/es/guides/go-live.md)
cubre las llaves para producción.

> [!WARNING]
>
> Las llaves se muestran una sola vez. Guarda la llave en una variable de entorno o
> en un gestor de secretos que el agente pueda leer, nunca en el prompt, en el
> repositorio ni en un chat.

## Los errores apuntan a su solución

Cada respuesta de error trae dos campos que un agente puede usar sin adivinar:

* `doc_url`: la página que explica ese `error.code` exacto, qué lo causa y si
  reintentar puede ayudar. Hay una página por código, todas en el
  [índice de páginas de errores](https://docs.listo.delivery/es/errors.md).
* `request_id`: el mismo valor que el encabezado `X-Request-Id` de la respuesta.
  Cítalo cuando le pidas ayuda a una persona. `GET /v1/request_logs` lista las
  llamadas que hicieron tus llaves, con lo que se envió y lo que se respondió, y
  acepta un filtro `request_id`.

[Depurar tu integración](https://docs.listo.delivery/es/guides/debugging.md) describe los registros de
llamadas, los eventos y los intentos de entrega de webhooks que un agente puede
leer por sí solo.

## Conecta un cliente de IA por MCP

Si tu asistente es Claude, Cursor o Codex, puedes conectarlo al servidor MCP de
Listo en lugar de pedirle que escriba llamadas HTTP. [Conecta Claude, Cursor o Codex](https://docs.listo.delivery/es/guides/connect-ai-client.md)
trae la dirección del servidor y la configuración de cada cliente. Una llave de
solo lectura también funciona ahí: el asistente puede leer, y toda herramienta
que crea, cambia o cancela algo en tu cuenta se rechaza con `read_only_key`,
porque cada herramienta ejecuta el endpoint `/v1/` que le corresponde. Una
herramienta que pide confirmación se rechaza desde su primer paso, así que al
asistente nunca se le muestra una vista previa que no podría confirmar. Enviar
comentarios a Listo (`submit_feedback`) sí sigue funcionando.

## Prompts para copiar

Cada prompt nombra las páginas que hay que leer. Pégalo tal cual, o agrega tus
datos (tu lenguaje, tu framework, dónde está el código). El agente debe abrir las
páginas antes de escribir nada.

### Integrar cotizar y crear

```text theme={null}
Agrega envíos de Listo a este proyecto usando la API de envíos para socios de Listo.

Lee primero esto y síguelo al pie de la letra:
- https://api.listo.delivery/AGENTS.md
- https://docs.listo.delivery/es/quickstart.md
- https://docs.listo.delivery/es/guides/quote-and-create.md
- https://api.listo.delivery/docs/openapi.yaml (la forma de las peticiones y las respuestas)

Usa la llave de prueba de la variable de entorno LISTO_API_KEY. Construye una
función que pida una cotización y otra que cree un envío a partir de esa
cotización, con los errores manejados por `error.code`. Cuando una llamada falle,
abre el `doc_url` del cuerpo del error antes de reintentar. No inventes campos que
no estén en el documento OpenAPI.
```

### Verificar las firmas de los webhooks

```text theme={null}
Agrega a este proyecto un endpoint de webhooks que reciba eventos de Listo.

Lee primero esto:
- https://docs.listo.delivery/es/guides/webhooks.md
- https://docs.listo.delivery/es/concepts/signing.md

Verifica la firma sobre el cuerpo crudo de la petición antes de interpretarlo,
rechaza todo lo que sea más viejo que la tolerancia que indica la página, responde
2xx primero y haz el trabajo después, e ignora un id de evento que ya procesaste.
Escribe pruebas que firmen un cuerpo de ejemplo con un secreto de prueba y
comprueben que un cuerpo alterado se rechaza.
```

### Depurar una llamada fallida por su request id

```text theme={null}
Una llamada a la API de Listo falló. Su request id es <PEGA AQUÍ EL request_id>.

Lee primero esto:
- https://docs.listo.delivery/es/guides/debugging.md
- https://api.listo.delivery/AGENTS.md

Con la llave de solo lectura de LISTO_API_KEY, consulta esa llamada en
GET /v1/request_logs (filtra por request_id), lee el estatus, el código de error
y el cuerpo que se envió, y luego abre el `doc_url` de ese error. Dime qué salió
mal y qué cambiar en el código. No llames ningún endpoint que escriba.
```

### Conciliar mi saldo

```text theme={null}
Revisa que nuestros libros coincidan con el saldo de Listo.

Lee primero esto:
- https://docs.listo.delivery/es/guides/balance-and-withdrawals.md
- https://docs.listo.delivery/es/concepts/money.md
- https://api.listo.delivery/docs/openapi.yaml (las operaciones de saldo y movimientos)

Con la llave de solo lectura de LISTO_API_KEY, lee GET /v1/balance y recorre
GET /v1/ledger para el periodo que te indique. Explica cada tipo de movimiento con
las palabras de la guía, enumera los movimientos que no puedas asociar a un envío
e informa la diferencia entre el total de los movimientos y el saldo. No crees ni
cambies nada.
```

> [!NOTE]
>
> Estos prompts funcionan en cualquier agente que pueda abrir una URL o leer un
> archivo. Si el tuyo no puede navegar, descarga una vez `llms-full.txt` y
> `openapi.yaml`, ponlos en el proyecto y cambia las URL del prompt por las rutas de
> los archivos.


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