API de empresas e marcas

A chave

A mesma que abre o conector MCP. Crie a sua no painel, em Conta e Perfil, e guarde na hora: ela aparece uma vez. Guardamos só o resumo criptográfico dela, então não existe “ver de novo”. Perdeu, gera outra e revoga a antiga.

Mande de uma destas três formas, nesta ordem de preferência:

• Authorization: Bearer SUA_CHAVE
• X-API-Key: SUA_CHAVE
• ?chave=SUA_CHAVE na URL, que funciona nas ferramentas de automação que não deixam mandar cabeçalho. O preço é a chave aparecer no registro de qualquer proxy no caminho.

A chave diz quem você é, não o que você pode. O que ela abre é conferido a cada chamada, contra as telas liberadas na sua conta. Perder o acesso a Empresas no painel fecha a API de Empresas no mesmo instante.

Buscar empresas

GET /api/v1/empresas

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://www.b2bfull.com.br/api/v1/empresas?uf=MG&cnae=4711302&com_telefone=1&limite=50"

Pelo menos um filtro é obrigatório além da situação. Sem recorte a consulta varreria 27,8 milhões de linhas e não terminaria a tempo, então ela é recusada antes com erro: filtro_obrigatorio.

• cnae sete dígitos, sem pontuação
• uf sigla do estado
• municipio código do IBGE
• porte 1 micro, 3 pequeno, 5 demais
• situacao 2 ativa (padrão), 3 suspensa, 4 inapta, 8 baixada
• capital_min capital social mínimo em reais
• aberta_ha_dias só quem abriu nos últimos N dias
• com_telefone=1 e com_email=1
• matriz=1 só matrizes
• limite até 500 por página, pagina começando em 0

{
  "pagina": 0,
  "limite": 50,
  "tem_mais": true,
  "empresas": [
    {
      "cnpj": "12345678000190",
      "razao_social": "EXEMPLO COMERCIO LTDA",
      "nome_fantasia": "EXEMPLO",
      "cnae": "4711302",
      "situacao": 2,
      "abertura": "2019-03-14",
      "uf": "MG",
      "municipio": "BELO HORIZONTE",
      "bairro": "CENTRO",
      "telefone": "31 33334444",
      "email": "contato@exemplo.com.br",
      "matriz": true,
      "capital": 100000,
      "porte": 3
    }
  ],
  "fonte": "Receita Federal, dados abertos, carga mensal"
}

tem_mais diz se existe página seguinte, e é mais barato que pedir o total: contar 27,8 milhões de linhas para dizer quantas sobraram custaria mais que a própria busca.

Ficha de um CNPJ, com sócios

GET /api/v1/empresas/{cnpj}

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://www.b2bfull.com.br/api/v1/empresas/12345678000190"

Traz o cadastro e a lista de sócios com qualificação, data de entrada e faixa etária. Use ?socios=0 quando não precisar deles, que a resposta fica mais rápida.

O campo `socios` tem três respostas e elas são diferentes. Ausente quer dizer que você não pediu. null quer dizer que pediu e a leitura falhou, e nesse caso vem socios_indisponivel: true junto. Lista vazia quer dizer que leu e não há sócio. Tratar as três como “sem sócio” é afirmar o que não se sabe.

Marcas de um CNPJ

GET /api/v1/marcas/{cnpj}

Os processos daquele CNPJ no INPI, com situação e data de vigência. É consulta à base pública: não é parecer de viabilidade, e quem decide concessão é o INPI.

Leads de marca

GET /api/v1/leads-marca

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://www.b2bfull.com.br/api/v1/leads-marca?tipo=renovacao&meses=6&uf=SP"

Empresas ativas cruzadas com o INPI, nos dois recortes em que existe um prazo correndo. A lista vem com telefone e e-mail, porque o cruzamento é com a base da Receita.

• tipo=renovacao marca em vigor cuja proteção vence dentro de meses, de 1 a 24
• tipo=travado pedido arquivado ou indeferido nos últimos quatro anos
• uf e cnae para recortar

Limites

• 120 chamadas por minuto
• 20.000 chamadas por dia
• 500 linhas por página

Toda resposta traz X-RateLimit-Remaining e X-RateLimit-Remaining-Day. Ao estourar vem 429 com Retry-After em segundos: respeite o cabeçalho em vez de tentar em laço.

Este teto é de infraestrutura, não é comercial. No painel a pesquisa é ilimitada. Aqui ele existe porque do outro lado de uma API quem chama é um programa, e um programa não cansa.

Erros

• 401 chave ausente, inválida ou revogada. Chave que não existe e chave revogada respondem igual, de propósito.
• 403 a conta existe mas não tem aquela tela liberada. O corpo diz qual.
• 400 parâmetro fora do formato, ou busca sem filtro.
• 404 CNPJ fora da base, ou recurso que não existe.
• 429 limite atingido.
• 503 a base não respondeu. Tente de novo.

Todo erro vem em JSON com erro (um código estável, para o seu programa) e mensagem (para uma pessoa ler). Trate pelo erro, nunca pelo texto.

O que a v1 não faz

• Não escreve nada. Toda a versão 1 é de leitura, e só responde a GET.
• Não devolve faturamento estimado. Empresa fechada não publica faturamento no Brasil. Entregamos capital social e porte, que são oficiais.
• Não devolve contato de pessoa física nem de decisor nominal.

Conector MCP

A mesma chave abre um servidor MCP, para o seu assistente consultar a base em linguagem natural. A URL é https://www.b2bfull.com.br/api/mcp/SUA_CHAVE, e as ferramentas que aparecem são as das telas que a sua conta tem: busca de empresas, ficha com sócios, marcas de um CNPJ e leads de marca.