# Guía para agentes de IA

> Cómo leer esta documentación desde un asistente y qué reglas no puede saltearse una integración.

Esta documentación está pensada para que un asistente de código (o un agente) pueda leerla y escribir la integración. Cada página tiene su versión en Markdown agregando `.md` a la dirección.

| Recurso | Para qué |
| --- | --- |
| [llms.txt](https://turnovapp.com/docs/llms.txt) | Índice corto con cada página y su versión .md. |
| [llms-full.txt](https://turnovapp.com/docs/llms-full.txt) | Toda la documentación en un solo archivo de texto. |
| [openapi.yaml](https://turnovapp.com/docs/openapi.yaml) / [openapi.json](https://turnovapp.com/docs/openapi.json) | La especificación OpenAPI 3.1, fuente de la referencia. |

## Reglas para una integración correcta

1. La clave pública va en el navegador; la secreta, solo en el servidor. Nunca pongas una clave secreta en código que llegue al navegador.
2. Decidí por `error.codigo`, `error.recuperacion` y `error.reintentable`; no interpretes `mensaje`.
3. Toda reserva lleva una `Idempotency-Key` estable por intento. Reintentá solo con la misma clave y el mismo cuerpo.
4. No calcules precios ni horarios del lado del cliente para guardar: mostralos desde la API y dejá que la reserva los valide.
5. Tratá `progreso.principal: GUARDADO` con `pago: PENDIENTE` como reservado sin pagar, no como confirmado.
6. La seña se confirma solo por Mercado Pago; la vuelta de la clienta a tu sitio no es prueba de pago.
7. Respetá `Retry-After` en los 429.

## Ejemplo de pedido a un asistente

```text
Leé https://docs.turnovapp.com/llms.txt y armá en mi sitio (Next.js) un flujo de reserva
con la API de Turnova: catálogo, horarios, reserva con Idempotency-Key y redirección
a la seña de Mercado Pago. Usá la clave pública desde el navegador.
```