---
id: financeiros/base-unica-cpf-cnpj
industria: Serviços financeiros
uso: muito usado
esforco: médio
grao: Pessoa ou empresa pelo documento normalizado; pessoa x contrato x objeto (placa, chassi, conta, apólice) para o detalhe
---

# Base única por CPF e CNPJ

Cada pessoa ou empresa aparece uma vez só, com o que contratou em cada sistema, se está ativa hoje e quem era o responsável comercial na data de cada fato.

## Resumo executivo

**Para quem:** Cooperativas e associações de proteção, corretoras de seguro, escritórios de investimento e fintechs com o mesmo cliente em vários sistemas.

**O que resolve**

- A base ativa tem um número só, igual para diretoria, comercial e financeiro.
- Cada cliente aparece uma vez, com tudo o que contratou em todos os sistemas e a origem de cada contrato.
- Lead que já era cliente para de contar como venda nova.

**Por que importa:** Em seguro, proteção e investimento o cliente nasce no CRM, contrata no core, ganha apólice em outro sistema e é atendido por um assessor que muda com o tempo. Sem uma chave limpa e uma regra escrita de cliente ativo, cada área conta a base de um jeito e o agente de IA responde com o número de quem perguntou por último. É a base de cobrança, comissão, retenção e de qualquer lista enviada a parceiro.

**Perguntas de negócio que responde**

- Quantos clientes ativos temos hoje, por regional e por produto?
- Quais contratos foram ativados este mês?
- Este CPF já é nosso cliente em algum sistema?
- Quantos leads do mês viraram contrato e quantos já eram clientes antes?
- Quem era o assessor responsável por esta conta quando a captação aconteceu?
- Quais clientes têm mais de um veículo ou mais de uma apólice ativa?

**O que você precisa**

- Os sistemas onde o cliente vive conectados na Nekt: core, apólices, CRM e relatórios do parceiro
- A definição escrita de cliente ativo, por sistema e por produto
- Um histórico de responsável por conta, se a pergunta for sobre o passado

**O que você recebe**

- Uma tabela por pessoa com documento normalizado, origem e status ativo
- O detalhe pessoa x contrato x objeto, com data de ativação
- Um vínculo lead para contrato que diz por qual chave casou
- Um agente de IA que conta a base com a regra de ativo já aplicada

## Detalhado

### O problema

O mesmo cooperado está no sistema de proteção, no de apólices, num pipeline do CRM e numa planilha, e em cada um o documento foi digitado de um jeito: com pontuação, sem zero à esquerda, como número com ".0" no fim. Somar as bases conta a mesma pessoa várias vezes. Cada área usa uma definição própria de ativo, e o lead que já era cliente vira conversão no funil.

### Regras de negócio

