--- id: saas/cliente-unico-billing-crm-produto industria: SaaS e tecnologia uso: muito usado esforco: médio grao: 1 linha por conta canônica, mais uma ponte por sistema (1 linha por id externo) --- # Cliente único entre billing, CRM, produto e suporte Uma linha por cliente com o id dele em cada sistema e o método do vínculo, para receita, uso e tickets finalmente se cruzarem. ## Resumo executivo **Para quem:** Empresas de SaaS cujo cliente é um customer no billing, uma company no CRM, um workspace no produto e um e-mail no suporte. **O que resolve** - Receita, uso, tickets e negócios do CRM passam a se cruzar pela mesma chave. - Cada vínculo diz como foi feito, então dá para confiar ou auditar. - O mesmo cliente para de ser contado duas vezes, e dois clientes param de virar um só. **Por que importa:** Sem essa ponte, nenhuma métrica por cliente fecha: o MRR não encontra o uso, o ticket não encontra a conta e o negócio ganho não encontra a assinatura. Um vínculo errado é pior que nenhum, porque mistura a receita de um cliente com o risco de outro sem ninguém perceber. **Perguntas de negócio que responde** - Qual o MRR, o uso e os tickets abertos do cliente X? - Esse negócio ganho virou qual cliente pagante? - Quais clientes pagam no billing e não existem no CRM? - Quais empresas têm mais de uma conta pagando separadamente? - Quantos tickets do mês não conseguimos ligar a nenhum cliente? **O que você precisa** - Billing, CRM e banco do produto conectados na Nekt - Um campo que guarde o id de um sistema dentro do outro, ou o CNPJ preenchido - Um dono para as correções manuais de vínculo **O que você recebe** - Uma tabela de clientes canônicos com o id de cada sistema - A coluna de método e qualidade de cada vínculo - Filas de qualidade: pagantes sem CRM, CRM sem pagante, conflitos de CNPJ - Um agente de IA que encontra o cliente por qualquer id ## Detalhado ### O problema Cada sistema identifica o cliente do seu jeito: o billing por customer, o CRM por company e deal, o produto por workspace e o suporte por e-mail. Quem cruza por nome ou por domínio de e-mail casa empresas diferentes que usam gmail e separa a mesma empresa que tem dois CNPJs. Quando o mapa é regravado em vez de atualizado, clientes diferentes acabam fundidos e a receita de um aparece no outro. ### Regras de negócio 1. **Um cliente canônico, uma coluna por sistema.** Crie uma chave própria de cliente e uma ponte por sistema (customer do billing, company do CRM, workspace do produto, organização do suporte). O cliente canônico é a conta econômica que paga, não o usuário nem a assinatura. Guarde em cada linha como o vínculo foi feito (linked_via ou match_method) e um nível de confiança. (Evite: Juntar as tabelas direto pelo nome da empresa em cada consulta.) 2. **Cascata de chaves, da mais forte para a mais fraca.** 1) Id de um sistema gravado no outro (id da assinatura no deal, id do customer na conta do produto, id do produto em atributo customizado do suporte). 2) CNPJ só com dígitos. 3) Domínio de e-mail corporativo. 4) Nome normalizado, só como último recurso e marcado como fraco. A primeira regra que casar decide. (Evite: Usar nome ou domínio mesmo quando existe um id gravado.) 3. **CNPJ normalizado com 14 dígitos.** Remova tudo que não é dígito e complete com zeros à esquerda até 14 dígitos. CNPJ guardado como número perde o zero inicial e não casa. Documento com 11 dígitos ou menos é CPF. (Evite: Comparar o CNPJ como veio, com pontos, barra ou sem o zero inicial.) 4. **E-mail pessoal nunca vira chave de empresa.** Descarte gmail, hotmail, outlook, yahoo, icloud, uol e similares antes de casar por domínio. Para esses, a chave é o e-mail inteiro. Normalize o e-mail com minúsculas e sem espaços; no Gmail, ignore pontos e o sufixo +alias. (Evite: Agrupar todos os clientes com @gmail.com como uma empresa.) 5. **Nome nunca confirma um vínculo.** Nome é útil para sugerir um vínculo, não para confirmar. Se houver casamento aproximado, normalize (sem acento, sem ltda, me, epp, eireli, sa) e exija pelo menos 5 caracteres e 2 palavras. Quando existe identificador estável, ele vence o nome. (Evite: Casar por nome parecido e tratar como certo.) 6. **Declare conta e sub-conta.** Uma empresa pode ter várias sub-contas pagando (várias assinaturas, vários CNPJs do grupo). Diga em cada métrica qual grão ela usa. Somar as sub-contas pode mudar a faixa do cliente e quem o CS atende. No grupo com vários CNPJs, o principal é o de maior MRR, para a identidade não mudar sem motivo. (Evite: Receita por sub-conta e qualificação por empresa, sem dizer qual é qual.) 7. **Quando os sistemas discordam, um manda.** Defina a precedência de status. Em geral, o billing ou o produto manda sobre o CRM, que fica desatualizado: numa base real, havia três vezes mais companies marcadas como churn no CRM do que workspaces inativos no produto. (Evite: Ler o status do cliente no CRM.) 8. **O mapa é atualizado, nunca regravado por cima.** A ponte deve ter um id canônico por CNPJ e por id externo, mantendo o vínculo mais antigo. Uma ponte gravada por append em vez de upsert criou linhas conflitantes e fundiu clientes diferentes, levando a receita de um para o outro. Guarde a ponte com válido de e válido até quando o vínculo muda. (Evite: Acrescentar linhas no mapa a cada execução.) 9. **Correções manuais numa tabela, com motivo.** Vínculos que nenhuma regra resolve vão para uma tabela de sobrescritas com o id, a data, quem confirmou e o motivo, aplicada antes da cascata. Sempre que possível, corrija também na origem (o CNPJ ou o id no CRM). (Evite: Casos especiais escritos à mão dentro do SQL.) 10. **Tire usuários internos, de teste e de serviço.** Contas de teste, demo e e-mails da própria empresa saem do mapa. No mapa de usuário para conta, usuários de serviço e integrações não podem ligar uma conta à outra. Em eventos de produto, resolva a conta em cascata: id da conta no evento, depois workspace para conta, depois usuário para conta. (Evite: Deixar o usuário de integração ligado a várias contas.) ### Chaves de vínculo por ordem de confiança A primeira que casar decide. Grave qual foi na coluna de método. - **Deal do CRM com id da assinatura** → Forte: id gravado (`deal.id_assinatura = subscription.id`) - **Conta do produto com id do customer** → Forte: id gravado (`conta.billing_customer_id = customer.id`) - **Suporte com id do produto em atributo** → Forte: id gravado (`custom_attributes.`) - **CNPJ em dois sistemas** → Forte: documento (`lpad(só dígitos, 14)`) - **Domínio de e-mail corporativo** → Média: domínio (`fora da lista de e-mail pessoal`) - **E-mail pessoal** → Média: e-mail inteiro (`lower, trim, Gmail sem pontos e +alias`) - **Nome normalizado** → Fraca: só sugere (`sem acento e sufixo societário`) - **Sobrescrita manual** → Vence todas (`tabela datada com motivo`) ### Definições | Métrica | Definição | |---|---| | Cliente canônico | conta econômica que paga, 1 linha por cliente, com chave própria que não muda quando um id externo muda | | Sub-conta | cada customer ou assinatura do billing que pertence ao cliente canônico | | Método do vínculo | regra da cascata que ligou o id externo ao cliente: id gravado, CNPJ, domínio, e-mail, nome ou sobrescrita | | Cobertura do vínculo | MRR dos clientes pagantes com vínculo forte no CRM / MRR total, no último dia do mês | | Pagante sem CRM | cliente com MRR > 0 no billing sem company ou deal vinculado | | CRM sem pagante | company ou deal ganho sem cliente pagante vinculado, excluindo negócios ainda em implantação | | Conflito de documento | cliente canônico com 2 ou mais CNPJs ou CPFs distintos que não pertencem ao mesmo grupo econômico declarado | ### Armadilhas - **Fusão falsa por append.** O mapa de identidade foi gravado por append durante semanas, ganhou dois ids para o mesmo CNPJ e passou a fundir clientes diferentes no relatório de receita. Como evitar: Grave a ponte por upsert, com um id canônico por CNPJ e o vínculo mais antigo vencendo. - **Duas verdades sobre a mesma empresa.** A qualificação de leads era medida por empresa e a receita por sub-conta. Empresas com várias sub-contas mudavam de faixa quando as irmãs eram somadas. Como evitar: Crie a conta empresa como verdade adicional e diga em cada métrica qual grão ela usa. - **CRM dizia churn, produto dizia ativo.** O CRM tinha muito mais companies marcadas como perdidas do que workspaces de fato inativos, e os relatórios de churn divergiam. Como evitar: Defina que billing ou produto manda e corrija o CRM a partir deles. - **Deal conta a empresa várias vezes.** Um cliente com três produtos tinha três deals ganhos e aparecia como três clientes no relatório comercial. Como evitar: Ligue deal à assinatura e conte clientes pelo id do customer, não pelo deal. - **Ticket sem empresa.** Tickets chegavam só com e-mail ou telefone e ficavam fora do health score. Como evitar: Ligue pelo e-mail do contato, depois pelo domínio corporativo, e meça a fatia de tickets sem cliente. Validado em dados reais: Na própria Nekt, cerca de 1 em cada 10 customers do Stripe usa e-mail pessoal (gmail, hotmail), o que impede casar por domínio, e cerca de 1 em cada 8 divide o e-mail com outro customer. No HubSpot, metade das companies não tem domínio preenchido e há domínios repetidos entre companies. A ponte que funciona é o id do customer gravado na organização do produto, não o nome nem o domínio. ### Teste de aceitação - [ ] Cada id externo (customer, company, workspace) aparece em no máximo um cliente canônico. - [ ] Nenhum cliente canônico tem dois CNPJs que não estejam declarados como mesmo grupo econômico. - [ ] O MRR somado pelos clientes canônicos é igual ao MRR total do billing no mesmo dia. - [ ] Pelo menos 95% do MRR tem vínculo forte (id gravado ou CNPJ) com o CRM, e a lista do restante existe com o motivo. - [ ] Nenhum cliente canônico é formado só por um domínio de e-mail pessoal. ### Context document ```text Identidade do cliente - Cliente = conta econômica que paga. Use a chave canônica da tabela de identidade, nunca o nome da empresa. - Para ligar sistemas, use a tabela de identidade. A ordem de confiança é: id gravado em outro sistema > CNPJ (só dígitos, 14 posições) > domínio de e-mail corporativo > nome normalizado. - E-mail pessoal (gmail, hotmail, outlook, yahoo, icloud, uol) nunca é chave de empresa. - Vínculo por nome é fraco: avise quando a resposta depende dele. - Conta = a empresa. Sub-conta = cada customer ou assinatura que paga. Diga qual grão está usando. - Status do cliente vem do billing ou do produto, não do CRM. - Contas internas, de teste, de demo e usuários de serviço não são clientes. - Se um id não estiver na tabela de identidade, diga que o cliente não foi vinculado em vez de adivinhar. Exceções por cliente: - : grupo econômico com os CNPJs , consolidado no CNPJ . - : vínculo manual entre a conta e a assinatura , confirmado em . ``` ### Variações - **Devolver ao CRM:** Grave o id do cliente canônico e o MRR na company do CRM para vendas e CS trabalharem com a mesma chave. - **Casamento probabilístico:** Para contatos sem id, um modelo de deduplicação com regra negativa: nenhum grupo pode ter dois CPFs distintos. - **B2C e self-service:** Sem CNPJ, a chave é o e-mail canônico. Para vários customers com o mesmo e-mail, some receita por pessoa.