Sistemas / SYS.007Explicado

Idempotência: como evitar que uma automação faça a mesma coisa duas vezes

Uma requisição falhou e o sistema tentou de novo. O cliente foi cobrado duas vezes? Entenda o que é idempotência e como ela torna repetições seguras.

Uma automação envia um pedido de pagamento para uma API. De repente, a conexão cai antes da resposta chegar. O pagamento aconteceu ou não? Se a automação tentar de novo e a primeira tentativa tiver funcionado, o cliente é cobrado duas vezes. Se não tentar, talvez o pagamento nunca aconteça. A saída para esse dilema tem um nome técnico pouco amigável: idempotência.

Neste explicado, você vai entender o que é idempotência, por que ela aparece em todo sistema que conversa pela internet e como aplicar a ideia nas suas integrações e automações.

O que é idempotência

Uma operação é idempotente quando executá-la várias vezes produz o mesmo efeito que executá-la uma vez. Apertar o botão do elevador é um bom exemplo: apertar cinco vezes não chama cinco elevadores.

Em sistemas, a diferença aparece entre “defina o saldo como 100” e “adicione 10 ao saldo”. A primeira é idempotente: repetir não muda o resultado. Por outro lado, a segunda, não: cada repetição soma mais 10.

No protocolo HTTP, leituras como GET são idempotentes por definição. Já operações que criam algo, geralmente com POST, não são. Por isso, um pedido de pagamento repetido pode virar dois pagamentos, a menos que o sistema tenha uma proteção.

Por que repetições acontecem

Em sistemas distribuídos, repetir é inevitável. Por exemplo, uma requisição pode falhar por queda de rede, tempo esgotado ou erro temporário do servidor. Em muitos desses casos, quem enviou não sabe se a operação foi feita.

Além disso, plataformas de mensagens e webhooks costumam garantir que uma mensagem chegue pelo menos uma vez, não exatamente uma vez. Ou seja, o mesmo aviso pode chegar duas vezes, e o sistema que recebe precisa lidar com isso. Esse é o mesmo cuidado que aparece em webhook ou polling, quando falamos em descartar entregas repetidas.

Chaves de idempotência

A solução mais comum é a chave de idempotência. Nesse caso, quem envia gera um identificador único para cada operação e o manda junto com a requisição. Se a mesma requisição chegar de novo com a mesma chave, o servidor reconhece e devolve o resultado da primeira vez, sem executar outra vez.

A documentação da Stripe, plataforma de pagamentos, descreve bem o funcionamento:

  • O cliente envia a chave no cabeçalho Idempotency-Key.
  • A Stripe recomenda gerar a chave com UUID versão 4 ou outra sequência aleatória com entropia suficiente, com até 255 caracteres.
  • Assim, a Stripe guarda a resposta da primeira requisição, e as repetições com a mesma chave recebem essa resposta.
  • O sistema pode descartar as chaves depois de pelo menos 24 horas.
  • Se uma repetição chegar com a mesma chave, mas parâmetros diferentes, a API devolve erro, para evitar uso indevido.
Fluxo de uma requisição com chave de idempotência: a automação envia o pagamento com uma chave única, a conexão cai, a automação repete com a mesma chave, o servidor reconhece a chave e devolve o resultado da primeira execução, sem cobrar de novo.
A chave transforma “tentar de novo” numa operação segura.

Um cuidado do mesmo guia: não use dados sensíveis, como e-mails ou documentos, como chave.

Como aplicar idempotência nas suas automações

Mesmo que a API que você usa não aceite chaves de idempotência, dá para proteger o seu lado. Um caminho possível:

  1. Dê um identificador a cada operação. Pode ser o ID do pedido, do formulário ou do evento que disparou a automação.
  2. Registre o que já foi feito. Em geral, uma tabela ou planilha com os identificadores processados basta para começar.
  3. Confira antes de agir. Se o identificador já está registrado, a automação pula a ação.
  4. Registre depois de concluir. Assim, uma falha no meio não marca como feito algo que não foi.
  5. Prefira operações que definem estado. “Marcar pedido como pago” é mais seguro que “somar um pagamento”.
Fluxo de uma automação idempotente: chega um evento com identificador, a automação consulta o registro de identificados já processados, se o identificador já existe pula a ação, se não existe executa a ação e só então registra o identificador como concluído.
O registro de processados funciona como a memória da automação.

No n8n, por exemplo, isso pode ser feito com um nó que consulta um banco de dados ou uma planilha antes da ação principal. Se você já integra APIs nesse tipo de ferramenta, vale revisar o guia sobre como integrar uma API no n8n com essa pergunta em mente: o que acontece se este fluxo rodar duas vezes com o mesmo dado?

A pergunta que evita o pior erro

A idempotência parece detalhe técnico até o dia em que um cliente reclama de uma cobrança duplicada ou recebe o mesmo e-mail três vezes. Por isso, vale incluir uma pergunta no desenho de toda automação que cria, cobra ou envia algo: se esta etapa rodar de novo, o que acontece? Se a resposta for “nada de errado”, o fluxo está protegido. Caso contrário, uma chave e um registro resolvem a maior parte do problema. O mesmo cuidado vale para quem processa uma fila de mensagens ou repete chamadas depois de receber um erro 429.

/ Conexões

Próximas conexões

Autor

Gledson Dias

Ver todos os artigos

Sistemativo / Brief

Gostou dessa ideia?

A cada duas semanas, ideias, ferramentas, referências e movimentos que valem alguns minutos da sua atenção.

Brief (formulário compacto)

Você poderá sair da lista quando quiser. Sem spam.