1. **Documento normalizado é a chave.** Remova tudo que não é dígito. CPF tem 11 dígitos e CNPJ 14: complete com zeros à esquerda quando a fonte leu o campo como número. Se vier com mais de 14 dígitos (prefixo de sistema), fique com os 14 últimos. Tire o ".0" de campos que passaram por float antes de remover não-dígitos, senão 8539905.0 vira 85399050. Guarde o documento original ao lado. (Evite: Comparar o documento como veio, com pontuação, ou convertido para número.)
2. **Lixo vira nulo, nunca chave.** Documento com tamanho diferente de 11 ou 14, ou com todos os dígitos iguais (000..., 111...), fica nulo. Telefone: só dígitos, corte o 55 apenas quando tiver 12 ou 13 dígitos, aceite 10 ou 11, o resto é nulo. Placa: maiúscula sem traço, válida no padrão antigo e no Mercosul (3 letras, 1 dígito, 1 letra ou dígito, 2 dígitos). Chassi: pelo menos 8 caracteres e nunca só zeros. (Evite: Ligar cadastros por um CPF 000.000.000-00 ou por um telefone sem DDD.)
3. **Ativo é uma regra escrita, por sistema.** Declare o que conta como ativo em cada fonte: no core, contrato com status ATIVO; no sistema de apólices, apólice active; no produto que só existe no CRM, o negócio na etapa Ativo daquele pipeline. Depois aplique as exclusões combinadas: quem está na lista de cancelados e, se o negócio decidir, quem está inadimplente. Escreva a decisão sobre inadimplente, porque ela muda a contagem. (Evite: Contar como ativo qualquer contrato existente, ou usar a regra de um sistema para os outros.)
4. **Uma linha por fonte, com origem.** Empilhe as fontes num formato comum (nome, documento, objeto, contrato, data de ativação) com as colunas fonte e id na origem. Conte contratos por fonte + id na origem, porque o detalhe pode ter uma linha por produto. Só depois consolide por documento. (Evite: Juntar as bases por nome e perder de onde veio cada contrato.)
5. **Ativação é o primeiro pagamento confirmado.** A data de ativação de um contrato é a menor data de pagamento entre as faturas pagas dele. Na apólice, a data de início de vigência. Data de criação do contrato ou da proposta não é ativação: há contratos criados que nunca pagaram. (Evite: Usar a data de cadastro do contrato como entrada do cliente.)
6. **O objeto é parte do grão.** Em proteção veicular e seguro, uma pessoa tem vários veículos, implementos ou apólices; em investimento, várias contas em instituições diferentes. O detalhe é pessoa x contrato x objeto, e o objeto pode ser veículo ou implemento, nunca os dois. Conte pessoas pelo documento distinto e objetos pela chave do objeto. (Evite: Contar clientes pelo número de linhas da base unificada.)
7. **Cliente prevalece sobre lead.** Na base de pessoas e leads, o lead só entra como tipo Lead quando não há cliente ativo ligado a ele. Se os dois existem, fica o cliente. Pessoa sem conta vinculada continua na base, com a conta nula. (Evite: Somar clientes e leads e mostrar a mesma pessoa duas vezes.)
8. **Lead para contrato em cascata e com data.** Case o lead com contratos pela chave mais forte primeiro: documento, depois placa ou chassi, depois telefone, depois o contato do CRM. Guarde por qual chave casou. Compare a data de registro do contrato com a criação do lead: contrato anterior ao lead é cliente que voltou, não conversão. (Evite: Marcar como convertido todo lead que casa com algum contrato, de qualquer data.)
9. **Responsável é o vigente na data.** Assessor, consultor ou corretor muda com o tempo. Para captação, venda ou comissão, junte com o histórico da carteira onde início da vigência <= data do fato e (fim nulo ou fim > data do fato). O responsável atual só vale para listas de hoje. (Evite: Atribuir captações antigas ao assessor de hoje.)
10. **Excluídos e versões antigas saem antes.** No core, filtre registros com deleted verdadeiro em pessoa, contrato, regional e consultor. No CRM, fique com a última versão de cada id (última data de modificação e, no empate, a sincronização mais recente). Em dados de Open Finance, confira se o evento traz o id do usuário da plataforma em vez do id do cliente e traduza antes de juntar. (Evite: Juntar tabelas do core sem filtrar excluídos, ou usar a primeira versão do negócio no CRM.)

### Chaves de cruzamento e como normalizar

Da mais forte para a mais fraca. Chave inválida vira nulo e não liga cadastros.

- **CPF** → Pessoa física (`só dígitos, 11 posições, sem dígitos todos iguais`)
- **CNPJ** → Empresa (`só dígitos, 14 posições (14 últimos se vier maior)`)
- **Contrato, apólice, número da conta** → Vínculo do produto (`texto sem ".0", só dígitos quando numérico`)
- **Placa** → Veículo segurado (`maiúscula, sem traço, ^[A-Z]{3}[0-9][A-Z0-9][0-9]{2}$`)
- **Chassi** → Veículo ou implemento (`maiúscula alfanumérica, 8+ caracteres, não só zeros`)
- **Telefone** → Sinal fraco, nunca sozinho (`só dígitos, sem 55 quando tem 12 ou 13, aceita 10 ou 11`)
- **Contato do CRM** → Vínculo gravado no CRM (`contact_id diferente de vazio e de 0`)
- **Nome** → Só valida, nunca liga (`minúsculo, sem acento, sem sufixo como ltda`)

### Definições

| Métrica | Definição |
|---|---|
| Pessoa única | documento normalizado válido (CPF de 11 ou CNPJ de 14 dígitos); 1 linha por documento, com a lista de fontes em que aparece |
| Cliente ativo | pessoa com pelo menos um contrato ativo pela regra da sua fonte na data de referência, fora da lista de cancelados e, se declarado, da de inadimplentes |
| Data de ativação | menor data de pagamento entre as faturas pagas do contrato; para apólice, início de vigência |
| Contratos ativados no mês | contratos distintos (fonte + id na origem) cuja data de ativação cai no mês |
| Base ativa por regional | pessoas ativas distintas por regional do contrato na data de referência; pessoa com contratos em duas regionais conta uma vez em cada e uma vez no total |
| Conversão de lead | lead com vínculo a contrato registrado na data de criação do lead ou depois, pela chave mais forte disponível |
| Cliente que voltou | lead com vínculo a contrato registrado antes da criação do lead; não entra na conversão |
| Cobertura de documento | linhas com documento válido / total de linhas, por fonte, na data da execução |

