O problema que a idempotência resolve é simples de descrever. Seu servidor envia o pedido de cobrança, a conexão cai e a resposta não chega. A cobrança foi criada ou não? Se você repetir sem proteção, pode gerar dois Pix para o mesmo pedido. Num saque, pode debitar o saldo duas vezes.
Como funciona
A solução comum é o cliente mandar uma chave única junto com o pedido. O servidor guarda a chave e, se receber de novo a mesma chave com o mesmo pedido, devolve o resultado da primeira vez em vez de executar outra vez. A chave identifica a intenção, por exemplo "cobrar o pedido 1234", e não a tentativa.
Na API da xFlow
O header é Idempotency-Key. Ele é opcional, e a documentação recomenda enviar sempre:
| Endpoint | Efeito da mesma chave num retry |
|---|---|
POST /api/v1/charges |
Devolve a mesma cobrança em vez de gerar outro Pix. |
POST /api/v1/transfers |
Devolve o mesmo saque em vez de debitar o saldo de novo. |
Reusar a chave com um corpo diferente retorna 409 idempotency_conflict. A mesma chave só vale para repetir o mesmo pedido. O comportamento é igual no modo de teste.
O estorno tem uma regra própria: repetir POST /api/v1/charges/{id}/refund na mesma cobrança devolve o mesmo estorno, sem estornar de novo.
Exemplo
curl -X POST https://app.xflowpayments.com/api/v1/charges \
-u "pk_live_...:sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1234" \
-d '{"amountCents":1990,"customer":{"name":"Cliente","email":"c@exemplo.com","document":"00000000000"}}'Se essa chamada for repetida, com a mesma chave e o mesmo corpo, a resposta traz a mesma cobrança. Use como chave algo que já é único no seu sistema, como o id do pedido ou do repasse.
Idempotência do seu lado
A regra vale nos dois sentidos. A xFlow reenvia um webhook até 3 vezes quando não recebe 2xx, então o seu sistema pode receber o mesmo evento mais de uma vez. O tratamento do evento também precisa ser idempotente: se o pedido já foi baixado, ignore. O tema completo, com exemplos de código, está em idempotência em API de pagamento.
Termos relacionados
- Webhook: o outro lado da idempotência, nos eventos que chegam ao seu sistema.
- End-to-end ID: o identificador único de cada Pix, útil para conferir se um pagamento já foi conciliado.
- API de saque Pix: onde a
Idempotency-Keyevita saque em dobro. - Erros da API Pix: o que fazer com o
409 idempotency_conflict.