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. |
<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. |
<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
- Baixe os arquivos que a tarefa precisa. Para cobrar, baixe
openapi.json. Para receber avisos, baixe tambémwebhooks.json. - Anexe os arquivos na conversa com o assistente, ou cole o conteúdo.
- Diga a linguagem, o que você quer fazer e as regras abaixo.
Exemplo de pedido:
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 antes de colocar o código no ar.
- A especificação não traz todas as regras de negócio. Leia os Fundamentos e a página Processar eventos 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.
- 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.