Idempotência
Use Idempotency-Key para deduplicar requisições e fazer retry seguro.
Para todas as operações de escrita (criar pagamento, cobrança, registrar
webhook, etc.), você pode enviar o header Idempotency-Key com
um identificador único gerado pelo seu sistema. Isso garante que, se a
requisição for reenviada, a Stater devolverá a mesma resposta sem criar
um novo recurso.
Como usar
bash
curl -X POST https://api.staterpay.io/v1/payouts \-H "Authorization: Bearer SUA_API_KEY" \-H "Idempotency-Key: 4a51b6c2-2cd0-4d06-b5e2-2e9d4d7e5e3f" \-H "Content-Type: application/json" \-d '{ "pixKey": "fulano@example.com", "pixKeyType": "EMAIL", "amountCents": "1000" }'Regras
- A chave deve ser única por operação (UUID v4 é uma boa escolha).
- Reenvie a mesma chave + mesmo body para receber a resposta original.
- Reenviar a mesma chave com body diferente retorna
409 conflict. - Janela de retenção: 24 horas. Após esse período, a chave pode ser reaproveitada.
Boa prática
Gere a Idempotency-Key antes de enviar a requisição e
persista-a junto com o registro local. Em retries, sempre use a mesma
chave para o mesmo recurso lógico.