--- id: casos/deduplicacao-de-cadastros area: Dados uso: muito usado esforco: médio grao: 1 linha por entidade resolvida, mais 1 linha por cadastro de origem no mapa --- # Deduplicação e entity resolution Uma linha por pessoa ou empresa, com todos os cadastros de origem ligados a ela e o motivo de cada fusão, sem juntar quem só divide um telefone. ## Resumo executivo **Para quem:** Empresas cujo mesmo cliente aparece em mais de um sistema, ou várias vezes dentro do mesmo CRM. **O que resolve** - Cada cliente é contado uma vez, mesmo com cadastros no CRM, no ERP, no billing e em planilhas. - Pessoas diferentes que dividem telefone ou e-mail param de virar uma só. - Cada fusão diz por qual chave foi feita e pode ser revista. **Por que importa:** Toda métrica por cliente herda o erro da identidade: LTV, churn, inadimplência e cohort ficam errados desde a raiz. Unir demais é tão ruim quanto unir de menos, porque misturar dois clientes leva a dívida de um para o outro e dispara campanha para a pessoa errada. Por isso a regra precisa ser explícita, auditável e ter uma fila de revisão humana para os casos duvidosos. **Perguntas de negócio que responde** - Quantos clientes únicos temos de verdade, somando todos os sistemas? - Quais clientes estão cadastrados mais de uma vez no CRM? - Esse lead novo já é cliente, proprietário ou ex-cliente? - Quanto este cliente já comprou, somando todos os cadastros dele? - Quantos cadastros estão sem CPF, CNPJ, e-mail ou telefone válido? - Quais fusões estão esperando revisão? **O que você precisa** - Os sistemas que guardam cadastro de cliente conectados na Nekt - Pelo menos uma chave forte em parte da base: CPF, CNPJ, e-mail ou o id de um sistema gravado no outro - Um dono para revisar os casos duvidosos **O que você recebe** - Uma tabela de entidades únicas com o melhor valor de cada campo - O mapa de cada cadastro de origem para a entidade, com método e confiança - Uma fila de pares duvidosos para revisão humana - Um agente de IA que encontra o cliente por qualquer documento, e-mail ou telefone ## Detalhado ### O problema O mesmo cliente aparece com nome, telefone e documento diferentes em cada sistema, e várias vezes dentro do mesmo CRM. Numa base real, nenhum cliente da lista do contas a receber casava pelo nome com o contato do CRM. Quem cruza por nome não acha nada, e quem cruza só por telefone ou e-mail junta familiares, colegas e o número da recepção num cliente só. O resultado é LTV, inadimplência e campanha calculados sobre identidades erradas. ### Regras de negócio 1. **Normalize antes de comparar.** CPF e CNPJ só com dígitos, completados com zeros à esquerda até 11 (CPF) ou 14 (CNPJ): documento lido como número perde o zero inicial e não casa. E-mail em minúsculas, sem espaços e validado por formato. Telefone só com dígitos, sem o 55 quando sobram 12 ou 13 dígitos, ficando com 10 ou 11. Nome em maiúsculas, sem acento e sem sufixo societário (ltda, me, epp, eireli, s/a). (Evite: Comparar os campos como vieram: CPF com pontos, telefone com e sem 55, e-mail com maiúsculas.) 2. **Lixo vira nulo, nunca chave.** CPF com todos os dígitos iguais (00000000000, 11111111111), dígito verificador inválido ou em notação científica, telefone vazio, '0' ou '55' e e-mails de preenchimento (naotem@, sememail@) viram nulo. Valide o dígito verificador de CPF e CNPJ. Um placeholder usado como chave junta centenas de pessoas num cliente só. (Evite: Usar o CPF 000.000.000-00 que o ERP grava por padrão como chave de cruzamento.) 3. **Identificador compartilhado não é identidade.** Telefone da recepção, e-mail do financeiro, e-mail do corretor ou do vendedor interno aparecem em muitos cadastros. Mantenha uma lista de bloqueio com os endereços internos e aplique um teto de frequência: telefone ou e-mail presente em mais de 5 cadastros distintos deixa de ser chave. Nome que aparece mais de 20 vezes também não serve para agrupar candidatos. (Evite: Fundir todos os cadastros que têm o e-mail financeiro@ da empresa.) 4. **Casamento em cascata, da chave mais forte para a mais fraca.** 1) Id de um sistema gravado no outro (campo customizado com o id do ERP ou do CRM antigo). 2) CPF ou CNPJ válido. 3) E-mail. 4) Telefone. Colete os matches de todas as regras e fique, para cada cadastro, com a regra de maior prioridade. Grave em cada vínculo qual regra casou. (Evite: Juntar por qualquer chave que bater, sem ordem de confiança.) 5. **Telefone e e-mail sugerem, o nome valida, o documento confirma.** E-mail e telefone iguais servem para achar candidatos e para corroborar. O nome decide: se o primeiro nome for muito diferente, o par não é a mesma pessoa, mesmo com e-mail e telefone idênticos, porque familiares e colegas dividem o contato. Numa base real, telefone sozinho gerava dezenas de vezes mais pares do que nome mais telefone. Só CPF ou CNPJ igual confirma sem olhar o nome. (Evite: Mesmo telefone, mesma pessoa.) 6. **Uma chave só liga quando aponta para uma entidade.** Ao ligar evento, ticket, mensagem ou venda a um cadastro por telefone ou e-mail, use apenas as chaves que apontam para um único cadastro. Chave que aponta para dois ou mais fica sem vínculo e vai para a fila, em vez de escolher um ao acaso. (Evite: Pegar o maior id quando o telefone casa com vários contatos.) 7. **O registro mais completo vence, campo a campo.** Escolha o registro principal pela completude (quantos de CPF, e-mail, telefone, nome e data de nascimento estão preenchidos), desempatando pela data de modificação mais recente e depois pelo id. Campos vazios no principal são completados pelos secundários. O desempate tem de ser determinístico, senão cada execução escolhe um vencedor diferente. (Evite: Ficar com qualquer linha do grupo.) 8. **Papel é vínculo, não identidade.** A mesma pessoa pode ser lead, cliente, proprietário, locatário, fiador, investidor ou parceiro. Crie uma entidade por pessoa e uma linha de vínculo por papel, em vez de um cadastro por papel. Quando lead e cliente coexistem, o cliente prevalece. (Evite: Um cadastro de proprietário e outro de comprador para a mesma pessoa.) 9. **Empresa e grupo econômico são grãos diferentes.** Para PJ, a entidade é o CNPJ completo, de 14 dígitos. A raiz do CNPJ (8 primeiros dígitos) junta matriz e filiais: guarde como coluna de grupo, nunca como chave de fusão. Documento de 11 dígitos é PF; marcadores no nome (ltda, me, s/a) ajudam a separar PF de PJ quando o documento falta. (Evite: Fundir matriz e filiais pela raiz do CNPJ.) 10. **Fusões vivem num mapa, e as duvidosas vão para revisão.** Mantenha um mapa de cada id de origem para a entidade, atualizado por upsert, com método, confiança e data. Pares de baixa confiança (nome mais telefone, sem documento) vão para uma fila de revisão humana, e as decisões manuais ficam numa tabela com quem decidiu e por quê. Fusões já feitas na fonte, como hs_merged_object_ids do HubSpot, entram no mapa para que ids antigos continuem encontrando a entidade. (Evite: Refazer o agrupamento do zero a cada execução e perder as decisões manuais.) ### O que cada chave pode fazer Da mais forte para a mais fraca. Grave em cada vínculo qual delas foi usada. - **Decisão manual registrada** → Vence todas (`tabela datada, com quem decidiu e o motivo`) - **Id de um sistema gravado no outro** → Confirma (`campo customizado com o id de origem`) - **CPF ou CNPJ válido** → Confirma (`só dígitos, lpad 11 ou 14, dígito verificador ok`) - **E-mail normalizado** → Sugere, o nome valida (`lower, trim, formato válido, fora da lista de bloqueio`) - **Telefone normalizado** → Sugere, o nome valida (`só dígitos, sem 55, 10 ou 11 dígitos`) - **Nome mais data de nascimento, mãe ou CEP** → Candidato para modelo probabilístico - **Nome sozinho** → Nunca confirma - **Raiz do CNPJ** → Grupo econômico, não entidade (`8 primeiros dígitos`) ### Definições | Métrica | Definição | |---|---| | Entidade (golden record) | pessoa (CPF) ou empresa (CNPJ completo) resolvida, 1 linha, com id próprio que não muda quando um cadastro de origem muda | | Cadastro de origem | cada linha de cliente, contato, lead ou pessoa num sistema, identificada por sistema + id | | Método do vínculo | regra que ligou o cadastro à entidade: id gravado, documento, e-mail, telefone, modelo ou decisão manual | | Taxa de duplicação | (cadastros de origem - entidades) / cadastros de origem, por sistema e no total, na data da execução | | Cobertura de chave forte | entidades com CPF ou CNPJ válido ou com id gravado em outro sistema / total de entidades | | Chave ambígua | e-mail ou telefone normalizado presente em 2 ou mais entidades distintas; não liga eventos nem vendas | | Fila de revisão | pares de cadastros com sinal fraco (nome mais telefone, sem documento em comum) aguardando decisão humana | | Grupo econômico | entidades PJ com a mesma raiz de CNPJ (8 dígitos); para PF, o grupo é a própria entidade | ### Armadilhas - **Contatos contaminados.** Uma planilha do ERP guardava um único registro de empresa para várias pessoas. A primeira rodada de criação de contatos no CRM gravou telefone, e-mail e CPF de uma pessoa em outra, e mais de uma centena de contatos teve de ser corrigida. Como evitar: Separe pessoa de empresa antes de criar ou fundir, e nunca herde contato de um registro de empresa. - **Carga dobrada.** A carga de origem gravava cada cadastro duas vezes, com conteúdo idêntico. Toda contagem feita direto na tabela bruta saía em dobro. Como evitar: Remova duplicatas exatas na entrada, antes de qualquer match, e compare linhas com ids distintos. - **Excluídos ainda casando.** Tabelas do ERP mantinham linhas marcadas como excluídas (deleted, ou D_E_L_E_T_ no TOTVS). Elas casavam com cadastros vivos e duplicavam clientes e títulos. Como evitar: Filtre registros excluídos antes de casar. - **Uma pessoa em quatro ids.** Sem CPF nem e-mail em comum, o mesmo cliente ficou espalhado em quatro cadastros, um como cliente num sistema e três como leads em outro CRM, todos com o mesmo telefone. Como evitar: Use nome mais telefone como sinal para revisão humana, não como fusão automática. - **Correntes transitivas.** A casava com B pelo telefone, B casava com C pelo e-mail, e A e C, que não tinham nada em comum, viravam a mesma pessoa. Como evitar: No modelo probabilístico, gere pares com limite permissivo e forme os grupos com limite estrito (por exemplo, 0,85 e 0,95). - **Vencedor que muda a cada execução.** Dois cadastros empatados no critério de escolha eram resolvidos sem desempate, e o registro principal mudava de uma execução para outra. Como evitar: Desempate fixo por data de modificação e, por último, pelo id. Validado em dados reais: No HubSpot da própria Nekt, nenhum e-mail se repete entre contatos, porque o HubSpot já impede, mas cerca de 1 em cada 15 telefones aparece em mais de um contato. Em cerca de 3 de cada 4 desses grupos o primeiro nome é o mesmo, sinal de duplicata com e-mail diferente. No restante os nomes diferem, e fundir só pelo telefone juntaria pessoas diferentes. ### Teste de aceitação - [ ] Cada cadastro de origem (sistema + id) aparece em exatamente uma entidade do mapa. - [ ] Nenhuma entidade tem dois CPFs ou dois CNPJs completos distintos. - [ ] Nenhuma fusão usou como chave um placeholder (CPF com dígitos iguais, e-mail de preenchimento, telefone curto) ou uma chave acima do teto de frequência. - [ ] A soma de compras ou receita por entidade é igual à soma por cadastro de origem, sem diferença. - [ ] Rodar o processo duas vezes sobre os mesmos dados gera as mesmas entidades e os mesmos registros principais. ### Context document ```text Identidade de pessoas e empresas - Cliente = entidade da tabela de identidade (1 linha por pessoa ou empresa). Conte e some por ela, nunca pelo cadastro de origem. - Para achar um cliente, normalize a busca: CPF e CNPJ só dígitos (11 e 14 posições), e-mail em minúsculas, telefone só dígitos e sem 55. - Ordem de confiança dos vínculos: decisão manual > id gravado em outro sistema > CPF ou CNPJ > e-mail > telefone. Nome sozinho nunca confirma. - Telefone ou e-mail compartilhado por várias entidades é chave ambígua: não ligue evento nem venda por ele. - PJ: a entidade é o CNPJ completo. A raiz do CNPJ é o grupo econômico, em coluna separada. - Uma pessoa pode ter vários papéis (lead, cliente, proprietário, locatário, fiador, parceiro). Quando lead e cliente coexistem, vale cliente. - Contas internas, de teste e e-mails da própria empresa não são clientes. - Se o vínculo de uma resposta foi por telefone ou e-mail, diga isso. Se o cadastro não está no mapa, diga que não foi resolvido em vez de adivinhar. Exceções por cliente: - : e-mails e telefones internos na lista de bloqueio: . - : campo do CRM guarda o id do ERP e é a chave mais forte. - : teto de frequência de cadastros por telefone ou e-mail. ``` ### Variações - **Probabilístico:** Sem documento, um modelo Fellegi-Sunter (por exemplo, com Splink) agrupa por chaves limpas e respeita uma regra negativa: nenhum grupo pode ter dois CPFs distintos. - **Imóveis e produtos:** A mesma lógica acha imóveis repetidos entre agências pelo endereço normalizado: número sem zeros à esquerda e apartamento extraído do complemento. - **Enriquecer pela Receita:** Para PJ, a base pública de CNPJ confirma o documento e completa razão social, CNAE e situação cadastral.