Instructions para agentes
Conteúdo objetivo para colar em qualquer IA antes de gerar código de integração com a API Pix da Pitra.
Base URL e autenticação#
| Item | Valor |
|---|---|
| Base URL | https://pitra.com.br/api/public/v1 |
| Header da API Key | Authorization: Bearer sk_live_... |
| Ambiente de teste | sk_test_... |
| Escrita idempotente | Idempotency-Key |
Fluxo recomendado#
1. Crie a cobrança: POST /payments/pix com Idempotency-Key e external_id do seu pedido.
2. Mostre ao pagador o Pix Copia e Cola e o QR Code devolvidos na resposta.
3. Aguarde o webhook pix.paid (fonte primária de confirmação).
4. Concilie com GET /payments/pix/external/{external_id} se o webhook não chegar.
5. Trate pix.expired como cobrança encerrada e crie outra com novo external_id.Tratamento de erros e retry#
Toda falha devolve { "error": { "code", "message", "request_id" } }. Repita apenas 429 e 5xx, com backoff exponencial e a mesma Idempotency-Key.
| Código | HTTP | Quando acontece |
|---|---|---|
invalid_request | 400 | Corpo ou parâmetros inválidos. |
authentication_required | 401 | Header Authorization ausente. |
invalid_api_key | 401 | Chave inexistente ou malformada. |
expired_api_key | 401 | Chave expirada. |
revoked_api_key | 401 | Chave revogada. |
insufficient_scope | 403 | A chave não tem o scope exigido. |
not_found | 404 | Recurso inexistente na sua loja. |
idempotency_conflict | 409 | Mesma Idempotency-Key com corpo diferente. |
idempotency_in_progress | 409 | Outra requisição com a mesma Idempotency-Key ainda está sendo processada. Aguarde e repita. |
method_not_allowed | 405 | Verbo de escrita em recurso somente leitura. |
rate_limited | 429 | Limite de requisições atingido. |
internal_error | 500 | Falha inesperada. Reenvie com backoff. |
Versão curta (colar no chat)#
Você é um desenvolvedor integrando a API Pix da Pitra.
- Utilize somente os endpoints documentados em https://pitra.com.br/docs/api.
- Nunca invente parâmetros, campos ou rotas.
- Utilize sempre a OpenAPI oficial: https://pitra.com.br/api/public/v1/openapi.json.
- Autentique com Bearer: Authorization: Bearer sk_live_... (ou sk_test_... em testes).
- Base URL: https://pitra.com.br/api/public/v1.
- Os webhooks seguem exatamente os eventos documentados e são assinados no header Pitra-Signature (HMAC SHA-256).Versão longa (regras de projeto)#
Salve como .cursorrules, regra de workspace no Windsurf ou instruções de projeto no Claude/ChatGPT.
# Regras de integração — API Pitra
Você é um desenvolvedor integrando a API Pix da Pitra.
## Fontes de verdade
- Documentação: https://pitra.com.br/docs/api
- OpenAPI (JSON): https://pitra.com.br/api/public/v1/openapi.json
- OpenAPI (YAML): https://pitra.com.br/api/public/v1/openapi.yaml
- Servidor MCP somente leitura da documentação: https://pitra.com.br/mcp
## Regras obrigatórias
1. Utilize somente os endpoints documentados. Se algo não estiver na OpenAPI, não existe.
2. Nunca invente parâmetros, campos de resposta, status ou nomes de evento.
3. Autenticação sempre por Bearer token: `Authorization: Bearer sk_live_...`. Chaves `sk_test_` operam em modo de teste, sem movimentação financeira.
4. Base URL: `https://pitra.com.br/api/public/v1`. Todos os recursos ficam sob esse prefixo.
5. Valores monetários em reais, com no máximo duas casas (ex.: `amount: 49.9`).
6. Envie `Idempotency-Key` em toda requisição de escrita. Em cobranças Pix, um `external_id` repetido devolve a cobrança existente com 200 em vez de duplicar.
7. Listagens usam paginação por cursor: `limit`, `starting_after`, e a resposta traz `has_more` e `next_cursor`.
8. Erros seguem `{ "error": { "code", "message", "request_id" } }`. Trate 429 com backoff exponencial.
9. Webhooks seguem exatamente os eventos documentados: product.created, product.updated, product.archived, checkout.created, checkout.updated, checkout.archived, sale.created, sale.approved, sale.refused, sale.canceled, sale.refunded, delivery.sent, pix.created, pix.paid, pix.expired.
10. Valide a assinatura do webhook (header `Pitra-Signature`, HMAC SHA-256 sobre o corpo bruto) antes de processar, e deduplique pelo `event_id`.
11. Nunca exponha a chave secreta no front-end. Todas as chamadas partem do seu servidor.
12. Não implemente cancelamento de cobrança Pix por API: a cobrança expira sozinha conforme `expires_in`.