Identificadores em integrações: como decidir que ID partilhar entre sistemas sem criar duplicados

Ligar um CRM, um ERP, um comércio eletrónico e aplicações próprias levanta uma questão aparentemente simples: como sabemos que dois registos representam a mesma entidade? A resposta não pode basear-se, por defeito, num nome, num endereço de e-mail ou numa referência visível. Estes valores mudam, podem repetir-se e habitualmente seguem regras diferentes em cada sistema.

Uma má decisão sobre identificadores provoca duplicados, atualizações aplicadas ao registo errado, encomendas sem cliente associado e reconciliações manuais que se tornam permanentes. Uma decisão sólida não consiste em encontrar um identificador universal mágico, mas em definir que sistema reconhece que entidade, com que chave, durante quanto tempo e segundo que regras de alteração.

Este enquadramento ajuda a escolher entre IDs internos, referências de negócio, IDs externos e tabelas de correspondência sem expor informação desnecessária nem acoplar sistemas de forma frágil.

Porque os campos visíveis não resolvem a identidade

O nome de uma empresa pode ser escrito de várias formas, mudar após uma fusão ou ser partilhado por organizações diferentes. O nome de uma pessoa apresenta ainda mais colisões. O endereço de e-mail pode ser alterado, reutilizado, pertencer a uma conta partilhada ou não existir em determinados fluxos. Até uma referência comercial pode ser única apenas dentro de uma filial, de um canal ou de um período.

Estes campos continuam a ser úteis para pesquisar, apresentar e propor correspondências, mas raramente devem ser a chave técnica de uma integração. A distinção importante é a seguinte:

• Identidade: o registo concreto que um sistema considera uma entidade.
• Atributos: dados que descrevem essa entidade, como nome, e-mail, telefone ou morada.
• Referência de negócio: um código com significado operacional, como um número de encomenda ou um código de cliente.

Confundir estas camadas é uma origem frequente de erros. Por exemplo, uma morada não identifica necessariamente um cliente: a mesma pessoa pode ter várias moradas e várias pessoas podem partilhar uma. Da mesma forma, uma encomenda identifica uma transação, e não o comprador de forma permanente.

Tipos de identificador e para que serve cada um

Antes de conceber mensagens ou endpoints, convém classificar as chaves disponíveis. Cada tipo tem vantagens e limites.

• ID interno: chave gerada e controlada por um sistema, normalmente estável e sem significado de negócio. É a melhor opção para operar dentro do seu próprio domínio.
• Referência de negócio: código legível ou operacional, como uma referência de encomenda. Facilita o suporte e a reconciliação, mas pode mudar de formato, reiniciar por série ou ser reutilizado.
• ID externo: identificador que um sistema recetor guarda para recordar o registo de um sistema emissor. É útil quando existe uma relação clara de proveniência.
• Identificador composto: combinação de valores, por exemplo origem + tipo de entidade + id. É indispensável quando um ID só é único dentro de um sistema.
• Identificador temporário: chave de correlação para um processo ainda não consolidado. Deve expirar e não se transformar acidentalmente numa identidade permanente.

Uma regra prática é manter o ID interno de cada aplicação como autoridade local. Quando os dados são trocados, o identificador mínimo seguro costuma ser um valor com um espaço de nomes explícito. Por exemplo:

{
  "entity_type": "customer",
  "source_system": "ecommerce",
  "source_id": "C-48291"
}

O valor C-48291, por si só, não é necessariamente único à escala global. O contexto de origem impede que outro sistema interprete uma correspondência textual como uma identidade partilhada.

Perguntas a responder antes de partilhar um ID

Não escolha uma chave pela comodidade de implementação. Decida primeiro o modelo de propriedade e o ciclo de vida. Estas perguntas revelam se um identificador é adequado para circular entre sistemas:

1. Que sistema cria a entidade e qual é a fonte de verdade para cada atributo?
2. O valor é único em toda a organização ou apenas dentro de uma aplicação, país, canal ou tipo de entidade?
3. Pode mudar? Se mudar, o valor anterior é mantido e o evento é publicado?
4. Pode ser reutilizado após uma eliminação, um cancelamento ou um período de retenção?
5. Contém dados pessoais, informação comercial sensível ou padrões fáceis de adivinhar?
6. Um registo pode ser fundido com outro ou dividido em vários?
7. Que comportamento deve ter o recetor quando não encontra uma correspondência?

Um ID partilhado deve ser estável, único no seu contexto, não reutilizável e suficientemente opaco para a utilização prevista. Se uma referência de negócio não cumprir estas condições, utilize-a como atributo verificável, e não como chave de atualização.

Também é necessário separar a identidade técnica da autorização. Conhecer um identificador não deve permitir ler ou alterar uma entidade. As APIs devem validar que quem faz a chamada tem permissão para operar sobre esse recurso e evitar IDs previsíveis como único mecanismo de proteção.

Quando propagar o ID de origem e quando usar uma tabela de correspondências

