# Para IAs (LLMs) (/docs/cartao/for-ai)
A documentação do Cartão também é servida em texto puro para assistentes de IA. Você pode colar uma URL fixa no chat ou carregar o arquivo inteiro no contexto.
Esta doc é da API **Cartão** (`https://api.payzu.io/v1`, mTLS + token Bearer obtido em `POST /token`, valores em **centavos**). A API **Pix** é outro sistema (`https://api.payzu.processamento.com/v1`, Bearer, valores em **reais**) e tem doc própria. Nunca misture as duas na mesma integração.
## Endpoints para IAs [#endpoints-para-ias]
| URL | O que tem |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`/cartao/llms.txt`](https://docs.payzu.com.br/cartao/llms.txt) | Índice em markdown com link e descrição de toda página **só do Cartão**. |
| [`/cartao/llms-full.txt`](https://docs.payzu.com.br/cartao/llms-full.txt) | **Toda** a doc do Cartão concatenada em um arquivo. |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt) | Índice global (todos os produtos PayZu juntos). |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt) | Dump global (todos os produtos PayZu juntos). |
| [`/cartao-openapi.json`](https://docs.payzu.com.br/cartao-openapi.json) | Especificação OpenAPI 3 da API Cartão: endpoints, schemas e erros. |
| [`/api-scalar-cartao`](https://docs.payzu.com.br/api-scalar-cartao) | Renderização Scalar interativa do OpenAPI. |
| [`/api-swagger-cartao`](https://docs.payzu.com.br/api-swagger-cartao) | Renderização Swagger UI do OpenAPI. |
O dump específico `/cartao/llms-full.txt` traz só o Cartão. O dump global `/llms-full.txt` reúne Cartão e Pix no mesmo arquivo, com base URL, autenticação (mTLS × Bearer) e unidade de valor (centavos × reais) diferentes.
## Por página [#por-página]
Toda página da doc tem o conteúdo equivalente em markdown puro. Substitua `/docs/...` por `/llms.mdx/docs/.../content.md`:
| Página HTML | Markdown bruto |
| ----------------------------- | ------------------------------------------------- |
| `/docs/cartao` | `/llms.mdx/docs/cartao/content.md` |
| `/docs/cartao/webhooks` | `/llms.mdx/docs/cartao/webhooks/content.md` |
| `/docs/cartao/three-d-secure` | `/llms.mdx/docs/cartao/three-d-secure/content.md` |
No topo de cada página ficam os botões **Perguntar à IA**, **Copiar para LLM** (copia o markdown da página) e **Ver como Markdown** (abre o markdown da página).
## Casos de uso [#casos-de-uso]
### Pergunta rápida no ChatGPT/Claude [#pergunta-rápida-no-chatgptclaude]
Cole a URL `https://docs.payzu.com.br/cartao/llms-full.txt` na conversa e peça algo concreto:
```text
Doc da API Cartão PayZu: https://docs.payzu.com.br/cartao/llms-full.txt
Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1).
Autenticação: certificado de cliente (mTLS) em toda chamada + token Bearer obtido em
POST /token com Basic Auth (client_id:client_secret) e grant_type client_credentials.
Valores em centavos.
Me mostre um exemplo em Node.js que:
1. Obtém o token em POST /token usando o certificado mTLS.
2. Cria uma cobrança de R$ 100,00 ("amount": 10000) em POST /charges com postbackUrl.
3. Recebe o webhook e valida a assinatura antes de processar: HMAC-SHA256 sobre
".." com o webhook secret,
comparado com X-Webhook-Signature; recusa timestamp (em milissegundos) com mais
de 5 minutos.
4. Deduplica pelo id da cobrança + transição de status.
```
### Cursor / Copilot no editor [#cursor--copilot-no-editor]
Crie um arquivo `.cursorrules` ou `.github/copilot-instructions.md` no seu repo:
```text
Você está integrando com a API Cartão da PayZu. É um sistema independente da API Pix.
Regras invioláveis:
- Base URL: https://api.payzu.io/v1 (sandbox: https://api.sandbox.payzu.io/v1)
- Toda chamada usa o certificado de cliente (mTLS) fornecido pela PayZu
- Token: POST /token com Basic Auth (client_id:client_secret) e {"grant_type": "client_credentials"};
as demais rotas recebem Authorization: Bearer
- Valores (amount, unitPrice) em centavos (R$ 10,90 = 1090); cotações de câmbio (rate.bid, rate.ask) são decimais
- Webhook: POST na postbackUrl da cobrança. Valide X-Webhook-Signature (HMAC-SHA256 em hex sobre
"timestamp.nonce.payload" com o webhook secret) e recuse X-Webhook-Timestamp (milissegundos)
com mais de 5 minutos
- Responda o webhook com 2xx em até 5 s; uma entrega que falha tem até 5 retentativas
- Deduplique webhooks pelo id da cobrança + transição de status, nunca pelo X-Webhook-Nonce
- POST /charges não é idempotente: num timeout, procure o seu externalId em GET /charges
(startDate e endDate) antes de repetir, senão a cobrança sai em dobro
- Estorno (PUT /charges/{chargeId}/reverse) é sempre do valor total, uma vez por cobrança; não envie amount
- NUNCA use api.payzu.processamento.com (essa é a API Pix: Bearer, valores em reais)
Referência completa: https://docs.payzu.com.br/cartao/llms-full.txt
OpenAPI: https://docs.payzu.com.br/cartao-openapi.json
```
### RAG / vector store [#rag--vector-store]
O `/cartao/llms-full.txt` é o arquivo para indexar a doc do Cartão em um vector store (Pinecone, Qdrant, Supabase pgvector). Cada `## seção` funciona como um chunk.
### Geração de código [#geração-de-código]
Para gerar um cliente HTTP, aponte a IA para o `/cartao-openapi.json`:
```text
Gere um cliente TypeScript tipado para esta API de Cartão:
https://docs.payzu.com.br/cartao-openapi.json
Base URL https://api.payzu.io/v1, mTLS + token Bearer de POST /token, valores em centavos.
Use Zod para validação de runtime e undici com o certificado de cliente.
```
## Atualização [#atualização]
Toda mudança publicada na doc atualiza `/cartao/llms.txt`, `/cartao/llms-full.txt` e o markdown de cada página no próximo deploy. O `/cartao-openapi.json` muda quando a API ganha endpoints novos ou mudanças de schema.