# Para agentes de IA

URL: https://staging.pagpolar.com/docs/guias/para-agentes-de-ia

> Entregue a especificação da API e dos webhooks a um assistente de IA para ele ajudar a escrever a sua integração.

Assistentes de IA escrevem código melhor quando recebem o contrato exato da API. A PagPolar publica esse contrato em arquivos OpenAPI, que qualquer assistente consegue ler.

## Arquivos disponíveis

Todos os arquivos ficam no endereço do portal, são públicos e não precisam de chave.

| Ambiente | Endereço do portal                  |
| -------- | ----------------------------------- |
| Produção | `https://app.pagpolar.com/docs`     |
| Staging  | `https://staging.pagpolar.com/docs` |

| Arquivo                                              | Conteúdo                                                                                                                                                         |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<portal>/llms.txt`                                  | Índice do portal para assistentes. Começa pelos links do OpenAPI e depois lista todas as páginas — guias, webhooks e referência — com título, endereço e resumo. |
| `<portal>/openapi.json`                              | Todas as operações da API, com parâmetros, corpos, respostas e erros (OpenAPI 3.0). É o arquivo que gera a [Referência da API](/docs/referencia).                |
| `<portal>/webhooks.json`                             | Os 15 eventos de webhook, com o formato de cada payload (OpenAPI 3.1). É o arquivo que gera o [Catálogo de eventos](/docs/webhooks/eventos).                     |
| `<portal>/llms-full.txt`                             | O conteúdo inteiro do portal num arquivo só.                                                                                                                     |
| qualquer página com `.mdx` no fim                    | O texto daquela página. Exemplo em Produção: `https://app.pagpolar.com/docs/guias/fundamentos/erros.mdx`.                                                        |
| qualquer página com o header `Accept: text/markdown` | O mesmo texto da versão `.mdx`, no endereço normal da página.                                                                                                    |
| `<portal>/api/search?query=`                         | Busca no conteúdo do portal, em JSON. Exemplo: `https://app.pagpolar.com/docs/api/search?query=reembolso`.                                                       |

Comece pelo `llms.txt` quando quiser que o assistente escolha o que ler; use o `llms-full.txt` quando quiser dar tudo de uma vez.

`openapi.json`, `webhooks.json` e `llms.txt` podem ficar em cache por até 5 minutos.

## Como usar com um assistente

1. Baixe os arquivos que a tarefa precisa. Para cobrar, baixe `openapi.json`. Para receber avisos, baixe também `webhooks.json`.
2. Anexe os arquivos na conversa com o assistente, ou cole o conteúdo.
3. Diga a linguagem, o que você quer fazer e as regras abaixo.

Exemplo de pedido:

```text
Anexei a especificação OpenAPI da API PagPolar e a dos webhooks.
Escreva, em Node.js, uma função que cria uma venda PIX com POST /payments/pix.
Regras:
- antes de tudo, chame POST /auth/token com o header X-API-Key vindo da variável
  de ambiente PAGPOLAR_API_KEY, e guarde o access_token da resposta em memória;
- o access_token vale 24 horas e vai no header Authorization, no formato
  "Bearer <access_token>", em POST /payments/pix e em qualquer outra rota;
- não existe rota de renovação: se a resposta for 401, peça outro token em
  POST /auth/token e repita a chamada uma única vez, com a mesma Idempotency-Key;
- gere uma Idempotency-Key por pedido e guarde antes de enviar;
- envie external_reference com o código do pedido;
- trate os erros no formato { error: { code, message, request_id } };
- não invente campos que não estão na especificação.
Depois, escreva o endpoint que recebe o webhook TRANSACTION_PAID e valida o header Authorization.
```

## Limites

* **O assistente pode errar.** Confira cada campo que ele usar na [Referência da API](/docs/referencia) antes de colocar o código no ar.
* **A especificação não traz todas as regras de negócio.** Leia os [Fundamentos](/docs/guias/fundamentos/credenciais) e a página [Processar eventos sem duplicar](/docs/webhooks/processar-sem-duplicar).
* **Teste o código com a chave de Homologação** e só troque pela de Produção quando o fluxo estiver conferido. Veja [Ambiente de testes](/docs/guias/fundamentos/ambientes#ambiente-de-testes).
* **Não cole a sua chave de API nem um token de acesso na conversa.** Use um placeholder, como `<SUA_CHAVE_DE_API>`. O token dá o mesmo acesso da chave [enquanto valer](/docs/guias/fundamentos/autenticacao#validade).