GET /v1/cnpjs

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

Respostas

200 OK

Página de resultados.

{
  "data": [
    {
      "cnpj": "00000000669822",
      "raiz_cnpj": "00000000",
      "razao_social": "BANCO DO BRASIL SA",
      "nome_fantasia": "TIRADENTES / BNC (SP)",
      "matriz_filial": {
        "codigo": "2",
        "descricao": "Filial"
      },
      "n_filiais": 0,
      "data_inicio_atividade": "2009-04-16",
      "situacao_cadastral": {
        "codigo": "02",
        "descricao": "Ativa"
      },
      "data_situacao_cadastral": "2009-04-16",
      "motivo_situacao_cadastral": {
        "codigo": "00",
        "descricao": "Sem motivo"
      },
      "situacao_especial": null,
      "data_situacao_especial": null,
      "natureza_juridica": {
        "codigo": "2038",
        "descricao": "Sociedade de Economia Mista"
      },
      "porte": {
        "codigo": "05",
        "descricao": "Demais"
      },
      "capital_social": 120000000000,
      "cnae_fiscal": {
        "codigo": "6422100",
        "descricao": "Bancos múltiplos, com carteira comercial"
      },
      "cnaes_secundarios": [
        {
          "codigo": "6499999",
          "descricao": "Outras atividades de serviços financeiros não especificadas anteriormente"
        }
      ],
      "endereco": {
        "tipo_logradouro": "AVENIDA",
        "logradouro": "TIRADENTES",
        "numero": "451",
        "complemento": null,
        "bairro": "Luz",
        "cep": "01101010",
        "municipio": "São Paulo",
        "codigo_municipio_ibge": "3550308",
        "codigo_municipio_siafi": "7107",
        "uf": "SP"
      },
      "simples": {
        "optante": false,
        "data_opcao": "2007-07-01",
        "data_exclusao": "2007-07-01"
      },
      "mei": {
        "optante": false,
        "data_opcao": "2009-07-01",
        "data_exclusao": "2009-07-01"
      },
      "has_email": false,
      "has_website": false,
      "has_phone": false,
      "has_mobile_phone": false
    }
  ],
  "meta": {
    "request_id": "req_01J8ZK3Q9X",
    "source": "rfb_open_data+oportunidados",
    "data_as_of": "2026-09-01",
    "credits_charged": 1,
    "credits_remaining": 59,
    "credits_reset_at": "2026-10-01T00:00:00-03:00",
    "page_size": 1,
    "next_cursor": null,
    "total_count_capped": "1"
  }
}

400 Requisição inválida

Filtro desconhecido ou valor fora do enum, cursor inválido, ou nenhum filtro além de cursor. explicacao é ignorada e não conta como filtro.

{
  "error": {
    "code": "invalid_filter",
    "message": "Um ou mais parâmetros da requisição são inválidos. Consulte a documentação.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_filter"
  }
}

401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API ausente ou inválida.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_api_key"
  }
}

402 Pagamento necessário

Franquia e pacotes esgotados. Header X-Credits-Reset.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Créditos insuficientes para esta operação. Aguarde a renovação ou adquira mais créditos.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#quota_exceeded"
  }
}

403 Proibido

insufficient_plan (operação fora do plano), filter_not_in_plan (filtro acima do nível do plano) ou payment_required (cobrança recusada há mais de 7 dias). Com a busca globalmente fechada, o mesmo insufficient_plan usa a mensagem de liberação gradual.

{
  "error": {
    "code": "insufficient_plan",
    "message": "Seu plano não inclui esta operação. Troque de plano para continuar.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#insufficient_plan"
  }
}

404 Não encontrado

API desligada (CNPJIA_API_ENABLED diferente de on).

{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#not_found"
  }
}

429 Excesso de requisições

Requisições por minuto da conta excedidas. Header Retry-After. Sem X-RateLimit-* quando o limite atingido é o de requisições sem chave por IP.

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições excedido. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#rate_limited"
  }
}

500 Erro interno

Erro interno, inclusive timeout da busca. retryable: true; a operação não é cobrada. Se houve liquidação, o estorno é tentado e pode ficar pendente de retentativa ou recuperação manual. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "internal_error",
    "message": "Erro interno. Tente novamente; se persistir, fale com o suporte.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#internal_error"
  }
}

503 Serviço indisponível

Janela mensal de atualização da base. Header Retry-After.

{
  "error": {
    "code": "maintenance",
    "message": "A base está em manutenção. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#maintenance"
  }
}

504 Tempo esgotado

Timeout de consulta. retryable: true; nada é cobrado. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "upstream_timeout",
    "message": "A operação demorou mais que o esperado. Tente novamente.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#upstream_timeout"
  }
}

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?uf=PR" \
  -H "Authorization: Bearer $CNPJIA_KEY"