B2B Technographics Prospector

Demo ao vivo

Acesse o sistema publicado em produção:

• URL: https://b2b-technographics-prospector.onrender.com/login
• Usuário: comercial.demo
• Senha: LeadPilot#84Nq2x7P

Obs: o serviço fica hospedado no plano gratuito do Render e pode levar ~30s para "acordar" no primeiro acesso. É uma conta de demonstração sem dados reais de clientes.

Painel de leads

Abra /dashboard na URL da API para visualizar todos os leads persistidos pelo n8n. O painel permite filtrar por temperatura e status, pesquisar, editar os contatos, abrir o site da empresa, preparar WhatsApp/e-mail e marcar ou reabrir leads enviados. Painel, API e n8n usam a mesma tabela PostgreSQL; as alterações são sincronizadas imediatamente.

O acesso ao painel é protegido por login. O portal demo fica em /login e redireciona para o dashboard após autenticação. No ambiente local, o padrão é admin / demo1234; no Render, ajuste PORTAL_USERNAME, PORTAL_PASSWORD e PORTAL_SECRET.

Prospecção automática completa

O workflow B2B 03 - Prospecção automática completa não recebe uma lista de domínios. Ele recebe apenas cidade, estado, segmentos e limite, descobre empresas com site na região, visita os sites, encontra CRM e canais de contato, pesquisa sinais públicos de reclamações e vagas, pontua os leads e prepara mensagens de WhatsApp ou e-mail.

Agenda diária -> região/segmentos -> descobrir empresas e sites -> analisar CRM e contato
              -> pesquisar reclamações -> pontuar -> preparar mensagem

Para testar gratuitamente, importe n8n/workflows/03_hot_leads.json e execute Testar agora. O padrão agora pesquisa Santa Catarina inteira em lotes pequenos por cidade. Esse fluxo prioriza estabilidade: busca empresas com site, detecta CRM, encontra contato público, remove duplicados e retorna leads quentes ou mornos qualificados com score mínimo 45. A busca pública profunda de reclamações e vagas fica opcional por API, porque rodar isso dentro da chamada principal do n8n pode causar timeout. Para uso comercial estável com pesquisa profunda, configure SERPER_API_KEY no Render.

Se quiser aprofundar a qualificação com IA, configure DEEPSEEK_API_KEY. Nesse modo, o backend usa a DeepSeek como camada de leitura dos sinais públicos para resumir a oportunidade e reforçar o score.

O sistema não precisa de OpenAI para descobrir leads. O disparo automático, porém, exige uma conta real de WhatsApp Business Cloud API/provedor ou SMTP. Sem essa credencial, o último nó deixa a mensagem e o link prontos, mas não finge que enviou.

Por padrão, POST /api/v1/prospect/run usa only_new=true: consulta um conjunto até cinco vezes maior que o lote solicitado, compara os domínios com o PostgreSQL e devolve apenas empresas ainda não cadastradas. A restrição única da coluna domain também impede duplicação física no banco. Use only_new=false somente para reprocessar ou atualizar leads existentes.

MVP de prospecção B2B com n8n + Python, detecção multipágina de CRM por sinais públicos, enriquecimento opcional, score transparente de oportunidade, geração de abordagem e aprovação humana obrigatória antes do envio.

Arquitetura

