Integração que repete: por que o pedido entra duas vezes

A integração cria o mesmo lançamento duas vezes porque um tempo esgotado não diz se o primeiro envio funcionou. O sistema de origem tenta de novo, e o de destino não sabe que é o mesmo pedido. A saída é dar a cada operação um identificador único e decidir, no desenho, o que acontece no reenvio.
Por que a integração duplica o pedido?
Porque a rede não entrega certeza. Quando o sistema de vendas manda um pedido ao ERP e a resposta não volta, existem dois mundos possíveis: o pedido não chegou, ou chegou e a confirmação se perdeu. Do lado de quem enviou, os dois são idênticos.
O artigo de Malcolm Featonby na Amazon Builders' Library descreve exatamente esse impasse. Quando uma chamada para criar um recurso estoura o tempo, repetir pode gerar dois recursos onde havia a intenção de um, com consequências que o autor chama de graves. Esperar não resolve, porque a dúvida continua. Desistir também não, porque às vezes o pedido nunca chegou.
Repetir é a escolha sensata na maior parte dos casos, e por isso integrações repetem sozinhas. O problema não está na tentativa. Está no destino, que trata a segunda chegada como um pedido novo.
O que a documentação técnica propõe?
Um identificador gerado por quem envia, único por operação. A Amazon chama de client request identifier: pedidos do mesmo remetente com o mesmo identificador são tratados como a mesma operação. Na segunda chegada, o destino não cria nada. Devolve uma resposta equivalente à da primeira, para que o remetente siga em frente como se tivesse recebido a confirmação na primeira vez.
A documentação da Stripe descreve o mesmo mecanismo para a sua API de pagamentos. Com a chave de idempotência, o cliente pode repetir a chamada depois de uma falha de conexão sem criar um segundo objeto. A Stripe guarda o código de status e o corpo da primeira resposta e os devolve nas repetições. Se a mesma chave chega com parâmetros diferentes, a API recusa, para evitar uso errado.
Há também uma peça que o texto da Amazon deixa explícita: registrar o identificador e executar a operação precisam acontecer juntos, ou nada acontece. Se o identificador for gravado e a operação falhar, o reenvio será ignorado e o pedido nunca existirá.
O assunto está em processo de padronização. Um rascunho do grupo de trabalho HTTPAPI da IETF, o draft-ietf-httpapi-idempotency-key-header (revisão 08, de 22 de outubro de 2026), propõe um cabeçalho padrão para esse identificador. Até essa revisão, não é norma publicada, e vale tratá-lo como sinal de que a prática é comum o bastante para merecer padrão.
Quais decisões o desenho precisa tomar?
Três, e nenhuma delas é de ferramenta.
A primeira é onde nasce o identificador. Ele precisa ser criado uma vez, no sistema que origina a operação, e reutilizado em cada tentativa. Se cada tentativa gera um identificador novo, o destino nunca reconhece o repetido.
A segunda é por quanto tempo o destino lembra. A Stripe informa que, na versão 1 da API, as chaves podem ser removidas depois de pelo menos 24 horas. Esse número é da Stripe, não uma regra. O que vale para a sua operação é a pergunta: qual a maior demora plausível entre a primeira tentativa e a última? Uma fila que fica parada no fim de semana precisa de memória mais longa que um formulário.
A terceira é o que o destino responde ao repetido. A resposta certa não é "esse pedido já existe", que o remetente leria como falha. É o resultado do primeiro envio, igual ao que ele teria recebido.
Como isso aparece em uma PME?
O exemplo abaixo é uma hipótese para ilustrar, não um caso medido. Uma distribuidora tem um sistema de vendas e um ERP ligados por uma integração. No fim do mês o ERP fica lento e algumas gravações demoram mais que o limite de espera. O sistema de vendas não recebe confirmação e reenvia.
Em parte dos casos, o primeiro envio já tinha sido gravado. O ERP agora tem dois pedidos iguais. O estoque separa duas vezes e o financeiro vê dois lançamentos. O cliente pode receber duas cobranças ou duas entregas. Ninguém vê o erro na hora, porque cada sistema, isoladamente, funcionou. Quem descobre é a pessoa que concilia no fim da semana, comparando linha a linha.
Com o identificador, o segundo envio chega ao ERP, que reconhece a operação e devolve o resultado do primeiro. Nada é criado. O sistema de vendas segue com a confirmação que esperava. O custo está no desenho inicial, e o ganho aparece como ausência de trabalho: a conciliação deixa de caçar duplicidade.
Em operações que sincronizam depois, como a Reatop, que registra resíduos hospitalares em campo, com uso offline e sincronização posterior, o reenvio faz parte da rotina. Ali a pergunta sobre o repetido vale desde o primeiro dia do projeto.
Como a diretoria enxerga o resultado?
Pelo que a operação deixa de fazer. Não encontrei indicador público confiável para a frequência de duplicidade em integrações de PME, e este artigo não vai inventar um. O número que importa é o seu, e ele sai de uma contagem simples na própria operação.
Conte, por mês, quantos registros duplicados a operação encontra e corrige, quanto tempo cada correção toma e quem a faz. Esse é o custo atual. Depois da mudança, o mesmo levantamento mostra se o desenho funciona. Se a contagem não cai, o identificador não está sendo reutilizado nas tentativas, e isso é achado útil.
Esse raciocínio é parente do que aparece em sua automação parou, quando você vai descobrir: a falha que não faz barulho costuma ser a que mais demora a aparecer. E a lista de cinco falhas que comprometem integrações de sistemas internos ajuda a ver onde mais a ligação entre sistemas costuma ceder.
Perguntas frequentes
Como eu meço o resultado, se o que muda é algo que deixa de acontecer?
Contando a duplicidade antes e depois. Registros duplicados encontrados por mês, tempo gasto para corrigir cada um e quem corrige. Se a conta mostra horas de conciliação por semana, esse é o custo que o projeto precisa eliminar, e a comparação fica na sua própria operação.
Isso vai exigir muito tempo do meu time para implementar?
O esforço mais caro é de desenho: decidir onde nasce o identificador, por quanto tempo o destino lembra e o que responde ao repetido. É uma conversa entre quem opera e quem constrói, e o tempo depende de quantas integrações existem. O custo cresce quando a decisão fica para depois, porque aí a correção passa por registros que já existem.
E se o sistema do outro lado não aceitar identificador? Isso não deixa o gargalo intacto?
Depende do sistema. Quando o destino não reconhece o identificador, a verificação pode ser feita na ponta de origem: consultar se o pedido já existe antes de reenviar. Fica mais lento e mais frágil, mas é uma barreira. Saber que o destino não oferece essa garantia já muda a decisão de compra e de integração.
O próximo passo
Se hoje ninguém sabe dizer quantas das suas integrações repetem envios sozinhas e o que cada uma faz com o repetido, o Diagnóstico de Arquitetura Operacional é uma conversa de 30 minutos para mapear isso. Fale com um arquiteto.
Cases relacionados

Reconheceu a sua operação neste artigo?
Agende o Diagnóstico de Arquitetura Operacional: 30 minutos para mapear onde está o gargalo da sua operação. Sem proposta na primeira conversa.
Agendar diagnóstico