Visão geral

O TermoLeads é o app da Termotubos para consultar a base CNPJ da Receita Federal. A Receita publica todo mês os dados cadastrais de todas as empresas do Brasil; o TermoLeads baixa essa base, monta uma tabela pronta para consulta e oferece duas telas em cima dela: a ficha completa de um CNPJ e a busca de empresas por situação, estado, cidade e atividade.

É a partir dessa busca que a equipe encontra leads: empresas ativas de um segmento em uma região, com telefone, e-mail e endereço cadastrados na Receita.

Quem usa

O acesso é pelo TermoAuth, o serviço central de login da Termotubos. O TermoLeads é registrado lá como o app termo-leads, aberto só ao perfil colaborador: quem tem perfil cliente não recebe token para ele. O TermoLeads não tem tela de login, não guarda senha e não tem tabela de usuários: ele recebe um token do TermoAuth e confere a assinatura. Quem é master também vem do token, pelo claim isMaster. Os detalhes estão em Arquitetura .

O que o sistema faz

• Consultar CNPJ — Digita um CNPJ e vê a ficha: empresa, estabelecimento, Simples Nacional e MEI e o quadro de sócios.
• Localizar Empresas — Filtra a base por situação, UF, cidade e CNAE e percorre a lista paginada, com telefone e e-mail de cada empresa.
• Importação da base CNPJ — O master baixa o mês mais recente publicado pela Receita e troca a base inteira, sem deixar a consulta fora do ar.
• Base CNPJ — Como os arquivos da Receita viram uma única tabela, com uma linha por estabelecimento.

Como os dados chegam até a tela

1. A Receita publica a base

Todo mês a Receita Federal publica uma pasta AAAA-MM com arquivos .zip: empresas, estabelecimentos, sócios, Simples Nacional e as tabelas de códigos (CNAE, municípios, naturezas jurídicas, qualificações, motivos e países).

2. O master dispara a importação

Na tela Dados da Receita (/master/dados-receita), o master inicia a importação. O backend baixa o mês mais recente, junta os arquivos e monta uma tabela nova ao lado da atual.

3. A base nova entra no ar de uma vez

Quando a tabela nova está completa e indexada, uma única transação troca a base antiga pela nova. Até esse instante, a consulta continua respondendo com a base anterior.

4. O colaborador consulta

As telas Consultar CNPJ e Localizar Empresas leem essa tabela diretamente, sem cruzar tabelas na hora da consulta.

Princípios

• A base é da Receita, não do TermoLeads. Nenhuma tela edita dados de empresa. A única forma de mudar a base é importar de novo.
• Os dados ficam como a Receita publicou. Todo campo é guardado como texto, com os zeros à esquerda, as datas no formato AAAAMMDD e os acentos preservados. As descrições (nome do CNAE, do município, da situação) são acrescentadas ao lado do código, nunca no lugar dele.
• Importar nunca derruba a consulta. A base nova é montada numa tabela à parte e só substitui a atual no fim, numa transação. Download incompleto, erro ou cancelamento deixam a base atual intacta.
• O TermoLeads só consulta. Ele não guarda leads trabalhados, histórico de contato nem funil de vendas: a lista de empresas é o ponto de partida, e o trabalho com cada lead acontece fora dele.

Como ler esta documentação

• Fluxos — As três telas do sistema: o que cada uma faz, as regras e o que acontece no backend.
• Base CNPJ — As tabelas do banco e como cada coluna se relaciona com os arquivos da Receita.
• Arquitetura — Backend, frontend, autenticação pelo TermoAuth, portas e como rodar localmente.
• Glossário — CNPJ básico, estabelecimento, CNAE, situação cadastral e os demais termos usados aqui.