Idempotência: como evitar cobrança duplicada e pedidos repetidos

A internet oscila. O botão é clicado duas vezes. O app tenta de novo depois de um erro de rede. O webhook chega repetido. Em todos esses casos, a mesma operação pode ser executada mais de uma vez — e, com dinheiro envolvido, isso é grave.

O que é idempotência

Uma operação é idempotente quando executá-la várias vezes tem o mesmo efeito que executá-la uma vez. Consultar um pedido é naturalmente idempotente. Criar um pagamento não é — a menos que você o torne.

A chave de idempotência

O cliente gera um identificador único para cada intenção ("pagamento do pedido 123, tentativa de agora") e o envia junto. O servidor guarda o resultado associado à chave. Se a mesma chave chegar de novo, devolve o resultado salvo em vez de cobrar outra vez.

POST /pagamentos
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Onde aplicar

• Pagamentos e estornos.
• Criação de pedidos.
• Envio de mensagens e e-mails.
• Processamento de webhooks (Webhooks confiáveis: idempotência, retentativas e ordem dos eventos).
• Sincronização de apps offline (Offline-first: apps que continuam funcionando sem internet).

Complementos no front

Desabilite o botão após o clique e mostre que está processando (Formulários que convertem: validação em tempo real sem irritar o usuário). Retentativas automáticas só para operações idempotentes (Gerenciando o erro 429 Too Many Requests: exponential backoff e retry no cliente).

No banco

Restrições de unicidade e transações garantem que duas requisições simultâneas não passem ao mesmo tempo (Transações no banco: quando duas operações precisam acontecer juntas).

A We Codex constrói fluxos de pagamento confiáveis em e-commerces e sistemas. Fale com a gente.