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

# LLMs y agentes

> Como usar las docs de SimplePay con LLMs, Cursor, Claude, ChatGPT, MCP, Markdown export, llms.txt y skill.md sin perder contexto ni seguridad.

SimplePay Docs esta configurado para humanos y agentes:

* Menu contextual con copy page, view Markdown, ChatGPT, Claude, Cursor, VS Code y MCP.
* Cada pagina expone Markdown agregando `.md`.
* Mintlify publica `/llms.txt` y `/llms-full.txt`.
* Este repo incluye `/skill.md` con capacidades, reglas y flujos canonicos.
* La referencia OpenAPI esta disponible en `/openapi.json`.

## URLs para agentes

| Recurso          | Uso                                                              |
| ---------------- | ---------------------------------------------------------------- |
| `/llms.txt`      | Indice de paginas con descripciones.                             |
| `/llms-full.txt` | Toda la docs en un solo archivo de contexto.                     |
| `/skill.md`      | Capacidades y workflows que un agente puede seguir.              |
| `/mcp`           | Search MCP server de Mintlify, cuando el deployment lo habilite. |
| `/openapi.json`  | Contrato exacto de endpoints y schemas.                          |
| `/quickstart.md` | Version Markdown del quickstart.                                 |

## Instalar el skill

<Prompt description="Instala el skill de SimplePay en tu agente." actions={["copy", "cursor"]}>
  npx skills add [https://docs.simplepay.mx](https://docs.simplepay.mx)
</Prompt>

## Como pedir una integracion

Buen prompt:

```txt prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Usa la documentacion de SimplePay. Integra Hosted Checkout en mi backend.
Requisitos:
- API base: https://api.simplepay.mx
- API key desde SIMPLEPAY_API_KEY
- Crear POST /v1/hosted-checkout/sessions en el backend
- Usar Idempotency-Key deterministica basada en order.id
- Guardar spcs_... y client_reference_id
- No marcar pagado por success_url
- Agregar webhook con verificacion SimplePay-Signature
- Deduplicar por event.id
Consulta /openapi.json para request/response exactos.
```

Mal prompt:

```txt bad-prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Haz pagos con SimplePay rapido.
```

## Reglas para agentes

<Warning>
  Nunca pegues una API key real en un prompt. Usa placeholders como
  `spk_sandbox_...` y variables de entorno.
</Warning>

Un agente debe:

* Leer `/openapi.json` antes de generar clientes tipados.
* Preferir Hosted Checkout para una primera integracion.
* Usar `Idempotency-Key` en writes.
* Crear handlers webhook idempotentes.
* No confirmar pagos por redirect.
* No guardar secrets en metadata.
* Usar solo endpoints publicos documentados.
* Usar sandbox antes de live.

## Markdown export

Puedes copiar una pagina como Markdown desde el menu contextual o abrir:

```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://docs.simplepay.mx/quickstart.md
https://docs.simplepay.mx/bookable-payments/quickstart.md
https://docs.simplepay.mx/webhooks/overview.md
```

Tambien puedes pedir Markdown por header:

```bash terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -L -H "Accept: text/markdown" "https://docs.simplepay.mx/quickstart"
```

## Contexto minimo por tarea

| Tarea              | Dale al agente                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------- |
| Primer checkout    | `/quickstart.md`, `/payments/checkout-sessions.md`, `/webhooks/overview.md`                 |
| Payment links      | `/payments/payment-links.md`, `/webhooks/overview.md`                                       |
| Bookable           | `/bookable-payments/overview.md`, `/bookable-payments/quickstart.md`, `/webhooks/events.md` |
| Cliente API tipado | `/openapi.json`, `/api-reference/overview.md`                                               |
| Debug webhook      | `/webhooks/overview.md`, `/webhooks/local-testing.md`                                       |

## Patrón de respuesta esperado

Cuando un agente implemente SimplePay, deberia entregar:

* Variables de entorno requeridas.
* Endpoint backend que llama SimplePay.
* UI o redirect que usa la URL retornada.
* Persistencia de IDs SimplePay.
* Webhook firmado y deduplicado.
* Tests para idempotencia y firma.
* Instrucciones de sandbox smoke.

<Tip>
  Para ahorrar tokens, empieza con `/agents/context-pack.md`; trae un resumen
  copy-paste de todo lo esencial.
</Tip>