B2B leads API: como integrar dados da Receita Federal ao seu CRM e escalar a prospecção

Uma b2b leads API bem implementada elimina o trabalho manual de copiar CNPJ, validar telefone e importar planilha — ela faz a ponte direta entre a fonte de dados e o CRM, disparando o ciclo de prospecção em segundos. No contexto brasileiro, a fonte mais confiável é a base pública da Receita Federal, que reúne razão social, situação cadastral, CNAE principal, endereço e contato de milhões de empresas ativas. Quando essa base é consultada via API com filtros inteligentes, você para de gastar horas em pesquisa e começa a gastar tempo fechando negócio.

Este guia explica, de ponta a ponta, como uma b2b leads API funciona na prática: autenticação, parâmetros de filtro, formato de resposta, mapeamento de campos para ferramentas como GoHighLevel, HubSpot ou Pipedrive, e os erros mais comuns que travam a integração antes de a campanha sequer começar. Se você usa o LeadFrio — plataforma que expõe dados públicos da Receita Federal com filtros de CNAE, cidade, UF, data de abertura e flag MEI —, vai encontrar exemplos diretos do endpoint ao campo do CRM.

O que é uma b2b leads API e por que ela importa para prospecção no Brasil

Uma b2b leads API é um endpoint REST (ou GraphQL) que retorna registros de empresas — razão social, CNPJ, segmento, localização, contato — de forma estruturada, sob demanda, sem necessidade de baixar planilhas nem navegar em interfaces. A diferença para o modelo de exportação manual é a latência: enquanto o download de um CSV exige que um humano acesse o painel, configure filtros, clique em exportar e depois importe no CRM, a API pode fazer isso em um job automatizado agendado para toda madrugada, entregando leads frescos ao acordar.

No Brasil, o diferencial competitivo está em consumir dados públicos da Receita Federal de forma normalizada. O Cadastro Nacional de Pessoas Jurídicas (CNPJ) é a maior base estruturada de empresas do país, com abertura de dados regulamentada. Plataformas como o LeadFrio pegam esse repositório bruto, limpam, normalizam e expõem via API com filtros que uma consulta direta ao portal da Receita jamais entregaria — como CNAE secundário, faixa de data de abertura, presença de e-mail comercial e flag MEI.

Para agências, closers e SDRs que prospectam B2B, isso significa abastecer o CRM com listas segmentadas sem depender de terceiros que vendem dados desatualizados ou ilegais. Como os dados são públicos de pessoas jurídicas, a base legal de legítimo interesse prevista na LGPD se aplica de forma clara, reduzindo o risco jurídico da operação de prospecção.

Arquitetura da integração: do endpoint ao CRM em quatro camadas

Antes de escrever uma linha de código ou configurar um Zap, é preciso entender as quatro camadas que compõem qualquer integração de b2b leads API. Elas determinam onde ocorre cada possível ponto de falha e onde você tem flexibilidade para customizar.

A primeira camada é a autenticação. APIs de dados B2B usam, em geral, API Key passada no header (ex.: `Authorization: Bearer <token>`) ou parâmetro de query. Guarde a chave em variável de ambiente — nunca hardcoded no repositório. A segunda camada é a requisição filtrada: você define parâmetros como `cnae=4711301`, `uf=SP`, `municipio=SAO+PAULO`, `data_abertura_de=2020-01-01`, `mei=false` e `situacao=ATIVA`. Quanto mais preciso o filtro, menor o volume e maior a qualidade — regra de ouro da prospecção segmentada.

A terceira camada é o mapeamento de campos: o JSON retornado pela API precisa ser traduzido para os campos do seu CRM. `razao_social` vira `Company Name`, `email` vira `Email`, `telefone` vira `Phone`, `cnpj` vira um campo personalizado de ID externo. Esse mapeamento evita duplicatas e permite enriquecer registros já existentes. A quarta camada é a automação de gatilho: você define se a consulta roda por agendamento (cron job diário), por evento (nova campanha criada no CRM) ou on-demand via botão.

Exemplo de requisição e resposta com dados da Receita Federal

Uma chamada típica à API do LeadFrio para buscar clínicas odontológicas ativas em Curitiba (CNAE 8630-5/04) ficaria assim: `GET /v1/leads?cnae=8630504&municipio=CURITIBA&uf=PR&situacao=ATIVA&mei=false&page=1&limit=50`. O retorno é um array de objetos JSON com campos como `cnpj`, `razao_social`, `nome_fantasia`, `email`, `telefone`, `logradouro`, `bairro`, `cep`, `data_abertura`, `mei` (boolean) e `cnae_descricao`. Esse payload está pronto para ser consumido por um script Python, um workflow no n8n ou uma automação nativa no GoHighLevel via webhook.

