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

# Conecta Claude, Cursor o Codex

> Deja que tu asistente de IA cotice, reserve, siga y administre envíos con tu llave de API, con un paso de confirmación antes de que se mueva dinero.

Listo tiene un servidor MCP. Cuando conectas tu asistente de IA a él, puedes
pedirle con palabras normales que cotice un envío, lo reserve, le dé
seguimiento, revise tu saldo o lea tu libro mayor, y lo hace con tu propia
llave de API. Es una segunda puerta a la misma API: cada herramienta ejecuta el
endpoint `/v1/` que le corresponde, con las mismas reglas, los mismos errores y
los mismos límites que ya conoces del resto de esta documentación.

El servidor está en:

```text theme={null}
https://api.listo.delivery/mcp
```

Habla MCP sobre HTTP con streaming (Streamable HTTP) y se autentica igual que la
API: `Authorization: Bearer <tu llave de API>`. Iniciar sesión con el navegador
(OAuth) todavía no está disponible.

> [!TIP]
>
> **Practica con una llave de prueba**
>
> Usa una **llave de prueba** la primera vez. Una llave de prueba solo ve y
> cambia cosas de prueba: el repartidor es simulado, el dinero es ficticio y no se
> reserva nada real (ve [el modo de prueba](https://docs.listo.delivery/es/concepts/test-mode.md)). Cambia
> a una llave real cuando el asistente haga lo que esperas. La primera herramienta
> que conviene llamar es `whoami`, que dice para qué cuenta actúa la conexión y si
> la llave es de prueba o real.

## Conecta tu cliente

Primero guarda tu llave en una variable de entorno, para que nunca quede en un
archivo de configuración que podrías subir a un repositorio:

```bash theme={null}
export LISTO_API_KEY="tu llave aquí"
```

### Claude Code

```bash theme={null}
claude mcp add --transport http listo https://api.listo.delivery/mcp --header 'Authorization: Bearer ${LISTO_API_KEY}'
```

Usa las comillas simples tal como se muestran. Claude Code expande `${LISTO_API_KEY}`
cada vez que se conecta, así que la llave nunca se escribe en su archivo de
configuración.

### Cursor

Agrega esto a `mcp.json` (el `.cursor/mcp.json` del proyecto, o el global en tu
carpeta de usuario):

```json theme={null}
{
  "mcpServers": {
    "listo": {
      "url": "https://api.listo.delivery/mcp",
      "headers": {
        "Authorization": "Bearer ${env:LISTO_API_KEY}"
      }
    }
  }
}
```

Cursor lee `${env:LISTO_API_KEY}` de su propio entorno, así que una llave exportada
en una terminal no la ve un Cursor abierto desde el dock. Define la variable en el
perfil de tu shell o en el entorno del sistema, y reinicia Cursor.

### Codex

```bash theme={null}
codex mcp add listo --url https://api.listo.delivery/mcp --bearer-token-env-var LISTO_API_KEY
```

### ChatGPT

El inicio de sesión para ChatGPT viene en camino. Necesita el inicio de sesión
con navegador que este servidor todavía no ofrece, así que por ahora usa alguno
de los clientes de arriba.

## Qué puede hacer el asistente

Las herramientas, agrupadas por para qué sirven. Una herramienta marcada
**pide confirmación** mueve o cobra dinero, o termina un servicio de pago, y
funciona en dos pasos (siguiente sección).

### Cuenta y saldo

| Herramienta | Qué hace |
| - | - |
| `whoami` | Para qué cuenta actúa la conexión y si la llave es de prueba o real. |
| `get_balance` | Tu saldo, lo que se puede retirar hoy y la parte en revisión. |
| `list_ledger` | Cada movimiento de tu saldo, del más reciente al más antiguo. |
| `get_store_balance` | El saldo del que gasta una tienda. |
| `list_store_ledger` | Los movimientos del saldo de esa tienda. |

### Tiendas

| Herramienta | Qué hace |
| - | - |
| `list_stores` | Tus tiendas, de la más reciente a la más antigua; encuentra una por tu propio `external_id`. |
| `get_store` | Una tienda: dirección, notas de recolección, nivel de acceso y plan. |
| `create_store` (**pide confirmación**) | Registra un punto de recolección. Con una llave real puede iniciar el plan de la tienda y cobrar el primer mes. |
| `update_store` | Cambia una tienda. Las reservas ya hechas no se afectan. |
| `invite_store_owner` | Le manda por correo a quien lleva la tienda un enlace para que elija su propia contraseña. |
| `start_card_onboarding` | Inicia la configuración de pagos con tarjeta para una tienda o para la empresa, y devuelve un enlace de un solo uso para quien responde por el negocio. |
| `get_card_status` | Si una tienda o la empresa ya puede cobrar con tarjeta, y qué falta. |
| `connect_existing_restaurant` | Inicia el flujo que conecta un restaurante que ya usa Listo y devuelve el enlace para su dueño (solo con llaves reales). |
| `complete_connection` | Cambia el código que devuelve la aprobación del dueño por la tienda conectada. |

### Envíos

| Herramienta | Qué hace |
| - | - |
| `quote_delivery` | Cotiza un envío desde una de tus tiendas y sostiene ese precio por un rato corto. No reserva nada. |
| `create_delivery` (**pide confirmación**) | Reserva un repartidor al precio de una cotización. |
| `list_deliveries` | Tus envíos, del más reciente al más antiguo, con filtros. |
| `get_delivery` | Un envío: estado, repartidor, pago, tarifa y enlace de seguimiento. |
| `update_delivery` | Mueve una recolección programada o corrige la nota de entrega para el repartidor. |
| `cancel_delivery` (**pide confirmación**) | Cancela un envío que no se ha entregado. Si ya hay repartidor asignado, puede costar dinero. |
| `retry_delivery` (**pide confirmación**) | Vuelve a buscar repartidor para un envío que nadie tomó. Se cotiza y se cobra de nuevo. |
| `refund_delivery` (**pide confirmación**) | Le devuelve dinero a un cliente en un envío pagado con tarjeta, completo o en parte. |

### Retiros

| Herramienta | Qué hace |
| - | - |
| `request_withdrawal` (**pide confirmación**) | Pide una transferencia de tu saldo a tu cuenta de banco registrada. |
| `list_withdrawals` | Tus solicitudes de retiro, de la más reciente a la más antigua. |
| `get_withdrawal` | Un retiro: monto, estado y, ya pagado, la clave de rastreo de la transferencia. |

### Planes

| Herramienta | Qué hace |
| - | - |
| `cancel_store_plan` (**pide confirmación**) | Da de baja el plan de una tienda. Sigue funcionando hasta el final del periodo ya pagado. |
| `undo_plan_cancellation` (**pide confirmación**) | Revierte esa baja antes de que surta efecto. |
| `reactivate_store_plan` (**pide confirmación**) | Reinicia el plan de una tienda que ya terminó, cobrando el primer mes en ese momento. |

Las tres herramientas de plan funcionan solo con llaves reales. Qué es un plan y
cuándo se cobra está en [plan y cobro](https://docs.listo.delivery/es/guides/plan-and-billing.md).

### Registros, eventos y webhooks

| Herramienta | Qué hace |
| - | - |
| `search_api_logs` | Tus llamadas recientes a la API, de la más reciente a la más antigua, filtradas por estado, endpoint, request\_id o fecha. |
| `get_api_log` | Una llamada, con el cuerpo de la petición que enviaste y el de la respuesta que recibiste. |
| `list_events` | Los eventos que Listo emitió para ti, los haya recibido o no tu endpoint. |
| `get_event` | Un evento, tal como se le envía a tu endpoint. |
| `list_webhook_deliveries` | Cada intento de entregar un evento a tu endpoint: qué respondió, cuánto tardó y si contó como exitoso. |
| `resend_event` | Envía un evento a tu endpoint una vez más. Actúa de inmediato y no pide confirmación, porque no mueve dinero. |
| `send_test_webhook` | Envía a tu URL de webhook un evento sintético de cualquier tipo publicado. Actúa de inmediato y no pide confirmación. |

Las dos que envían actúan en el momento en que se llaman, con los mismos límites
de los endpoints de la API que tienen detrás. El intento que provocan se lee con
`list_webhook_deliveries`. Cómo usar todas estas para averiguar por qué no
funciona una integración está en
[depurar tu integración](https://docs.listo.delivery/es/guides/debugging.md#depura-con-tu-asistente-de-ia).

### Comentarios

| Herramienta | Qué hace |
| - | - |
| `submit_feedback` | Le dice a Listo qué no pudo hacer el asistente, o qué faltó o fue confuso, para que las herramientas mejoren. Unas pocas por hora. |

Las listas son de 50 por página, igual que en la API: cuando una respuesta dice
que hay más, el asistente regresa el cursor `next` para leer la página
siguiente.

## Nada mueve dinero hasta que lo digas

Cada herramienta marcada **pide confirmación** funciona en dos pasos, y al
asistente se le indica que se detenga entre ellos y te muestre lo que está por
pasar:

1. **La vista previa.** El asistente llama la herramienta con los detalles. No
   pasa nada. Recibe lo que *pasaría* (en una reserva: el precio, la tienda, el
   destino) y un `confirmation_token`, y te lo muestra.
2. **La confirmación.** Solo cuando tú apruebas, llama la herramienta otra vez
   con exactamente los mismos argumentos más `confirm: true` y el token. Ese es
   el momento en que se mueve el dinero.

Qué lo hace seguro:

* **Reservar siempre usa una cotización.** `create_delivery` exige el
  `quote_id` de `quote_delivery`, así que el precio que te mostraron es el
  precio que se reserva. Si la cotización venció o ya se usó, la reserva se
  rechaza y el asistente cotiza de nuevo.
* **Un token sirve una vez y por diez minutos.** Pertenece a tu llave, a esa
  herramienta y a esos argumentos exactos: si cambias el monto o el envío, el
  token se rechaza, y el error no lo gasta. Un token que nadie usó se rechaza como
  `confirmation_expired` cuando pasan los diez minutos: pide una vista previa nueva.
* **Confirmar de nuevo nunca actúa dos veces.** Si se confirma el mismo token
  otra vez, por ejemplo porque el asistente reintentó tras una conexión caída,
  devuelve el primer resultado y no reserva, cancela ni retira nada por segunda
  vez. Esa repetición se mantiene 24 horas después de que el token venció. Pasado
  ese tiempo el registro ya no existe y confirmar responde
  `confirmation_not_found`: que el asistente lea primero el recurso (por ejemplo
  con `get_delivery`) antes de pedir una vista previa nueva.
* **Una llave de solo lectura no recibe vista previa.** Con una llave de solo
  lectura, una herramienta que pide confirmación se rechaza desde el primer
  paso con `read_only_key` y no se emite ningún token, porque la confirmación
  solo podría fallar. Enviar comentarios con `submit_feedback` sí sigue
  funcionando.

> [!WARNING]
>
> **Deja activa la aprobación de tu propio cliente**
>
> Los dos pasos son la protección de Listo. Tu cliente tiene la suya: Claude Code,
> Cursor y Codex pueden preguntarte antes de ejecutar una herramienta. Déjala
> activa, al menos para las herramientas que piden confirmación, para que una
> persona vea cada llamada que puede mover dinero y no solo la vista previa.

## Límites y registros

* Una llamada a una herramienta es una petición a la API contra los límites de
  tu llave, los mismos de siempre (ve
  [sal a producción](https://docs.listo.delivery/es/guides/go-live.md#límites-de-tasa)). Al pasarte de
  un límite, el asistente recibe `rate_limited`. Cualquier error que le pida esperar
  (`rate_limited`, `resend_limit_reached` y `test_webhook_limit_reached`) trae
  `retry_after_seconds`, los segundos que debe esperar antes de reintentar la misma llamada.
* Cada llamada a una herramienta aparece en tus registros de la API como
  cualquier petición `/v1/`, excepto `submit_feedback`, que no llama a ninguna
  ruta `/v1/`, y una vista previa que se le rechazó a una llave de solo lectura,
  que nunca llega a una.
* Los errores son los de la API: el asistente ve el mismo `code` y el mismo
  `retryable` que verías tú, y decide con ellos de la misma manera. Cada error
  trae además un `doc_url` y un `request_id`, que es el `X-Request-Id` de esa
  respuesta de `/mcp`.

## Cuando las herramientas no alcanzan

Si el asistente necesita algo que ninguna herramienta ofrece, puede decirlo con
`submit_feedback`. Así sabemos qué agregar después.


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