# 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.