API de CNPJ — Documentação REST

A API CNPJ Aberto expõe, em formato REST, a mesma base que alimenta o site — derivada dos arquivos públicos publicados mensalmente pela Receita Federal. Todos os endpoints retornam JSON, aceitam CORS e usam HTTPS obrigatório. A autenticação é feita pelo header X-API-Key; você pode gerar e rotacionar a sua chave na seção acima.

O que a API cobre. Consulta direta por CNPJ (matriz e filiais, com quadro societário e CNAEs secundários), busca avançada com filtros de UF, CNAE, situação cadastral e faixa de capital, listagem por município e bairro, resolução de sócios por nome com filtro por CPF parcial para reduzir homônimos, detecção de sócios em comum entre dois CNPJs, estatísticas agregadas por CNAE e análise de concorrentes de uma empresa. Usuários do plano Pro desbloqueiam endpoints completos de rede societária, Raio-X de pessoa, geração de leads e listagem por cidade em volume (a navegação no site oferece prévia dessas ferramentas na conta gratuita).

Limites (rate limiting). O plano gratuito permite 1.000 requisições por dia e cobre os endpoints básicos. O plano Pro eleva o teto para 10.000 requisições diárias e habilita os endpoints Pro. Códigos de resposta HTTP seguem o padrão REST: 200 para sucesso, 400 para parâmetros inválidos, 401 para chave ausente ou inválida, 404 para CNPJ não encontrado e 429 quando o limite diário é atingido.

Boas práticas. Faça cache no lado do cliente — a base muda uma vez por mês; retries com backoff exponencial em 5xx e 429; e utilize paginação nos endpoints de listagem (parâmetros page e per_page). Para ingestão em massa, combine a API com a Consulta em Lote: envie a planilha e baixe o resultado sem esbarrar em limites.