GET /v1/cnpjs
Buscar empresas por filtros
Página de até 20 empresas com campos basic, ordenação fixa por CNPJ, paginação por cursor. Custa 1 crédito por empresa retornada; página vazia não custa. Não disponível no plano Free.
Créditos
por empresa retornada · 1 crédito página máx. · 20 empresas
Parâmetros
| Nome | Em | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
uf | query | string | — | Sigla da UF. |
municipio | query | string | — | Código IBGE do município (7 dígitos). |
cnae | query | string | — | CNAE fiscal, 7 dígitos ou prefixo (classe, grupo, divisão). |
porte | query | stringenum: ME, EPP, DEMAIS | — | — |
situacao | query | stringenum: ATIVA, SUSPENSA, INAPTA, BAIXADA, NULA | — | — |
simples | query | boolean | — | — |
mei | query | boolean | — | — |
natureza | query | string | — | Código da natureza jurídica. |
capital_min | query | numbermín. 0 | — | — |
capital_max | query | numbermín. 0 | — | — |
abertura_de | query | stringformato: date | — | — |
abertura_ate | query | stringformato: date | — | — |
cursor | query | string | — | Cursor opaco da página anterior (meta.next_cursor). |
Respostas
200 OK
Página de resultados.
| Header | Tipo | Descrição |
|---|---|---|
X-Request-Id | string | Identificador da requisição para suporte. |
X-Credits-Charged | integer | Créditos debitados nesta resposta. |
X-Credits-Remaining | integer | Créditos restantes (franquia + pacotes). |
X-Credits-Reset | stringformato: date-time | Instante do próximo reset da franquia (RFC 3339). |
X-RateLimit-Limit | integer | Requisições por minuto do plano (por conta). |
X-RateLimit-Remaining | integer | Requisições restantes no minuto corrente. |
400 Requisição inválida
Filtro desconhecido ou valor fora do enum.
401 Não autorizado
Chave ausente, desconhecida, revogada ou expirada.
402 Pagamento necessário
Franquia e pacotes esgotados. Header X-Credits-Reset.
403 Proibido
insufficient_plan (operação fora do plano) ou payment_required (cobrança recusada há mais de 7 dias).
429 Excesso de requisições
Requisições por minuto da conta excedidas. Header Retry-After.
| Header | Tipo | Descrição |
|---|---|---|
Retry-After | integer | Só em 429 e 503: segundos até tentar de novo. |
503 Serviço indisponível
Janela mensal de atualização da base. Header Retry-After.
504 Tempo esgotado
Timeout de consulta. retryable: true; nada é cobrado.
Ferramenta MCP
No servidor MCP oficial esta operação é a ferramenta buscar_empresas, com a mesma chave e os mesmos créditos da API.
Exemplo
curl -s "https://api.cnpj.ia.br/v1/cnpjs" \
-H "Authorization: Bearer $CNPJIA_KEY"