Módulo 8 - Enriquecedor do CRM¶
Quando o SDR digita um CNPJ numa negociação do RD CRM, este robô consulta a Receita Federal, preenche o cadastro da empresa sozinho e avisa se aquela empresa já existe no CRM com outro nome.
Vive na pasta enriquecedor/ do repositório veggi-ads-dashboard, mas é totalmente independente dos módulos 6 e 7: Worker próprio, KV próprio e lógica própria. O que divide com eles é só o repositório git.
| Item | Valor |
|---|---|
| Worker | veggi-enriquecedor |
| URL | veggi-enriquecedor.veggiageral.workers.dev |
| Código | enriquecedor/worker/src/index.js + enriquecedor/src/logica.mjs (1.206 linhas) |
| KV binding | ENRIQUECEDOR — 0bc265da159944d5bff7142d1fcaf1b2 |
| Secrets | RD_CRM_TOKEN, CHAVE, SEGREDO_WEBHOOK |
| Fontes de dados | BrasilAPI e MinhaReceita (as duas, gratuitas) |
Como explicar para o SDR¶
Esta é a parte que interessa a quem vai treinar a equipe comercial. O repositório tem uma versão visual em enriquecedor/GUIA-SDR-cnpj.html — dá para abrir no navegador e mandar para a equipe.
A regra de ouro¶
O CNPJ vai no campo da NEGOCIAÇÃO, nunca direto na empresa
É o campo da negociação que aciona o robô e dispara a verificação de duplicada. Digitar direto no cadastro da empresa pula essa verificação — e é exatamente aí que nasce cadastro repetido.
Os passos do SDR¶
- Ter o CNPJ em mãos (o cliente informou, ou você confirmou)
- Abrir a negociação e preencher o campo CNPJ dela — o da negociação, não o da empresa
- Salvar. Em poucos segundos o robô começa a trabalhar
- Conferir as anotações da negociação
O que o robô faz sozinho¶
Assim que o CNPJ entra, ele verifica se a empresa já existe no CRM — pelo nome ou pelo mesmo CNPJ. Daí saem dois caminhos:
Existe outra empresa igual — mesmo nome ou mesmo CNPJ, ainda que escrito diferente. O robô escreve um alerta de possível empresa duplicada.
O SDR faz: confere. Se for a mesma loja, troca a empresa da negociação pela que já existe. Não cadastra de novo.
O robô copia o CNPJ para o cadastro da empresa e preenche tudo pela Receita:
- Razão social e nome fantasia
- Cidade / UF e situação (CNPJ ativo?)
- Endereço completo — rua, número, bairro, CEP
- Atividade, data de abertura, telefones e sócios
- Instagram, puxado do contato
- Corrige o nome da empresa para a razão social oficial
O SDR faz: nada — só confere. O robô ainda deixa uma nota de registro na negociação.
A regra do nome
O nome da empresa é sempre a razão social. O nome pelo qual a loja é conhecida vive no campo Nome fantasia.
Como MEI quase nunca declara nome fantasia na Receita (em 09/09/2026, 4 de 5 vieram vazias), o robô faz o seguinte ao trocar o nome: copia o nome antigo para o Nome fantasia — só quando o campo está vazio. Assim "Bambolê", "HIJEPE" e "Nanymodaintima" continuam no cadastro, no lugar certo, em vez de sumirem.
A anotação diz para onde o nome foi: "O nome antigo não se perdeu: guardei Nanymodaintima no campo Nome fantasia da empresa." Se o campo já estava ocupado — pela Receita ou pela SDR —, ele não mexe, e o nome antigo fica registrado na própria anotação.
Quatro dados que o robô replica depois¶
Nem sempre o SDR tem tudo na primeira conversa. Estes quatro são copiados para a empresa no momento em que ele salvar — sem precisar preencher duas vezes:
| Dado | Onde o SDR preenche |
|---|---|
| Tipo de revenda | na negociação |
| Segmento da Loja | na negociação |
| no contato | |
| Celular | no contato (o telefone é copiado automaticamente) |
O que o SDR nunca deve fazer¶
| ✕ | Por quê |
|---|---|
| Digitar o CNPJ direto no cadastro da empresa | Pula a verificação de duplicada e gera cadastro repetido |
| Preencher os dados da Receita na mão | O robô preenche. Ele respeita o que já existe e não sobrescreve |
| Criar empresa nova quando o robô apontou duplicada | Trocar pela que já existe no CRM |
Uma exceção ao 'não sobrescreve'
O campo CNPJ Ativo é sempre reconferido na Receita a cada passagem do robô — se a loja foi inativada desde a última vez, o campo muda. O campo Último Enriquecimento mostra quando o robô mexeu por último.
Casos especiais¶
| Aviso do robô | O que significa | O que fazer |
|---|---|---|
| "CNPJ com problema" | O número tem erro de digitação | Confirmar com o cliente e corrigir no campo da negociação |
| "CNPJ válido, mas sem dados automáticos" | Empresa recém-aberta, ainda não consta nas bases gratuitas | Consultar ao vivo em consultacnpj.redesim.gov.br |
| "EMPRESA DUPLICADA (CADASTRADA HOJE)" | O mesmo cliente foi cadastrado duas vezes hoje — o nome que esta empresa deveria receber já é de outra | Escolher qual cadastro fica, mover a negociação para ele e apagar o repetido. O robô não renomeou nada |
| "NÃO CONSEGUI COMPLETAR OS DADOS DESTA EMPRESA" | O RD recusou a gravação de verdade | Abrir /falhas para ver o motivo exato que o RD devolveu |
| Os dados não apareceram na hora | Normal — leva alguns segundos após salvar | Atualizar a página da negociação |
Lead que se cadastra duas vezes
É o caso mais comum de duplicata: a pessoa preenche o formulário e minutos depois é cadastrada de novo à mão, com e-mail ou telefone escrito diferente. A trava do RD não pega, porque para ele são duas pessoas. Quem avisa é o robô.
Atenção ao encerrar a repetida: a etiqueta do anúncio costuma estar na que veio do formulário. Encerrando essa e mantendo a criada à mão, a venda deixa de ser creditada à campanha que trouxe o cliente.
Como funciona por dentro¶
Três gatilhos¶
| Gatilho | Quando | Para quê |
|---|---|---|
| Webhook | O RD avisa na hora que uma negociação é criada | Caminho normal, instantâneo |
| Cron 15 min | */15 * * * * |
Rede de segurança: pega o que o webhook não entregou |
| Cron 9h-12h UTC | 4 das 96 batidas do dia | Monta o catálogo de empresas em pedaços |
Por que um cron só faz as duas coisas
A conta tem limite de 5 gatilhos cron no total, compartilhado entre todas as aplicações. Então existe um único cron de 15 minutos, que decide a tarefa pelo horário. O catálogo é montado em 4 pedaços porque são 100 chamadas no total e o plano grátis permite 50 por execução — o último pedaço junta tudo.
Como ele enxerga empresa duplicada¶
São duas camadas, e elas cobrem coisas diferentes:
| Camada | Como funciona | O que enxerga | O que não enxerga |
|---|---|---|---|
| Catálogo | Cópia de todas as empresas com CNPJ, montada de madrugada e guardada no KV | Duplicata antiga, por CNPJ | Empresa cadastrada depois da foto — inclusive a de minutos atrás |
| Consulta ao vivo | Pergunta ao RD, na hora, se alguém já usa o nome que ele está prestes a gravar | Duplicata criada hoje | — |
Por que a consulta ao vivo é por NOME, e não por CNPJ
O q da API v1 do RD não enxerga campo personalizado: procurar por CNPJ ali devolve zero mesmo com a empresa existindo (conferido em 09/09/2026). Nome é o que dá para consultar — e é justamente o que colide, porque o RD não aceita duas empresas com o mesmo nome. Era essa colisão que derrubava a gravação inteira com HTTP 422.
A consulta acontece só quando há renomeação de fato: se o nome já está certo, não gasta chamada nenhuma.
Quando dá duplicada, ele não preenche os campos daquela empresa
E não é perda: com o nome colidindo, o RD recusa o PUT inteiro — preencher era impossível de qualquer jeito. Os dados ficam no cadastro que sobreviver à unificação.
O teto de 50 chamadas por execução¶
A Cloudflare conta chamadas externas por execução, não por dia. No plano grátis são 50.
| Caminho | Negociações por execução | Chamadas |
|---|---|---|
| Webhook | 1 | ~12 de 50 |
| Varredura do cron | até 3 | ~36 de 50 |
Por que a varredura pega 3, e não 8
As negociações da varredura dividem o mesmo teto, porque rodam todas dentro de uma execução só. Com 8 dariam ~96 chamadas e a Cloudflare cortaria as últimas no meio — e gravação cortada é justamente o que faz o robô achar que falhou e escrever anotação de erro à toa.
Não há perda de capacidade: o cron bate 92 vezes por dia, o que dá 276 negociações de folga para uma dúzia de leads. Quem não coube entra na batida seguinte, 15 minutos depois — a negociação só é marcada como resolvida quando dá certo, então ela continua na fila.
A trava de segurança¶
A chave real fica no KV, não no código
O valor do wrangler.toml é só o padrão inicial. O liga/desliga de verdade mora no KV, para poder ser acionado pelo navegador, na hora, sem depender de ninguém publicar nada.
| Ação | Link |
|---|---|
| Ver o estado (não muda nada) | / |
| Desligar agora — botão de emergência | /desligar?key=CHAVE |
| Ligar | /ligar?key=CHAVE |
Desligar para a escrita na hora. O robô continua rodando e calculando, mas não grava nada.
Anotação feita não se apaga pela API
O RD não permite. Dá para editar o texto pela tela do RD, mas não remover. Por isso a trava existe e começa em "nao".
Rotas¶
Endereço base
https://veggi-enriquecedor.veggiageral.workers.dev
As rotas abaixo são o caminho depois desse endereço.
| Rota | O que faz |
|---|---|
POST /rd |
Webhook do RD — chegada de negociação nova |
/uma |
Processa uma negociação específica |
/varrer |
Varredura manual |
/avisos · /ultimo-aviso |
O que o robô avisou — as 15 últimas linhas, 7 dias |
/falhas |
Só as falhas, com o texto inteiro devolvido pelo RD — 50 registros, 90 dias |
/catalogo |
Estado do catálogo de empresas |
/ligar · /desligar |
A trava de escrita |
Por que /falhas existe separado de /avisos
O /avisos guarda 15 linhas e gira rápido: numa tarde movimentada, o motivo de um erro é empurrado para fora da lista antes de alguém conseguir ler. Aconteceu em 08/09/2026 — o texto do HTTP 422 tinha sumido quando fomos procurar. Falha é rara e é justamente o que se precisa ler depois, então tem lista própria e prazo longo.
A anotação na negociação continua mostrando só o número da resposta, de propósito: se o texto variasse a cada tentativa, a trava anti-repetição não reconheceria o aviso e ele voltaria todo dia na mesma negociação.
Falha que não é falha
Quando o RD recusa a gravação, o robô relê a empresa antes de alarmar. Se o cadastro já estiver enriquecido, foi outra negociação da mesma loja que gravou primeiro (lead duplicado): não é falha, então não vira anotação — fica registrado só em /falhas, com a marca jaEnriquecida.
Duas fontes na Receita¶
Consulta BrasilAPI e, se falhar, MinhaReceita. As duas são gratuitas e atualizam em ritmos diferentes — a segunda às vezes tem empresa nova que a primeira ainda não recebeu.
Deploy¶
cd "C:\Projetos\veggi-ads-dashboard\enriquecedor\worker"
npx wrangler deploy
npx wrangler secret put RD_CRM_TOKEN
npx wrangler secret put CHAVE
npx wrangler secret put SEGREDO_WEBHOOK
Diagnóstico¶
| Sintoma | Causa provável e ação |
|---|---|
| CNPJ salvo e nada aconteceu | Conferir se foi no campo da negociação. Depois abrir /ultimo-aviso |
| Anotação de erro na negociação | Abrir /falhas — lá está o motivo exato que o RD devolveu, com a negociação e a empresa |
| Robô calcula mas não grava | A trava está em "não". Abrir / para ver o estado; /ligar?key=... para religar |
| "CNPJ válido, mas sem dados" em várias empresas | As duas fontes da Receita podem estar fora do ar. Testar BrasilAPI direto no navegador |
| Duplicada antiga não foi detectada | O catálogo pode estar incompleto. Ver /catalogo — ele é montado em 4 pedaços entre 9h e 12h UTC |
| Duplicada criada hoje não foi detectada | A consulta ao vivo só roda quando o robô ia trocar o nome da empresa. Se o cadastro já se chamava exatamente a razão social, não há renomeação, ele não consulta — e o catálogo ainda não tinha a gêmea. Unificar na mão |
| Webhook parou de chegar | Conferir o webhook no RD e o secret SEGREDO_WEBHOOK. O cron de 15 min cobre enquanto isso |
| Empresa com nome errado depois do robô | Ele corrige o nome para a razão social oficial de propósito. Se estiver errado, o CNPJ digitado é de outra empresa |
| "Sumiu o nome pelo qual a gente conhece a loja" | Não sumiu: está no campo Nome fantasia, para onde o robô copia o nome antigo ao renomear. Se o campo já estava ocupado, o nome antigo está na anotação |