DESKTOP-F2O4A80\UserandClaude
b8d10b210c
App local (Node + SQLite) para captura, tratamento e exportacao de leads comerciais, com dashboard de gestao, login/usuarios e integracao Z-PRO. Co-Authored-By: Claude <noreply@anthropic.com>
76 lines
3.6 KiB
Markdown
76 lines
3.6 KiB
Markdown
# Captura de Leads
|
||
|
||
A captura procura empresas por **UF + cidades + nichos** nas fontes selecionadas,
|
||
pontua cada lead (score/classificação) e grava tudo no banco local com
|
||
deduplicação automática — um lead capturado uma vez nunca é duplicado, em nenhuma
|
||
execução futura.
|
||
|
||
O jeito normal de usar é pela **aba "Capturar Leads" do aplicativo**
|
||
(GTI-Comercial.exe). Este documento cobre os detalhes e o uso por linha de comando.
|
||
|
||
## Fontes
|
||
|
||
| Fonte | Custo | Observações |
|
||
|---|---|---|
|
||
| `cnpj-base` | grátis | **Principal.** Base oficial da Receita Federal extraída por UF (~97% com telefone). |
|
||
| `brasilapi` | grátis | Mesma base CNPJ, enriquecida online via BrasilAPI (mais lenta). |
|
||
| `overpass` | grátis | OpenStreetMap por área da cidade (bounding box automática via geocode). |
|
||
| `nominatim` | grátis | Busca textual no OpenStreetMap. |
|
||
| `wikidata` | grátis | Empresas registradas no Wikidata (volume baixo). |
|
||
| `google-places` | paga | Exige `GOOGLE_MAPS_API_KEY` no `.env`. |
|
||
| `mock` | — | 3 leads fictícios para testar o fluxo. |
|
||
|
||
## Base CNPJ por estado
|
||
|
||
Cada UF precisa de uma extração única (~40–60 min) que gera
|
||
`prospeccao/cnpj/estabelecimentos-<UF>.csv` a partir dos zips brutos da Receita
|
||
(`prospeccao/cnpj/rfb-raw/`, Brasil inteiro, já baixados). A interface oferece o
|
||
botão **"Extrair base agora"** quando a UF escolhida ainda não tem base; na linha
|
||
de comando:
|
||
|
||
```bash
|
||
node scripts/extrair-base-cnpj.mjs --uf=SP
|
||
```
|
||
|
||
A extração cobre **todos os municípios da UF** — depois dela, qualquer cidade do
|
||
estado pode ser capturada na hora, sem re-extração. Um checkpoint em disco permite
|
||
retomar de onde parou se o processo for interrompido.
|
||
|
||
## Deduplicação e pontuação
|
||
|
||
- Chave de duplicidade: **CNPJ válido → WhatsApp válido → empresa+cidade**.
|
||
- **Score de Qualidade** (0-100, "os dados são confiáveis?"): +30 WhatsApp válido,
|
||
+20 CNPJ válido, +20 empresa válida, +5 cidade, +10 nicho, +10 CNAE, +5 website.
|
||
- **Score Comercial** (0-100, "qual a chance de comprar?"): aderência do nicho
|
||
(alta 40 / média 30 / baixa 20, configurada por nicho em `prospeccao/config.json`)
|
||
+ website 15 + e-mail 10 + WhatsApp válido 15 + CNPJ válido 20.
|
||
- **Score Geral** = 60% comercial + 40% qualidade — é o valor usado para ordenar
|
||
a tela de Tratamento.
|
||
- **Classificação**: 90-100 Excelente, 75-89 Bom, 55-74 Médio, 35-54 Baixo,
|
||
0-34 Muito Baixo. A **Prioridade comercial** (P1-P4, mostrada na tela) deriva
|
||
direto dela: Excelente/Bom ⇒ P1 (atacar já), Médio ⇒ P2 (na semana), Baixo ⇒ P3,
|
||
Muito Baixo ⇒ P4 (só em campanhas específicas).
|
||
- Cada nicho tem produtos GTI recomendados automaticamente (ERP, G-Delivery,
|
||
G-Chat, Sistema de Ponto) que aparecem no card do lead. Se o catálogo de
|
||
aderência/produtos do `config.json` mudar, rode `npm run recalc-scores` para
|
||
recalcular todos os leads já capturados.
|
||
|
||
## Linha de comando (uso avançado)
|
||
|
||
```bash
|
||
node scripts/capturar-leads.mjs --sources=mock
|
||
node scripts/capturar-leads.mjs --sources=cnpj-base --uf=BA --cities="Ilheus,Itabuna"
|
||
node scripts/capturar-leads.mjs --sources=cnpj-base,overpass --uf=BA --cities=all --segments=all
|
||
node scripts/capturar-leads.mjs --help
|
||
```
|
||
|
||
Parâmetros úteis: `--segments=a,b,c` (nichos pelo nome), `--segment-limit=N`,
|
||
`--city-limit=N`, `--max=N` (resultados por consulta nas fontes de API),
|
||
`--query-limit=N` (teto total de consultas).
|
||
|
||
## Ritmo e boas práticas (fontes OpenStreetMap)
|
||
|
||
Os servidores públicos do Overpass/Nominatim têm limites de uso. O app já aplica
|
||
espera entre consultas (`OVERPASS_REQUEST_DELAY_MS`), failover entre endpoints e
|
||
cooldown após falhas — falha de uma cidade não derruba a captura, só pula.
|