Como Transformei um Extrator de Emails em um Pipeline Industrial de Prospecção B2B

A maioria dos projetos começa simples.

Um script.
Um CSV.
Algumas requisições HTTP.

Mas quando a necessidade deixa de ser pontual e passa a ser estratégica, o script precisa evoluir.

Foi exatamente isso que aconteceu quando um extrator básico de e-mails se transformou em um pipeline industrial de prospecção B2B, com controle de estado, versionamento por execução, logs estruturados, processamento incremental e hardening de qualidade de dados.

Neste artigo explico a arquitetura, as decisões técnicas e os princípios de engenharia que guiaram essa evolução.

O problema: scripts não escalam

Um extrator simples resolve:

• Ler uma lista de domínios

• Fazer crawl

• Buscar padrões de e-mail

• Gerar um CSV

Mas ele não resolve:

• Reprocessamento inteligente

• Controle de concorrência

• Auditoria de execução

• Versionamento de base

• Reprodutibilidade

• Governança técnica

• Controle de custo de API

Ou seja: funciona como ferramenta, mas não como sistema.

Quando o processo passou a rodar por segmentos empresariais e integrar enriquecimento via Google Maps API, ficou claro que era necessário estruturar uma engine com mentalidade de produto.

Arquitetura do pipeline

O sistema foi dividido em duas camadas principais.

Camada de consolidação e segmentação

Arquivo principal: linkedin_processor.py

Responsável por:

• Consolidar bases (Connections + Imported Contacts)

• Deduplicar por URL

• Classificar empresas por segmento empresarial

• Gerar CSVs segmentados

• Controlar execução por run

• Aplicar controle incremental por hash

Essa camada organiza e prepara os dados antes da extração.

Engine de extração

Responsável por:

• Enriquecimento via Google Maps API

• Filtragem por confidence_score

• Geração de root_domain

• Deduplicação por domínio raiz

• Crawl multi-thread controlado

• Extração de e-mails

• Consolidação final por segmento

A separação permite escalar cada camada de forma independente.

Controle industrial implementado

A transformação mais relevante não foi o crawler.

Foi o controle.

Lock de execução

Um arquivo .pipeline.lock impede execução simultânea.

Isso evita:

• Corrupção de CSV

• Concorrência acidental

• Duplicidade de processamento

• Estado inconsistente

Run-based architecture

Cada execução cria um diretório estruturado:

linkedin_processed/runs/YYYY-MM-DD_HH-MM-SS

linkedin_processed/runs/YYYY-MM-DD_HH-MM-SS

linkedin_processed/runs/YYYY-MM-DD_HH-MM-SS

Dentro dele:

• Snapshot dos CSV de entrada

• Logs da execução

• Hash dos arquivos processados

• Relatório consolidado da run

Isso torna o pipeline:

• Auditável

• Reproduzível

• Versionado implicitamente

• Rastreável

🔑 Hash de integridade (SHA256)

Cada CSV recebe um hash SHA256.

O sistema compara hashes para:

• Detectar alterações reais

• Processar apenas segmentos modificados

• Evitar retrabalho desnecessário

• Reduzir uso de API externa

Em bases com milhares de registros, essa decisão tem impacto financeiro direto.

Processamento incremental

Se um segmento não sofreu alteração de hash, ele simplesmente não é reprocessado.

Isso reduz:

• Uso de Google Maps API

• Tempo de execução

• Risco de bloqueio

• Custo operacional

• Consumo desnecessário de threads

Essa é uma das decisões arquiteturais mais estratégicas do projeto.

Enriquecimento com Google Maps API

O enriquecimento resolve problemas comuns de dados B2B:

• Empresas sem website no LinkedIn

• Domínios inconsistentes

• Correção de nomes

• Classificação por confiança

• Validação prévia antes do crawl

O pipeline filtra por confidence_score >= 0.65, gera root_domain e elimina redundâncias antes de iniciar a extração.

Esse pré-processamento aumenta significativamente a eficiência do sistema.

Crawl multi-thread com controle

A extração roda com:

• ThreadPoolExecutor controlado

• Retry automático

• Backoff de conexão

• Timeout configurável

• Filtro de domínios inválidos

• Remoção de subdomínios técnicos

Erros como:

• Connection reset by peer

• Max retries exceeded

São tratados como eventos operacionais esperados, não como falhas estruturais.

O objetivo não é agressividade. É estabilidade.

🔒 Hardening de qualidade da extração (v4.2.0)

Uma evolução importante foi o reforço da qualidade da extração de e-mails.

PDFs frequentemente geram ruído estrutural como:

• a@b.c

• sg.@n..

• tokens quebrados com múltiplos @

A engine agora implementa:

• Regex restritiva com validação mínima de TLD (>= 2 caracteres)

• Validação mínima da local-part

• Bloqueio de múltiplos @

• Filtro contra domínios malformados

• Sanitização obrigatória

• Rejeição de padrões inválidos

A decisão foi estratégica:

É preferível reduzir volume do que comprometer qualidade.

Em prospecção B2B, qualidade de dado é ativo financeiro.

CLI flags e flexibilidade operacional

O pipeline aceita flags como:

• --dry-run

• --no-enrich

• --only-segment ONG

• --resume

• --skip-processed

Isso permite:

• Testar execução sem rodar extração real

• Processar apenas um segmento específico

• Ignorar enriquecimento

• Retomar execução interrompida

• Pular segmentos já processados

Flexibilidade sem alterar código.

O que mudou na prática?

Antes:
Um script que gerava um CSV.

Agora:
Um sistema com:

• Versionamento implícito por run

• Controle de integridade por hash

• Processamento incremental

• Arquitetura modular

• Logs estruturados

• Hardening de qualidade de dados

• Governança técnica

A diferença não está apenas no código.

Está na mentalidade de engenharia.

Próximos passos

As próximas evoluções previstas incluem:

• Persistência de estado em SQLite

• API interna REST

• Cache inteligente de enriquecimento

• Dashboard de priorização comercial

• Integração com CRM

• Camada adicional de validação (MX / SMTP)

A base arquitetural já está preparada para escalar.

Conclusão

Transformar scripts em sistemas é uma mudança de postura.

Quando você adiciona:

• Controle de execução

• Integridade de dados

• Segmentação estratégica

• Arquitetura modular

• Hardening de qualidade

• Governança técnica

Você deixa de ter automação pontual e passa a ter infraestrutura.

Esse projeto começou como um extrator.

Hoje ele é uma engine industrial de prospecção B2B.

E essa mentalidade de engenharia aplicada a marketing, dados e tecnologia é parte do que estrutura os projetos desenvolvidos na Ad Rock.