Propagar o ID de origem é razoável quando uma entidade nasce num sistema claramente autoritativo e os restantes sistemas apenas precisam de a reconhecer. Por exemplo, o comércio eletrónico pode criar uma encomenda e o ERP pode armazenar o identificador da encomenda do comércio eletrónico como referência externa. Este padrão reduz a ambiguidade e permite rastrear a proveniência.

No entanto, nem todos os domínios têm uma única autoridade. Um cliente pode surgir através de vendas, comércio eletrónico, suporte ou importações históricas. Nestes casos, impor o ID de um dos sistemas como chave universal cria dependência e pode transformar uma migração futura num projeto de elevado risco.

Uma tabela de correspondências é preferível quando existem vários sistemas mestres, consolidação gradual, fusões de registos ou regras de identidade complexas. Deve guardar, pelo menos, o tipo de entidade, o sistema, o ID local, o ID canónico, caso exista, o estado da ligação, a data de criação e a evidência ou regra que justificou a relação.

Evite uma tabela que apenas relacione duas colunas sem contexto. O mesmo valor pode existir para tipos distintos, e uma ligação pode ser confirmada, provisória, rejeitada ou substituída após uma fusão. Trate esse mapeamento como um dado operacional com auditoria, e não como uma configuração invisível no código.

Criações, duplicados e fusões: conceber para os casos incómodos

Quando chega uma criação sem identificador comum, o recetor não deve assumir que se trata de uma nova entidade nem que uma correspondência por e-mail é definitiva. Deve aplicar uma política explícita:

• Criar um novo registo e deixá-lo sem ligação quando não existe evidência suficiente.
• Propor uma correspondência quando vários atributos consistentes ultrapassam um limiar definido pelo negócio.
• Exigir revisão humana para unir registos com consequências financeiras, contratuais ou de apoio ao cliente.
• Registar a decisão, a regra aplicada e os IDs envolvidos.

A deduplicação automática é especialmente arriscada quando o custo de uma união incorreta é superior ao de manter dois registos pendentes. Fundir por engano dois clientes pode misturar faturas, consentimentos ou comunicações. Em contrapartida, um duplicado detetado pode ser resolvido através de uma fila de revisão.

As fusões requerem uma semântica própria. Defina um registo sobrevivente, mantenha os IDs históricos como aliases ou redirecionamentos e publique a alteração para que os sistemas consumidores atualizem as respetivas ligações. Não elimine imediatamente o ID absorvido: processos assíncronos, novas tentativas e registos históricos podem continuar a referir-se a ele.

Alterações, eliminações e reativações sem quebrar a rastreabilidade

Idealmente, um identificador técnico não muda. Se uma referência de negócio tiver de mudar, o evento deve comunicar tanto o valor anterior como o novo e explicar a causa. Nunca interprete o silêncio como uma eliminação: podem existir atrasos, falhas de entrega ou filtros de sincronização.

Para eliminações, utilize estados explícitos como ativo, inativo, cancelado, eliminado ou fundido, consoante o domínio. A eliminação física pode ser necessária por requisitos de privacidade, mas deve ser concebida em conjunto com a rastreabilidade: poderá ser possível manter um marcador técnico não identificável ou uma evidência de que uma ligação já não deve ser recriada.

Não reutilize referências que já tenham sido emitidas, mesmo que o registo esteja inativo. A reutilização transforma dados históricos corretos em ambiguidade futura. Se uma reativação representar a mesma entidade, mantenha o ID; se representar uma nova entidade, atribua um novo e documente a relação apenas se isso acrescentar valor operacional.

Conceção de APIs, mensagens e controlos operacionais

Um contrato de integração deve transportar contexto suficiente, mas não mais dados do que os necessários. Inclua o tipo de entidade, o sistema de origem, o ID de origem, a operação, a marca temporal, a versão ou sequência quando aplicável e um identificador de evento para gerir novas tentativas. A idempotência evita criar várias vezes a mesma entidade quando uma entrega se repete.

Para atualizações, dê prioridade a uma operação que indique claramente a chave utilizada. Se for permitida a pesquisa por referência de negócio, trate um resultado múltiplo como um erro controlado, e não como um convite para escolher o primeiro registo.

Os controlos operacionais devem transformar os problemas de identidade em sinais visíveis:

• alertas para correspondências ambíguas e mensagens sem correspondência;
• filas para ligações pendentes e revisões de fusão;
• métricas de duplicados criados, ligações quebradas e erros recorrentes por sistema;
• reconciliações periódicas entre contagens, estados e ligações esperadas;
• logs que incluam IDs técnicos e de correlação, sem expor atributos pessoais desnecessários.

Antes de desenvolver, documente para cada entidade o seu sistema autoritativo, ID local, chaves externas aceites, regras de unicidade, política de alterações, estados de eliminação e estratégia de deduplicação. Esta decisão reduz o acoplamento hoje e torna uma futura migração, auditoria ou incorporação de um novo canal mais fácil de gerir.