API · REST + MCP

Dados cadastrais de empresas do Brasil

Todos os estabelecimentos ativos do país, mais os que mudaram de situação nos 24 meses anteriores ao dump, a partir dos dados abertos do CNPJ da Receita Federal. A base é atualizada em até 24 h após cada publicação mensal, com opção pelo MEI e pelo Simples Nacional.

Somente dados cadastrais. A API informa se a empresa tem e-mail ou telefone no registro (contato.temEmail), nunca os valores, nem nomes de sócios.

1. Chave de acesso

Uma chave por projeto, com escopos (companies:read, stats:read). Projetos da FlukeBase recebem a chave no cofre do projeto como EMPRESASNOBRA_API_KEY. Envie-a assim:

Authorization: Bearer enb_live_…

2. Início rápido

curl -s https://empresasnobra.flukebase.me/api/v1/companies/12.345.678%2F0001-95 \
  -H "Authorization: Bearer $EMPRESASNOBRA_API_KEY" | jq .data

# novos MEIs em SP no último mês, CNAE 8599 (ensino)
curl -s "https://empresasnobra.flukebase.me/api/v1/companies?uf=SP&mei=true&cnae=8599&abertaDesde=2026-09-01&limit=50" \
  -H "Authorization: Bearer $EMPRESASNOBRA_API_KEY"

Respostas de sucesso: { data, meta: { sourceVersion, stale } }. O sourceVersion diz de qual dump da Receita a resposta saiu.

3. Endpoints

Rota	Escopo	O quê
GET /api/v1/companies/{cnpj}	companies:read	Registro de um CNPJ (qualquer formatação, inclusive alfanumérico)
POST /api/v1/companies/batch	companies:read	Até 100 CNPJs; 1 unidade por CNPJ
GET /api/v1/companies	companies:read	Busca com filtros, paginação por cursor
GET /api/v1/companies/count	companies:read	Quantas empresas atendem aos filtros
GET /api/v1/stats/openings	stats:read	Aberturas por dia × UF × seção CNAE
GET /api/v1/reference/{tipo}	companies:read	cnaes, municipios, naturezas, portes, situacoes, secoes
GET /api/v1/meta	companies:read	Dump carregado, idade, cobertura, última atualização
GET /api/v1/openapi.json	—	Contrato OpenAPI 3.1 (público)

4. Filtros de busca

Valem para /companies e /companies/count. O total é exato até 10 mil resultados e estimado acima disso (totalIsEstimate).

q: texto livre na razão social e no nome fantasia
uf: SP,RJ ou uf=SP&uf=RJ
municipio: código IBGE de 7 dígitos (municipioTom: código TOM da Receita)
cnae: prefixo do CNAE principal: 41 (divisão) até 4120400 (subclasse)
natureza: natureza jurídica, ex.: 2135 empresário individual
porte: 00 não informado · 01 ME · 03 EPP · 05 demais
situacao: padrão 02 (ativa) · 03 suspensa · 04 inapta · 08 baixada
mei / simples: true ou false (null = sem registro de opção)
temEmail / temTelefone: tem contato no registro (o valor nunca é retornado)
abertaDesde / abertaAte: data de início de atividade, YYYY-MM-DD
capitalMin / capitalMax: capital social em R$
matriz: somente matrizes
limit / cursor: 1–100 itens; cursor = nextCursor da página anterior

CNPJ alfanumérico: desde julho de 2026 a Receita emite CNPJs com letras (ex.: 12.ABC.345/01DE-35). A API aceita e devolve o formato canônico em maiúsculas, e valida os dígitos verificadores, então um erro de digitação volta como 400.

5. Erros

application/problem+json (RFC 9457) com um code estável:

invalid_request: 400; Entrada inválida: veja detail e issues[]. Parâmetros desconhecidos também são recusados.
unauthorized: 401; Chave ausente, desconhecida ou revogada.
forbidden: 403; A chave não tem o escopo exigido (requiredScope).
not_found: 404; CNPJ fora do registro carregado: baixado há mais de 24 meses ou mais novo que o dump.
rate_limited: 429; Mais requisições por minuto que o limite da chave. Aguarde Retry-After.
quota_exceeded: 429; Cota diária de unidades esgotada; renova às 00:00 UTC.
not_configured: 503; Configuração do servidor: avise o operador.
internal_error: 500; Falha nossa, já registrada. Tente de novo com backoff.

6. Limites

Por chave: 120 requisições por minuto e 50 mil unidades por dia (ajustáveis). Toda resposta traz X-RateLimit-Remaining e X-Quota-Remaining. Requisições recusadas não consomem cota.

7. MCP para agentes

POST https://empresasnobra.flukebase.me/api/mcp (Streamable HTTP), com a mesma chave e os mesmos escopos. São 7 ferramentas equivalentes aos endpoints: empresasnobra_company_lookup, _company_batch, _company_search, _company_count, _openings_stats, _reference, _dataset_meta.

{
  "mcpServers": {
    "empresasnobra": {
      "type": "http",
      "url": "https://empresasnobra.flukebase.me/api/mcp",
      "headers": { "Authorization": "Bearer ${EMPRESASNOBRA_API_KEY}" }
    }
  }
}

8. Atualização e cobertura

A Receita publica os dados abertos do CNPJ uma vez por mês. Uma rotina diária detecta o novo mês, aplica apenas as mudanças e passa por verificações de qualidade antes de publicar. Um mês com dados quebrados é recusado, e o mês anterior continua no ar. Use GET /api/v1/meta para ver qual dump está carregado e quando foi a última atualização.

Fonte: Receita Federal do Brasil, dados abertos do CNPJ. Tratamento conforme a LGPD; nomes e endereços de MEI identificam pessoas físicas, e quem armazena esses dados é controlador da própria cópia.