API Keys
Todas as requisições à API devem incluir o header Pagozz-Token com sua chave de API.
curl https://api.pagozz.com/v1/links \
-H "Pagozz-Token: pgz_live_XXXXXXXXXXXXXXXXXXXXXXXX"
pgz_test_XXXXXXXXXXXXXXXXXXXXXXXX # Ambiente de teste (sandbox)
pgz_live_XXXXXXXXXXXXXXXXXXXXXXXX # Ambiente de produção
| Prefixo | Ambiente | Comportamento |
|---|
pgz_test_* | Test | Pagamentos simulados, sem cobrança real |
pgz_live_* | Live | Pagamentos reais processados via PIX |
Gerenciamento
Crie e gerencie suas chaves em Configurações → Chaves de API no painel do Pagozz.
| Ação | Descrição |
|---|
| Criar | Gera nova chave com scopes selecionados |
| Rotacionar | Gera nova chave com mesmos scopes, revoga a anterior |
| Revogar | Desativa a chave permanentemente |
A chave secreta é exibida apenas uma vez na criação (ou rotação). Guarde-a em um local seguro.
Scopes
Cada chave possui um conjunto de scopes que definem as permissões de acesso.
| Scope | Descrição |
|---|
links:read | Listar e visualizar links |
links:write | Criar, editar e excluir links |
payments:read | Consultar status de pagamentos |
payments:write | Criar pagamentos |
transactions:read | Listar e visualizar transações |
withdrawals:read | Listar e visualizar saques |
withdrawals:write | Solicitar saques |
webhooks:read | Listar e visualizar webhooks |
webhooks:write | Criar, editar e remover webhooks |
links:read, links:write, payments:read, payments:write, transactions:read.
Versionamento
A API usa versionamento por header no estilo Stripe. Inclua o header Pagozz-Version para fixar a versão:
curl https://api.pagozz.com/v1/links \
-H "Pagozz-Token: pgz_test_..." \
-H "Pagozz-Version: 2026-03-15"
2026-03-15 será usada. Toda resposta inclui o header Pagozz-Version indicando a versão utilizada.
| Versão | Status |
|---|
2026-03-15 | Atual (padrão) |
Política de evolução
- Adições (novos campos, novos endpoints) não geram nova versão
- Mudanças incompatíveis geram nova versão com data nova
- Versões antigas continuam funcionando por pelo menos 12 meses
- Depreciações são comunicadas no changelog e por email
Rate Limiting
A API possui limites de requisições por conta:
| Contexto | Limite |
|---|
| Autenticado (API key) | 100 req/min por conta |
| Público | 20 req/min |
429 Too Many Requests. O SDK retenta automaticamente com backoff exponencial.
Segurança
- Chaves são armazenadas como hash SHA-256 no banco de dados
- Validação usa comparação timing-safe
- Todas as requisições são logadas (método, path, status, duração)
- Máximo de 10 chaves por conta
