Buscar empresas

GET/v1/buscarX-Api-Key

Busca estabelecimentos por nome, atividade, CNPJ ou CNAE, com filtros estruturados. Somente estabelecimentos com situação cadastral ativa (02) entram no resultado; para consultar um CNPJ em qualquer situação, use /v1/empresas/{cnpj}. Informe q, cnae ou os dois. Um CNPJ completo em q faz busca exata (modo cnpj); palavras usam busca textual em português sobre razão social, nome fantasia e descrição do CNAE (modo texto); quando nenhuma empresa corresponde ao texto, a busca tenta semelhança de grafia na razão social (modo fuzzy). meta.modo_busca informa o modo aplicado. O total exato é opcional (incluir_total) porque custa uma contagem completa. Cada item traz telefone e e-mail cadastrais; com tem_telefone e tem_email, uma página de até 100 contatos custa uma chamada. Toda busca é planejada antes de rodar, e meta.plano diz se ela é uma varredura ampla da base. Sem cnae, uma varredura ampla pede confirmação explícita (409 busca_ampla_requer_confirmacao). Com q e sem cnae, meta.cnaes_sugeridos traz os códigos CNAE das palavras de q (os mesmos de /v1/cnaes): filtrar por eles é a forma indexada, e rápida, de buscar uma atividade.

Parâmetros

qstring · query
Nome, razão social, atividade ou CNPJ. Obrigatório se cnae não for informado.
Ao menos 2 caracteres.
ufstring · query
Sigla da UF do estabelecimento.
Até 2 caracteres.
municipiostring · query
Nome do município, sem diferenciar maiúsculas nem acentos (sao paulo equivale a São Paulo); hífens e apóstrofos contam. Envie também uf: sem ela, municípios homônimos de outras UFs entram no resultado. Nome desconhecido ou fora da UF informada devolve 422 com sugestões.
cnaestring · query
Código CNAE principal, ou até 10 códigos separados por vírgula (uma categoria de /v1/cnaes pode ter vários). Com sete dígitos busca o código exato; com menos, filtra pelo prefixo. Pontos, hífens e barras são ignorados (4721-1/02).
somente_matrizboolean · query
Exclui filiais.
Padrão: false.
ordenar_porstring · query
Valores: relevancia, nome, municipio, uf, capital_social, data_inicio_atividade, cnae. Padrão: "relevancia".
ordemstring · query
Valores: asc, desc. Padrão: "desc".
portestring · query
Códigos de porte da RFB separados por vírgula: 00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais.
capital_minnumber · query
Capital social mínimo em reais.
Mínimo 0.
capital_maxnumber · query
Capital social máximo em reais; não pode ser menor que capital_min.
Mínimo 0.
data_inicio_destring (date) · query
Início de atividade a partir desta data (AAAA-MM-DD).
data_inicio_atestring (date) · query
Início de atividade até esta data (AAAA-MM-DD).
tem_emailboolean · query
true exige e-mail cadastrado; false exige ausência.
tem_telefoneboolean · query
true exige telefone cadastrado; false exige ausência.
simplesstring · query
Opção pelo Simples Nacional.
Valores: S, N.
meistring · query
Opção pelo MEI.
Valores: S, N.
incluir_totalboolean · query
Calcula o total exato de resultados; sem ele, total vem null.
Padrão: false.
confirmar_varreduraboolean · query
Confirma uma busca ampla recusada com 409 e amplia o tempo limite de 12 para 60 segundos.
Padrão: false.
limitinteger · query
Entre 1 e 100. Padrão: 20.
offsetinteger · query
Deslocamento da página. Prefira refinar filtros a paginar fundo.
Mínimo 0. Padrão: 0.

Resposta

Página de resultados.

totalinteger | null
Total exato quando incluir_total=true; caso contrário null.
limitinteger
offsetinteger
itemsarray de objeto
- cnpjstring
  CNPJ completo com 14 caracteres.
- razao_socialstring | null
- nome_fantasiastring | nullopcional
- municipiostring | null
- ufstring | null
- cnae_principalstring | null
  Código CNAE de sete dígitos.
- cnae_principal_descstring | nullopcional
- portestring | null
  00 não informado, 01 microempresa, 03 empresa de pequeno porte, 05 demais.
- situacao_cadastralstring | null
  Sempre 02 (ativa) nesta rota.
- opcao_simplesstring | null
  S ou N.
- matriz_filialstring | null
  1 matriz, 2 filial.
- telefonestring | null
  DDD e número do primeiro telefone cadastral, sem formatação; vazio quando ausente.
- emailstring | null
  E-mail cadastral declarado à RFB.
- scorenumber
  Relevância relativa dentro desta busca; não compare entre buscas.
has_moreboolean
Indica que há ao menos mais um resultado após esta página.
metaobjeto
- fontearray de string
- competenciastring | nullopcional
- snapshot_idstring | nullopcional
- total_calculadoboolean
  Indica se total foi calculado (incluir_total=true).
- modo_buscastring
  Estratégia aplicada: CNPJ exato, texto, semelhança de grafia ou somente CNAE. Valores: cnpj, texto, fuzzy, cnae.
