Aparência
Idempotência (Idempotency-Key)
As rotas que movem dinheiro exigem o header Idempotency-Key, e as que criam cobrança o aceitam. Ele é um código gerado por quem chama a API e identifica uma operação. Se a mesma requisição chegar de novo com o mesmo código (duplo clique, timeout, retry automático), a API não executa outra vez: devolve a resposta da primeira.
Idempotency-Key: 6f1c2e0a-3b8d-4c1e-9a77-0d5f2b9e4c11Rotas
| Método | Rota | Header |
|---|---|---|
POST | /banking/pix/transfers/key | Obrigatório |
POST | /banking/pix/transfers/bank-account | Obrigatório |
POST | /banking/pix/transfers/copy-paste | Obrigatório |
POST | /banking/transfers (TED) | Obrigatório |
POST | /banking/boleto/payments/pay | Obrigatório |
POST | /billing/charges | Opcional |
POST | /banking/pix/qrcode/dynamic | Opcional |
Sem o header numa rota obrigatória, a resposta é 428, e nada é executado.
Nas demais rotas, o header é ignorado.
Como usar
- Gere um código novo (recomendado: UUID v4) para cada operação que o usuário inicia.
- Envie o mesmo código em todas as tentativas dessa operação.
- Para uma operação nova (outra cobrança, outro Pix), gere outro código.
O código vale por conta e por rota. O mesmo valor usado em rotas diferentes, ou por contas diferentes, não colide.
Comportamento
| Situação | Resposta |
|---|---|
| Código novo | Executa normalmente. A resposta fica guardada, menos se for 4xx |
| Código já concluído, mesmos dados | A resposta guardada (mesmo status e body), com o header Idempotent-Replayed: true. Nada é executado de novo |
| Código já concluído, dados diferentes | 422: Esta Idempotency-Key já foi usada com outros dados... |
| Código com requisição ainda em andamento | 409: Já existe uma requisição em andamento com esta Idempotency-Key. |
| Header vazio ou com mais de 255 caracteres | 422 |
A primeira tentativa terminou em 4xx (PIN errado, saldo insuficiente, recusa do banco) | A chave é liberada. A próxima tentativa com o mesmo código executa de novo |
A primeira tentativa terminou em 5xx ou exceção (ex.: banco sem resposta) | A resposta de erro fica guardada e é devolvida nas repetições, sem executar de novo: não dá para saber se o dinheiro saiu. Confira o extrato e, se for o caso, use um código novo |
- Mesmos dados: a comparação usa o body inteiro, menos o
pin. Errar o PIN e tentar de novo com o PIN certo usa o mesmo código. - Retenção: cada código fica guardado por 30 dias. Depois disso, ele é tratado como novo.
409que não some: se o processo da API cair no meio da operação, o código fica em andamento e continua respondendo409. Isso é proposital: num Pix, não há como saber se o dinheiro já saiu. Confira o resultado emGET /banking/pix/transfers(ou na lista de cobranças) antes de tentar com um código novo.