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

> O tempo esgotado não diz se o envio funcionou. Veja por que a integração duplica pedidos e o identificador único que torna o reenvio seguro.

- Autor: Marlon Trettin
- Publicado: 2026-11-10 · Atualizado: 2026-11-10
- Idioma: pt-BR
- Canonical: https://yowpi.com/blog/integracao-que-repete-o-pedido-que-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.

## TL;DR

- Quando a resposta não chega, quem enviou não sabe se o pedido foi gravado. Repetir o envio é a reação natural e é o que duplica o registro.
- A prática documentada é o identificador de operação gerado por quem envia: o destino reconhece o repetido e devolve o resultado do primeiro envio.
- Isso é decisão de desenho, tomada antes da integração entrar no ar. Corrigir depois significa limpar duplicidade à mão, registro a registro.
- Para a diretoria, a pergunta útil é quantos registros duplicados a operação encontra por mês e quem os encontra.

## 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](/cases/reatop), 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](/blog/automacao-parou-quando-voce-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](/blog/5-falhas-que-comprometem-integracoes-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](/contato).