- planoobjetoopcional
  Estimativa do PostgreSQL (EXPLAIN) para a busca, calculada em toda busca. varredura_ampla diz se a leitura mais cara de empresas_busca atinge limite_custo; sem cnae (exige_confirmacao), essa busca responde 409 até receber confirmar_varredura=true. O custo considera o limit da página quando a leitura para assim que a página enche (um índice percorrido em ordem); ordenações e contagens (incluir_total) leem tudo e contam inteiras.
  - varredura_amplaboolean
  - custo_estimadonumber
    Custo estimado da leitura mais cara de empresas_busca, como ela vai rodar.
  - custo_leitura_completanumber
    Custo da mesma leitura lida até o fim, sem o limit da página; para comparação.
  - linhas_estimadasinteger
    Linhas estimadas nessa leitura.
  - limite_custonumber
  - exige_confirmacaoboolean
    Se a regra de confirmação vale para esta busca (vale sem cnae).
- cnaes_sugeridosarray de objetoopcional
  Com q e sem cnae: os códigos CNAE das palavras de q, como em /v1/cnaes. Vazio para um nome de empresa.
  - rotulostring
    Nome da categoria curada ou descrição oficial da subclasse.
  - codigosarray de string
    Subclasses CNAE 2.3; envie-as em cnae separadas por vírgula.
  - descricoesarray de string
    Descrição oficial de cada código, na mesma ordem.
  - origemstring
    Valores: categoria, ibge.
  - termostringopcional
    Sinônimo ou atividade do IBGE que correspondeu à consulta.
  - notastringopcional
  - aproximadobooleanopcional
    Nenhuma categoria tem todas as palavras; esta tem a palavra da atividade.

Erros

Status	Quando	Código
401	Chave ausente, inválida ou revogada.
409	Busca ampla demais para executar sem confirmação, ou interrompida após 12 segundos. Refine os filtros, de preferência com um dos cnaes_sugeridos, ou repita com confirmar_varredura=true.	`busca_ampla_requer_confirmacao` `busca_demorada`
422	Parâmetro inválido ou município incompatível com a UF.	`municipio_uf_incompativel`
429	Cota diária da chave atingida (1.000 chamadas por padrão). Toda requisição autenticada conta, inclusive as que terminam em erro e as recusadas por cota. A contagem renova na virada do dia da base. A resposta não traz Retry-After.
503	Autenticação indisponível, base indisponível, consulta interrompida pelo tempo limite (consulta_demorada) ou, nas buscas, consultas demais do mesmo tipo em andamento (api_sobrecarregada).	`base_indisponivel` `api_sobrecarregada` `consulta_demorada`
504	Busca confirmada interrompida após 60 segundos.	`busca_demorada`

Formatos de erro em Erros; o que conta na cota em Autenticação e cota.

curl -G https://api.fonteza.com.br/v1/buscar \
  -H "X-Api-Key: $FONTEZA_KEY" \
  --data-urlencode "q=transportadora" \
  --data-urlencode "uf=SP"

import os
import requests

resposta = requests.get(
    "https://api.fonteza.com.br/v1/buscar",
    params={"q": "transportadora", "uf": "SP"},
    headers={"X-Api-Key": os.environ["FONTEZA_KEY"]},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const url = new URL("https://api.fonteza.com.br/v1/buscar");
url.search = new URLSearchParams({ q: "transportadora", uf: "SP" });
const resposta = await fetch(url, {
  headers: { "X-Api-Key": process.env.FONTEZA_KEY },
});
if (!resposta.ok) throw new Error(`${resposta.status}: ${await resposta.text()}`);
const dados = await resposta.json();

Monte esta requisição com seus filtros

Resposta 200

{
  "total": null,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "cnpj": "12345678000190",
      "razao_social": "TRANSPORTADORA EXEMPLO LTDA",
      "nome_fantasia": "EXEMPLO CARGAS",
      "municipio": "CAMPINAS",
      "uf": "SP",
      "cnae_principal": "4930202",
      "cnae_principal_desc": "Transporte rodoviário de carga, exceto produtos perigosos e mudanças, intermunicipal, interestadual e internacional",
      "porte": "03",
      "situacao_cadastral": "02",
      "opcao_simples": "S",
      "matriz_filial": "1",
      "telefone": "1932345678",
      "email": "contato@transportadoraexemplo.com.br",
      "score": 0.83
    }
  ],
  "has_more": false,
  "meta": {
    "fonte": [
      "RFB/DadosAbertos"
    ],
    "competencia": "2026-09",
    "snapshot_id": "rfb-2026-09-3f9c2a7d41b8e605",
    "total_calculado": false,
    "modo_busca": "texto",
    "plano": {
      "varredura_ampla": false,
      "custo_estimado": 1834.2,
      "custo_leitura_completa": 1834.2,
      "linhas_estimadas": 412,
      "limite_custo": 100000,
      "exige_confirmacao": true
    },
    "cnaes_sugeridos": [
      {
        "rotulo": "Caminhoneiros e transportadoras",
        "codigos": [
          "4930201",
          "4930202",
          "4930203"
        ],
        "descricoes": [
          "Transporte rodoviário de carga",
          "exceto produtos perigosos e mudanças",
          "municipal",
          "Transporte rodoviário de carga, exceto produtos perigosos e mudanças, intermunicipal, interestadual e internacional",
          "Transporte rodoviário de produtos perigosos"
        ],
        "origem": "categoria",
        "termo": "transportadora",
        "nota": "Maioria MEI: são sobretudo caminhoneiros autônomos."
      }
    ]
  }
}