n8n (orquestração) -> FastAPI (regras e integrações) -> PostgreSQL
                              |-> sites públicos / technographics
                              |-> Hunter (opcional)
                              |-> OpenAI (opcional; modo demo sem chave)
                              `-> webhook de outreach (bloqueado por padrão)

Subir o projeto

Pré-requisitos: Docker Desktop e Docker Compose.

1. Copie .env.example para .env.
2. Troque senhas e N8N_ENCRYPTION_KEY.
3. Execute:

docker compose up -d --build
docker compose exec n8n n8n import:workflow --separate --input=/workflows

• n8n: http://localhost:5678
• API/Swagger: http://localhost:8000/docs
• Saúde: http://localhost:8000/health

Sem OPENAI_API_KEY, os rascunhos usam um gerador determinístico para permitir o teste completo. Sem DEEPSEEK_API_KEY, a qualificação profunda usa heurística local. Sem HUNTER_API_KEY, o contato pode ser preenchido manualmente pela API. O envio só funciona quando o lead está approved, OUTREACH_ENABLED=true e OUTREACH_WEBHOOK_URL está configurado.

Para habilitar o portal de login em produção, configure:

• PORTAL_USERNAME
• PORTAL_PASSWORD
• PORTAL_SECRET
• PORTAL_SESSION_DAYS
• PORTAL_COOKIE_SECURE

O runtime Python está fixado na série 3.12 por python-api/.python-version, inclusive para deploys nativos no Render.

Rodar n8n local sem Docker

Use esta opção quando quiser executar mais cidades/lotes do workflow sem depender dos limites do n8n web. O n8n local continua chamando a API publicada no Render e usando o mesmo PostgreSQL configurado no backend, então o painel permanece sincronizado.

Pré-requisito: instalar o Node.js LTS em https://nodejs.org/.

No PowerShell:

cd "C:\Users\Usuário\Documents\Codex\2026-07-21\criar-uma-ia-para-automa-o\outputs\b2b-prospector"
.\scripts\start-n8n-local.ps1

Depois abra:

http://localhost:5678

Importe o workflow:

n8n/workflows/03_hot_leads.json

Para volume maior, prefira rodar em lotes. Exemplo seguro:

• 4 a 6 cidades por execução;
• limit entre 8 e 15 por cidade;
• include_complaints=false na coleta diária rápida;
• pesquisa profunda de reclamações/vagas em etapa separada ou com SERPER_API_KEY.

Rodar local evita limite do n8n web, mas não substitui a proteção de timeout no backend. O commit Add prospecting time budget fallback precisa estar publicado na main para a API no Render não ficar presa em site lento ou serviço público instável.

Prospecção nacional de escolas particulares

Importe no n8n local:

n8n/workflows/04_private_schools.json

Esse workflow usa a base oficial do Censo Escolar INEP 2025 já compactada no projeto. Ele não depende de Overpass, DuckDuckGo ou Google para descobrir as escolas e, por isso, a execução principal termina rapidamente.

• fonte primária: 42.454 escolas privadas declaradas ativas no Censo 2025;
• padrão do workflow: somente categoria particular, com telefone público;
• meta: até 100 escolas novas por execução;
• deduplicação: código INEP (external_id) e domínio técnico interno únicos no PostgreSQL;
• validação complementar: até 12 CNPJs por execução na BrasilAPI, com timeout curto;
• falha no CNPJ não interrompe a coleta do INEP;
• o painel mostra a fonte e os motivos da pontuação.

Endpoint:

POST /api/v1/schools/run

Corpo padrão:

{
  "states": [],
  "cities": [],
  "limit": 100,
  "require_phone": true,
  "private_category": "1",
  "only_new": true,
  "enrich_cnpj_limit": 12
}

states e cities vazios pesquisam o Brasil inteiro. Para restringir, use por exemplo "states": ["SC", "PR"]. O telefone do INEP não é tratado automaticamente como WhatsApp; o sistema só cria link de WhatsApp quando esse canal estiver confirmado.

Página para iniciar a prospecção

O administrador pode abrir /prospecting e iniciar uma coleta sem entrar no n8n ou no Swagger. A página permite:

• pesquisar escolas particulares por estado e cidade usando o INEP 2025;
• pesquisar empresas por cidade, estado e segmentos;
• escolher o volume e os critérios mínimos;
• escolher sim ou não para a validação complementar de CNPJ;
• enriquecer escolas com telefone e site do Google Maps e confirmar WhatsApp somente quando existir link público no site oficial;
• manter only_new=true, evitando leads repetidos;
• acompanhar a execução e abrir na central somente os IDs encontrados naquela pesquisa, com uma ação separada para voltar à base completa;
• pesquisar diretamente na Places API (New) sem expor a chave no navegador, revisar a prévia e adicionar os locais ao banco com deduplicação por place_id e domínio.

Para habilitar a busca automática e o laboratório do Google Maps, ative a Places API (New) no Google Cloud, crie uma chave restrita à API e configure no servidor:

GOOGLE_MAPS_API_KEY=sua-chave-restrita

No Render, adicione a variável no serviço da API em Environment. A chave fica somente no backend; o endpoint de configuração informa apenas se ela está presente. Quando configurada, a busca de empresas passa a usar o Google Maps como fonte principal e as fontes abertas como contingência. Na busca de escolas, o Maps fornece perfil, telefone e site; o robô visita o site e só preenche contact_whatsapp quando encontra um link público explícito. O campo contact_phone continua separado. A API também devolve whatsapp_url, e o painel prepara um botão direto com a mensagem de abordagem para os números confirmados no site oficial.

A pesquisa direta do Maps não salva silenciosamente: primeiro apresenta a prévia e depois exibe Adicionar à base. Ao confirmar, o backend verifica o site oficial, importa telefone, CRM, WhatsApp explícito e sinais agregados das avaliações. Locais encerrados são ignorados e resultados já existentes são identificados sem criar uma segunda linha.

O crédito fixo mensal de US$ 200 foi substituído em 1º de março de 2025 por franquias mensais específicas para cada SKU. No modo de teste atual:

• Text Search Pro, sem telefone/site: 5.000 eventos gratuitos por mês;
• Text Search Enterprise, com telefone/site: 1.000 eventos gratuitos por mês;
• Text Search Enterprise + Atmosphere, com avaliações: 1.000 eventos gratuitos por mês.

Os valores e limites podem mudar. Consulte sempre a tabela oficial, configure alertas de orçamento e limite as cotas no Google Cloud. A API nova retorna no máximo cinco avaliações por local, ordenadas por relevância, não necessariamente as mais recentes. Na prospecção de empresas, o backend analisa essa amostra por regras objetivas, registra apenas temas agregados, contagem, score e link da fonte e não copia o texto integral das avaliações para o banco. Sinais como demora, falta de retorno, dificuldade por telefone/WhatsApp, problemas no site e suporte sem solução entram na justificativa do lead.

Para uma demonstração com baixo risco de cobrança, restrinja a chave apenas à Places API (New) e defina uma cota abaixo da franquia mensal. Alertas de orçamento notificam, mas não interrompem sozinhos o consumo; a cota é o controle que bloqueia novas solicitações quando o limite é atingido.

Primeiro teste

1. Abra o workflow B2B 01 - Descoberta de technographics.
2. Edite o nó Definir domínios com domínios que você tem permissão para pesquisar.
3. Execute o workflow.
4. Consulte GET /api/v1/leads no Swagger.
5. Enriqueça (POST /{id}/enrich) ou preencha o contato (PATCH /{id}).
6. Gere (POST /{id}/generate), revise e aprove (POST /{id}/approve).
7. Configure um provedor somente depois de validar a lista de supressão e os textos.

Estados do pipeline

discovered -> enriched -> drafted -> approved -> sent

Qualquer lead pode ir para suppressed; nesse estado a geração e o envio ficam impedidos. Aprovação exige rascunho e e-mail. Envio exige aprovação e duas configurações explícitas.

Priorização de leads

O detector visita a página inicial e até quatro páginas públicas relacionadas a contato, orçamento, atendimento ou sobre. Ele procura assinaturas de CRM e e-mails publicados pela própria empresa. O score é explicável e vai de 0 a 100:

• CRM detectado: 35 ou 50 pontos, conforme a confiança;
• evidência em páginas adicionais: até 20 pontos;
• e-mail profissional público: 20 pontos;
• empresa e setor identificados: 5 pontos cada;
• dor pública e tipo de oportunidade: reforço adicional de score quando há reclamações, vagas ou sinais de suporte/CRM.

Uma empresa sem CRM pode ser classificada como quente quando houver canal de contato público e pelo menos um sinal forte ou recorrente de dor nas avaliações. Uma única avaliação fraca não basta por padrão: o score diferencia sinal isolado de recorrência e mostra no card quantas avaliações da amostra sustentam a classificação.

Temperaturas: hot a partir de 65, warm a partir de 40 e cold abaixo disso. O workflow B2B 03 - Descobrir e priorizar leads quentes reúne todo o teste inicial: recebe os domínios, executa a descoberta, calcula o score e mostra somente os leads quentes. Para testar no n8n, basta importar esse único workflow. O score prioriza revisão; ele não autoriza envio automático.

O último nó do workflow 03 prepara uma abordagem e cria links de WhatsApp ou e-mail. O envio é manual e permanece com status aguardando revisão manual, evitando disparos acidentais durante os testes.

Integrações e extensões

• app/services.py: assinaturas de Bitrix24, HubSpot, Salesforce, RD Station e Pipedrive.
• Hunter: adaptador de busca de e-mail corporativo.
• OpenAI: geração factual pelo endpoint Responses; padrão configurável em OPENAI_MODEL.
• Outreach: webhook genérico compatível com um segundo workflow n8n, Smartlead, Instantly ou serviço próprio.
• BuiltWith/Wappalyzer: próximos adaptadores recomendados para aumentar cobertura e confiança.

LGPD e entregabilidade

Use apenas dados profissionais necessários e com finalidade documentada. Registre fonte e evidência, ofereça opt-out simples, mantenha lista de supressão, aplique limites de volume e não raspe áreas autenticadas ou que proíbam automação. Antes de produção, valide base legal, política de privacidade, retenção e atendimento aos direitos do titular com assessoria jurídica. Não automatize LinkedIn/Indeed diretamente; use APIs ou fontes autorizadas.

Desenvolvimento e testes

cd python-api
python -m venv .venv
# Windows: .venv\\Scripts\\activate
pip install -r requirements-dev.txt
pytest -q

Próximos passos para produção

1. Migrações com Alembic e autenticação na API.
2. Rate limiting, retry com backoff e fila (Redis/Celery).
3. Adaptadores BuiltWith/Wappalyzer, verificação de e-mail e deduplicação por empresa.
4. Painel de revisão ou notificações Slack/Teams/Telegram.
5. Métricas de origem, confiança, aprovação, resposta e opt-out.
6. Testes de prompts com amostra real antes de habilitar envio.