GET /v1/cnpjs

GET /v1/cnpjs lista empresas que atendem a um conjunto de filtros. Cada página traz até 20 empresas no perfil basic e custa 1 crédito por empresa retornada; página vazia custa 0. A paginação é por cursor opaco, com ordenação fixa por CNPJ. A busca exige um plano pago: no Free ela responde 403 insufficient_plan. Ela também exige ao menos um filtro além de cursor.

O que retorna

data é um array de empresas no perfil basic, os mesmos campos da consulta por CNPJ sem contatos e sócios. Para os contatos de uma empresa da lista, faça a consulta individual em full; os sinais has_phone, has_email e has_website já vêm na busca e dizem para quais vale a pena.

meta traz, além dos campos de toda resposta, três específicos da busca:

• next_cursor: o cursor da página seguinte, ou null na última.
• page_size: quantas empresas vieram nesta página. É campo de resposta; não existe parâmetro para pedir páginas maiores.
• total_count_capped: texto com a contagem de empresas que atendem aos filtros. Abaixo do teto de exibição é exata; a partir dele vem com o sufixo + (por exemplo "10000+") e informa um mínimo. null quando não foi calculada. É uma contagem com teto, nunca uma estimativa.

Filtros

Os filtros se combinam com E lógico e ao menos um deles é obrigatório; sem filtro a resposta é 400 invalid_filter. Os parâmetros de código aceitam vários valores separados por vírgula (uf=SP,RJ, cnae=47,6201501): os valores de um mesmo parâmetro se combinam com OU, e municipio_excluir exclui todos os municípios da lista. O limite de valores por parâmetro está na referência gerada; acima dele a resposta é 400 invalid_filter. nome e socio_nome buscam texto contido, sem diferenciar maiúsculas. Não há ordenação escolhida pelo cliente: a ordem é sempre por CNPJ, o que torna a paginação estável.

Cada filtro tem um plano mínimo. Filtro acima do plano da conta responde 403 filter_not_in_plan, sem consulta e sem custo, e a mensagem diz qual plano libera o filtro.

Filtros de sócio respeitam os pedidos de remoção dos titulares: empresa com remoção ativa não aparece nessa busca nem na contagem.

Filtro desconhecido ou valor fora do enum responde 400 invalid_filter sem custo. Na busca, porte e situação são filtrados pelos nomes acima; na resposta, os mesmos campos vêm como código e descrição da Receita Federal, listados em Campos da resposta.

Exemplo de requisição

# padarias ativas em Curitiba (CNAE 1091-1/02), optantes do Simples
curl "https://api.cnpj.ia.br/v1/cnpjs?uf=PR&municipio=4106902&cnae=1091102&situacao=ATIVA&simples=true" \
  -H "Authorization: Bearer $CNPJIA_KEY"

# próxima página
curl "https://api.cnpj.ia.br/v1/cnpjs?uf=PR&municipio=4106902&cnae=1091102&situacao=ATIVA&simples=true&cursor=<meta.next_cursor>" \
  -H "Authorization: Bearer $CNPJIA_KEY"

import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"}
filtros = {"uf": "PR", "municipio": "4106902", "cnae": "1091102", "situacao": "ATIVA", "simples": "true"}

def paginas(filtros: dict):
    cursor = None
    while True:
        params = {**filtros, **({"cursor": cursor} if cursor else {})}
        r = requests.get("https://api.cnpj.ia.br/v1/cnpjs", params=params, headers=HEADERS, timeout=10)
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        cursor = body["meta"].get("next_cursor")
        if not cursor:
            break

for empresa in paginas(filtros):
    print(empresa["cnpj"], empresa["razao_social"])

const headers = { Authorization: `Bearer ${process.env.CNPJIA_KEY}` };
const filtros = { uf: "PR", municipio: "4106902", cnae: "1091102", situacao: "ATIVA", simples: "true" };

async function* paginas(filtros) {
  let cursor;
  do {
    const url = new URL("https://api.cnpj.ia.br/v1/cnpjs");
    Object.entries({ ...filtros, ...(cursor && { cursor }) }).forEach(([k, v]) => url.searchParams.set(k, v));
    const res = await fetch(url, { headers });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const { data, meta } = await res.json();
    yield* data;
    cursor = meta.next_cursor;
  } while (cursor);
}

for await (const e of paginas(filtros)) console.log(e.cnpj, e.razao_social);

Paginação e custo

Repita a chamada com os mesmos filtros, passando em cursor o valor de meta.next_cursor da página anterior, até ele vir null. Mudar um filtro no meio invalida o cursor. Cada página cobra 1 crédito por empresa retornada, então percorrer todas as empresas custa tantos créditos quantas empresas houver; total_count_capped na primeira página dá esse número quando está abaixo do teto, e um mínimo quando vem com +. Quando o saldo da conta não cobre uma página inteira, a página vem menor, com as empresas que o saldo paga, e next_cursor continua apontando para a seguinte.

Erros

Relacionados

• Referência gerada de searchCnpjs.
• Gerar filtro: POST /v1/filters/generate transforma uma descrição em linguagem natural nos filtros desta busca; é a ferramenta gerar_filtro do MCP.
• Créditos, franquia e rate limit.