### Armadilhas

- **Zero à esquerda sumiu.** CNPJ e CPF lidos como número de planilha ou CSV perderam os zeros iniciais e um CNPJ começado em 00 nunca casava com o core. Como evitar: Leia documento como texto e complete com zeros até 11 ou 14 dígitos.
- **Apólice com um dígito a mais.** O número da apólice veio como float, "8539905.0", e a limpeza de não-dígitos gerou 85399050, que não batia com nada. Como evitar: Remova o ".0" final antes de tirar não-dígitos.
- **O mesmo cooperado três vezes.** Somar o core de proteção, o sistema de apólices e o pipeline do CRM contava a mesma pessoa uma vez em cada sistema. Como evitar: Empilhe com fonte e consolide por documento antes de contar.
- **Venda nova que já era cliente.** Leads de campanha casados por telefone com contratos de anos antes apareciam como conversão do mês. Como evitar: Compare a data do contrato com a criação do lead e separe cliente que voltou.
- **Captação do assessor errado.** A captação de meses anteriores foi atribuída ao assessor atual da conta depois de uma troca de carteira. Como evitar: Cruze pelo histórico de vigência da carteira na data da captação.
- **Funciona na consulta, quebra no pipeline.** A query validada no editor usava índice de array a partir de 1 e cardinality; virou transformação em Spark, que indexa a partir de 0 e usa size, e passou a pegar o item errado. Como evitar: Teste a regra no motor em que ela vai rodar antes de publicar a tabela.

### Teste de aceitação

- [ ] Nenhum documento normalizado aparece em mais de uma linha da tabela de pessoas.
- [ ] Toda linha tem documento com 11 ou 14 dígitos ou documento nulo com motivo; nenhuma tem dígitos todos iguais.
- [ ] A contagem de clientes ativos por fonte bate com a contagem do próprio sistema na mesma data (core por status ATIVO, apólices active, etapa Ativo do pipeline).
- [ ] Contratos ativados no mês = contratos com primeira fatura paga no mês, conferido em 5 contratos escolhidos ao acaso.
- [ ] Todo vínculo lead para contrato tem a chave usada e a classificação conversão ou cliente que voltou.

### Context document

```text
Base única por CPF e CNPJ
- A pessoa é identificada pelo documento normalizado: só dígitos, CPF com 11 e CNPJ com 14, zeros à esquerda preservados. Documento com outro tamanho ou com dígitos todos iguais é inválido e não liga cadastros.
- Para contar pessoas, use documento distinto. Nunca conte linhas: a tabela de detalhe tem uma linha por contrato, objeto (placa, chassi, apólice, conta) e às vezes por produto.
- Cliente ativo: contrato ATIVO no core, apólice active no sistema de apólices, ou negócio na etapa Ativo do pipeline <pipeline> do CRM; e fora da lista de cancelados. Inadimplente: <entra | não entra> na base ativa.
- Data de ativação = primeiro pagamento confirmado do contrato. Para apólice, início de vigência.
- Cliente prevalece sobre lead. Um lead só é conversão se o contrato foi registrado na criação do lead ou depois; contrato anterior é cliente que voltou.
- Diga sempre por qual chave o vínculo foi feito (documento, placa, chassi, telefone, contato do CRM). Telefone sozinho é sinal fraco.
- Responsável (assessor, consultor, corretor) em perguntas sobre o passado: use o vigente na data do fato, pelo histórico da carteira. Para listas de hoje, use o atual.
- Se a pergunta não disser o produto ou o sistema, responda com o total consolidado e abra por fonte.
Exceções por cliente:
- <cliente>: produto <produto> existe só no CRM; ativo = etapa <etapa> do pipeline <id>.
- <cliente>: inadimplentes há mais de <N> dias saem da base ativa.
```

### Variações

- **Investimentos:** A pessoa é o CPF e o objeto é a conta em cada instituição. O assessor vem do histórico da corretora pela data do fato.
- **Previdência e benefícios B2B:** Dois níveis: empresa (CNPJ) e colaborador (CPF), com o contato do CRM ligado à empresa pela raiz do CNPJ.
- **Planejamento financeiro:** Clientes e leads do planejador numa só base, com saldo por instituição e um histórico diário por cliente, conta e data.