Skip to content

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-0d5f2b9e4c11

Rotas ​

MétodoRotaHeader
POST/banking/pix/transfers/keyObrigatório
POST/banking/pix/transfers/bank-accountObrigatório
POST/banking/pix/transfers/copy-pasteObrigatório
POST/banking/transfers (TED)Obrigatório
POST/banking/boleto/payments/payObrigatório
POST/billing/chargesOpcional
POST/banking/pix/qrcode/dynamicOpcional

Sem o header numa rota obrigatória, a resposta é 428, e nada é executado.

Nas demais rotas, o header é ignorado.

Como usar ​

  1. Gere um código novo (recomendado: UUID v4) para cada operação que o usuário inicia.
  2. Envie o mesmo código em todas as tentativas dessa operação.
  3. 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çãoResposta
Código novoExecuta normalmente. A resposta fica guardada, menos se for 4xx
Código já concluído, mesmos dadosA resposta guardada (mesmo status e body), com o header Idempotent-Replayed: true. Nada é executado de novo
Código já concluído, dados diferentes422: Esta Idempotency-Key já foi usada com outros dados...
Código com requisição ainda em andamento409: Já existe uma requisição em andamento com esta Idempotency-Key.
Header vazio ou com mais de 255 caracteres422
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.
  • 409 que não some: se o processo da API cair no meio da operação, o código fica em andamento e continua respondendo 409. Isso é proposital: num Pix, não há como saber se o dinheiro já saiu. Confira o resultado em GET /banking/pix/transfers (ou na lista de cobranças) antes de tentar com um código novo.