O campo `mei` é especialmente útil para quem precisa segmentar oferta: uma agência que vende plano de marketing para pequenos negócios quer MEIs; uma empresa de software de gestão pode querer excluí-los e focar em EPP ou ME com mais de dois anos de cadastro. Esse filtro — impossível de fazer em uma planilha genérica — é o tipo de precisão que uma b2b leads API bem projetada entrega de forma nativa.

Passo a passo: integrando a b2b leads API ao GoHighLevel

O GoHighLevel (GHL) é o CRM mais usado por agências de marketing no Brasil e tem suporte nativo a webhooks e à API própria, o que facilita a integração com fontes externas de leads. O fluxo descrito abaixo usa o LeadFrio como fonte e o GHL como destino, mas a lógica se aplica a qualquer CRM com endpoint de criação de contatos.

Passo 1 — Gere sua API Key no painel do LeadFrio e copie também a chave de API do GoHighLevel (Settings > API Keys). Passo 2 — Escolha a ferramenta de middleware: n8n (self-hosted ou cloud), Make (Integromat) ou Zapier são as opções mais comuns. Para volumes altos, prefira n8n pela ausência de limite de operações por plano. Passo 3 — Crie um workflow com nó HTTP Request apontando para o endpoint do LeadFrio com seus filtros. Configure paginação automática para varrer todas as páginas do resultado.

Passo 4 — Adicione um nó de deduplicação: verifique se o CNPJ já existe como campo personalizado no GHL antes de criar o contato. Isso evita duplicatas que poluem o pipeline. Passo 5 — Mapeie os campos: `email → Email`, `telefone → Phone`, `razao_social → Company Name`, `cnpj → Custom Field: CNPJ`, `mei → Tag: MEI` (ou uma tag automática). Passo 6 — Atribua o lead a um pipeline e stage específicos (ex.: pipeline 'Prospecção Fria', stage 'Novo Lead API'). Passo 7 — Agende o workflow para rodar diariamente às 6h e defina um limite máximo de novos registros por ciclo para não saturar a equipe de SDRs.

Integrando via exportação CSV/Excel quando a API não está disponível

Para quem ainda não tem acesso à API ou quer testar a qualidade dos dados antes de automatizar, o LeadFrio oferece exportação direta em CSV e Excel com os mesmos filtros da API: CNAE, cidade, UF, faixa de data de abertura e flag MEI. O arquivo exportado já vem com colunas nomeadas de forma compatível com o template de importação do GoHighLevel e do HubSpot, reduzindo o trabalho de mapeamento manual.

O fluxo manual funciona bem para campanhas pontuais ou listas menores: aplique os filtros no painel, visualize uma amostra dos registros para confirmar a qualidade, exporte e importe direto no CRM. Quando o volume crescer ou a frequência aumentar, migre para a integração via API para eliminar o gargalo humano. Essa transição progressiva reduz o risco de configuração errada em produção.

Filtros que fazem a diferença: CNAE, cidade, MEI e data de abertura

A qualidade de uma b2b leads API não está apenas na velocidade de resposta, mas na granularidade dos filtros disponíveis. Filtrar só por cidade ou só por segmento gera listas amplas demais; a combinação de múltiplos parâmetros é o que transforma volume em relevância. O CNAE (Classificação Nacional de Atividades Econômicas) é o filtro mais poderoso: ele define com precisão o que a empresa faz, seja no nível de divisão (ex.: 47 = Comércio varejista) ou no nível de subclasse (ex.: 4711-3/01 = Comércio varejista de mercadorias em geral, com predominância de produtos alimentícios — hipermercados).

A combinação CNAE + UF + municípío cria listas hiper-locais, ideais para vendedores externos ou franquias com território definido. Por exemplo: uma fintech de antecipação de recebíveis quer prospectar restaurantes (CNAE 5611-2/01) abertos há menos de três anos em capitais do Nordeste — quatro filtros combinados que, em uma busca manual, exigiriam horas de trabalho e entregariam dados sujos. Via API do LeadFrio, essa query retorna em segundos com e-mail e telefone já incluídos.

