Evitar duplicidade em integrações passa por definir uma chave de identificação única (telefone, e-mail, código de pedido), verificar se um registro já existe antes de criar um novo, e desenhar a integração para ser idempotente, ou seja, executar a mesma operação duas vezes sem gerar dois resultados diferentes.
Antes de criar qualquer registro, a integração precisa de um critério confiável para reconhecer "isso já existe": um telefone, um e-mail, um código de pedido, algo que não mude entre uma execução e outra.
Toda integração deveria checar se já existe um registro correspondente antes de criar um novo, atualizando o existente em vez de duplicar.
Uma operação idempotente pode ser executada mais de uma vez sem mudar o resultado além do esperado, o que protege contra reenvios acidentais de um mesmo evento (comuns quando uma conexão falha e o sistema de origem tenta de novo).
Repetir a mesma requisição deve produzir o mesmo efeito observável. Para isso, armazene um identificador do evento ou componha uma chave estável com origem, objeto e operação. Faça a verificação e a gravação na mesma transação quando possível. Também defina o que é duplicidade: dois contatos com o mesmo e-mail podem exigir revisão, enquanto o mesmo pagamento jamais deve ser lançado duas vezes.
A primeira conversa deve reunir donos dos sistemas de origem e destino, arquitetura, desenvolvimento, segurança e responsáveis pela operação. O objetivo não é escolher uma ferramenta, mas esclarecer qual sistema é a fonte de verdade de cada campo e como conflitos serão resolvidos. Use a resposta central deste guia como hipótese e confronte-a com o processo atual: quem inicia a tarefa, quais dados entram, onde existe julgamento, qual saída é útil e quem absorve uma exceção. O recorte inicial precisa caber em uma frase e ter começo e fim observáveis. Em seguida, transforme o problema em um contrato de dados versionado, exemplos de payload, critérios de aceite e cenários de falha testados. Se a equipe não consegue descrever o resultado esperado sem mencionar marca, plataforma ou modelo, ainda há descoberta a fazer. Um bom enquadramento também explicita o que ficará fora da primeira versão. Essa fronteira reduz dependências, protege o prazo e impede que o piloto seja avaliado por expectativas diferentes em cada área.
Escolha poucos indicadores que conectem operação e resultado. Para este tema, um conjunto inicial pode acompanhar eventos processados, erros por causa, tempo de sincronização, duplicidades evitadas e divergências na reconciliação. Registre a linha de base antes da mudança e defina frequência, fonte e responsável por cada número. Média isolada costuma esconder filas, segmentos e exceções; quando houver volume, observe distribuição e casos extremos. Combine um indicador de velocidade, um de qualidade, um de custo e um de risco. Os exemplos do artigo ajudam a escolher a unidade: Um webhook que avisa duas vezes sobre o mesmo pedido, por falha de rede, não deveria criar dois registros se a integração verificar o código do pedido antes de agir. A métrica só é útil se levar a uma decisão. Documente antecipadamente qual variação exige investigação, qual permite ampliar o uso e qual interrompe a operação.
Transforme o processo de implantação em entregas verificáveis. Primeiro, definir a chave de identificação única para o tipo de dado integrado. O resultado dessa etapa deve ser revisado por quem executa o trabalho, não apenas pela equipe técnica. Depois, implementar verificação antes de criar um novo registro, usando uma amostra que contenha situações comuns e exceções conhecidas. Na sequência, testar o comportamento da integração recebendo o mesmo evento mais de uma vez. Se houver mais etapas, organize-as por dependência: segurança, homologação, observabilidade e liberação gradual. Libere primeiro para um grupo ou volume limitado, mantenha um caminho manual e registre cada correção relevante como caso de teste. A implantação termina apenas quando existe responsável, alerta, procedimento de recuperação e uma revisão marcada; colocar o fluxo no ar é o início da operação, não o encerramento do projeto.
O caminho feliz raramente concentra o custo de produção. Timeout, retry, ordem, autenticação, mudança de contrato e reprocessamento precisam entrar no desenho inicial. Neste artigo, os limites que merecem atenção incluem Definir uma boa chave de identificação nem sempre é trivial quando os sistemas de origem têm dados inconsistentes (telefones em formatos diferentes, por exemplo). Converta cada limite em um controle observável: permissão mínima, confirmação, amostragem, alerta, teto de custo, versionamento ou transferência humana. Os erros mais prováveis são Não verificar duplicidade antes de criar um registro novo; Usar uma chave de identificação pouco confiável, como nome da pessoa. Em vez de tratá-los como lembrete genérico, associe cada erro a um responsável e a uma evidência de prevenção. O critério de interrupção também precisa estar escrito. Não se aplica: prevenção de duplicidade é recomendada em praticamente qualquer integração que crie ou atualize registros. Parar, reduzir autonomia ou voltar ao fluxo anterior não representa fracasso; é uma resposta de governança quando o resultado real deixa de sustentar a hipótese inicial.
Duplicidade é um dos problemas mais comuns e mais evitáveis em integrações reais; quase sempre a causa é a ausência de uma chave de identificação bem definida desde o início do projeto.
Não se aplica: prevenção de duplicidade é recomendada em praticamente qualquer integração que crie ou atualize registros.
Normalizar o formato (removendo espaços, códigos de país inconsistentes, maiúsculas/minúsculas) antes de comparar é essencial para a verificação funcionar.
Ajuda bastante, mas ainda depende de uma chave de identificação bem definida por trás da lógica.