Localizar Empresas

Localizar Empresas (/app/consulta-empresas) é a tela de prospecção: a pessoa monta um recorte da base, por exemplo empresas ativas de uma atividade em uma cidade, e percorre a lista com o telefone, o e-mail e o endereço de cada estabelecimento.

Entradas e saídas

Ponto	Descrição
Entrada	Filtros de situação, UF, cidade e CNAE, e o número da página
Saída	Uma página de 12 estabelecimentos e o total de resultados, exato ou estimado
Operação	buscarPaginador da feature cnpj: GET /api/empresas, com login

Os filtros

Filtro	Como funciona
Situação	Ativa traz só a situação cadastral 02. Inativa traz todas as outras (nula, suspensa, inapta, baixada ou sem situação). Todas as situações não filtra. A tela abre com Ativa.
UF	Uma das 27 unidades federativas, ou todas.
Cidade	O nome da cidade como a Receita grava, comparado por igualdade, sem diferença entre maiúsculas e minúsculas. O backend procura o nome com e sem acento, então São Paulo e Sao Paulo dão o mesmo resultado. Não é busca por parte do nome.
Atividade (CNAE)	Um ou mais códigos de CNAE separados por vírgula, como 6201-5/00, 4781400. Pontuação é ignorada. O filtro olha só o CNAE principal, não os secundários.

Os filtros de situação e UF aplicam ao escolher. Cidade e CNAE aplicam ao apertar Enter ou sair do campo. No celular, os mesmos filtros ficam numa folha lateral, aplicados de uma vez. Cada filtro ativo aparece como um marcador que pode ser removido, e há a opção de limpar todos.

A lista

Cada linha mostra a empresa (razão social e nome fantasia), a situação, o CNPJ (com botão para copiar), a cidade e a UF, os telefones (com link para ligar), o e-mail (com link para escrever), o capital social e o botão para abrir a ficha completa em Consultar CNPJ .

A lista vem ordenada pelo CNPJ. A navegação é por Anterior e Próxima, 12 estabelecimentos por página.

Etapas

1. Ler o recorte da URL

Ao abrir, a tela lê os filtros e a página da URL. Assim, recarregar a página ou compartilhar o endereço mantém o mesmo recorte.

2. Buscar a página

O frontend chama GET /api/empresas com pagina, tamanho, situacao, uf, cidade e cnae. O backend normaliza os valores (UF e cidade em maiúsculas, CNAE só com dígitos, situação desconhecida ignorada) e consulta a tabela cnpj.

3. Contar os resultados

Na mesma chamada, o backend conta quantas linhas o recorte tem, com teto de tempo e de quantidade (veja abaixo).

4. Atualizar a URL

Depois de cada busca, a tela grava os filtros e a página na URL, sem criar uma entrada nova no histórico do navegador.

Contagem com teto

Contar milhões de linhas a cada página seria lento demais. Por isso a contagem tem dois limites:

• Até 2.000.000 de resultados. Acima disso, a contagem para e a resposta vem com estimado: true.
• Até 6 segundos. Se a contagem passar desse tempo, ela é interrompida e a resposta também vem como estimada.

Quando a contagem é estimada, a tela mostra "Empresas (pelo menos)" com um + antes do número, e o total de páginas também aparece com +. A página pedida nunca passa da última página que o teto permite.

Regras

• Tamanho da página fixo. O padrão e o máximo são 12. Um tamanho maior na URL é reduzido para 12.
• A busca exige login. Diferente da consulta por CNPJ, a listagem não é pública.
• Recorte vazio. Sem resultado, a tela mostra "Nenhuma empresa para este recorte" e sugere tentar outra cidade, UF ou atividade.
• O TermoLeads não registra o contato. Ligar, escrever e acompanhar a empresa acontece fora do sistema; a lista não marca quem já foi contatado.