A flag MEI merece atenção especial. Microempreendedores Individuais representam parcela enorme da base da Receita, mas muitas ofertas B2B (softwares de gestão, seguros empresariais, consultorias) têm ticket e perfil incompatíveis com MEI. Filtrar `mei=false` já limpa boa parte do ruído. Por outro lado, quem vende para MEIs — conta digital, maquininha, plano de saúde empresarial acessível — pode usar `mei=true` e criar uma segmentação exclusiva. Esse nível de controle, somado ao filtro de `situacao=ATIVA`, garante que você não desperdice crédito de e-mail ou tempo de SDR em empresas baixadas ou inaptas.

LGPD, legítimo interesse e boas práticas de uso da API

Um ponto que trava muitas equipes é a dúvida sobre a legalidade de consumir e usar dados de empresas via API. A resposta é direta: dados de pessoas jurídicas constantes em cadastros públicos — como o CNPJ na Receita Federal — não são dados pessoais no sentido estrito da LGPD, que foca em pessoas naturais. O CNPJ, razão social, endereço comercial e contato comercial de uma empresa são informações públicas, e sua utilização para prospecção B2B se enquadra na base legal de legítimo interesse (Art. 7º, IX da Lei 13.709/2018), desde que o tratamento seja proporcional e o contato, transparente.

Isso não significa vale-tudo. Boas práticas exigem: (1) sempre respeitar pedidos de descadastro e não recontatar empresas que solicitaram opt-out; (2) usar o dado para a finalidade declarada — prospecção comercial — e não revender ou compartilhar com terceiros sem consentimento; (3) manter um registro mínimo de onde os dados foram obtidos (ex.: 'fonte: Receita Federal via LeadFrio, data da extração: 2025-06-01') para auditorias internas. Esse registro também facilita a resposta a eventuais questionamentos dos contatos abordados.

Plataformas como o LeadFrio operam exatamente dentro desse marco: expõem apenas dados públicos de PJ, não armazenam dados de pessoas físicas e não oferecem informações que não estejam no registro público do CNPJ. Isso protege o fornecedor e o usuário da API. Antes de integrar qualquer fonte de dados B2B, verifique se ela declara claramente a origem dos dados e se há política de privacidade e DPA (Data Processing Agreement) disponíveis.

Erros comuns na integração de b2b leads API e como evitá-los

O erro mais frequente é consumir a API sem paginação. A maioria dos endpoints retorna entre 50 e 200 registros por página; se o seu script faz apenas uma chamada e para, você captura só a primeira página e perde o restante da lista. Implemente loop de paginação verificando o campo `total_pages` ou `has_next_page` no payload de resposta antes de encerrar o job.

O segundo erro é não tratar falhas de rede. APIs externas caem, têm timeout ou retornam erro 429 (rate limit). Sem retry com backoff exponencial, um erro pontual interrompe o job inteiro e você começa o dia sem novos leads no CRM. Implemente tentativas automáticas com espera progressiva (1s, 2s, 4s) e alertas por e-mail ou Slack quando o job falhar três vezes seguidas.

O terceiro erro é importar contatos sem verificar duplicatas. Rodar o job diariamente sem checar se o CNPJ já existe no CRM resulta em duplicação de registros, sequências de e-mail disparadas duas vezes para o mesmo contato e relatórios de pipeline corrompidos. Use o CNPJ como chave de deduplicação — ele é único e imutável, diferente de e-mail ou razão social, que podem mudar. O quarto erro, menos técnico mas igualmente destrutivo, é importar volume sem capacidade de trabalhar o lead: mil novos contatos no CRM sem SDR para cadenciar são só custo de armazenamento. Calibre o volume diário importado pela capacidade real de contato da equipe.

Checklist de validação antes de ir para produção

Antes de ativar o job em produção, valide: (1) autenticação funcionando com token de produção, não de sandbox; (2) paginação testada com query que retorna mais de uma página; (3) deduplicação ativa com CNPJ como chave; (4) campos obrigatórios do CRM mapeados e preenchidos (pelo menos nome, empresa e um canal de contato); (5) tratamento de erro com retry e alerta configurado; (6) limite diário de importação definido e documentado; (7) tag de origem ('LeadFrio API') aplicada a todos os leads para rastreamento de ROI por fonte.

Esse checklist de sete pontos resolve mais de 90% dos problemas que equipes relatam nas primeiras semanas de integração. Rode o job em ambiente de staging com um subconjunto pequeno de dados (ex.: 20 registros) antes de escalar para o volume real. O custo de corrigir dados duplicados ou mal mapeados em produção é sempre maior do que o tempo gasto em testes.

Perguntas frequentes

Pronto para prospectar com dados reais? Acesse o LeadFrio.