API Comercial

Nossa API Comercial de consulta CNPJ oferece acesso em tempo real aos serviços da Receita Federal, Simples Nacional, Cadastro Centralizado de Contribuintes (CCC), SINTEGRA e SUFRAMA. Por meio dela, você obtém dados completos sobre empresas e estabelecimentos, situação cadastral, endereço, e-mails, telefones, atividades econômicas, quadro societário, regime tributário, inscrições estaduais, incentivos fiscais, entre outros.

Além das consultas individuais, a API oferece pesquisa avançada de estabelecimentos e sócios, listas de CNPJs com exportação em massa, emissão de comprovantes em PDF, geolocalização, imagens de mapa aéreo e visão da rua, consulta de CEP e acompanhamento de saldo.

Este guia apresenta de forma objetiva todos os recursos disponíveis, permitindo que você realize suas primeiras consultas em poucos minutos. Para a descrição completa de cada parâmetro e campo retornado, consulte a Referência da API .

Visão Geral

Todas as requisições são feitas para o endereço https://api.cnpja.com e retornam JSON, exceto os comprovantes (PDF) e as imagens (PNG).

Os exemplos deste guia estão disponíveis em cURL, PowerShell e JavaScript. Neste último, utilizamos nosso SDK oficial, que pode ser instalado com npm install @cnpja/sdk.

Recursos Disponíveis

Estabelecimentos

• GET /office/:taxId: Consulta CNPJ centralizada, com dados de diversas fontes.
• GET /office: Pesquisa de estabelecimentos por filtros.
• GET /office/:taxId/map: Imagem do mapa aéreo.
• GET /office/:taxId/street: Imagem da visão da rua.

Empresas e Pessoas

• GET /company/:companyId: Empresa com todos os sócios e estabelecimentos.
• GET /person/:personId: Pessoa com todas as sociedades das quais participa.
• GET /person: Pesquisa de sócios e representantes por filtros.

Consultas por Fonte e Comprovantes

• GET /rfb e GET /rfb/certificate: Receita Federal.
• GET /simples e GET /simples/certificate: Simples Nacional e MEI.
• GET /ccc e GET /ccc/certificate: Cadastro de Contribuintes.
• GET /suframa e GET /suframa/certificate: SUFRAMA.

Listas de CNPJ

• POST /list e GET /list: Criação e pesquisa de listas.
• GET, PATCH e DELETE /list/:listId: Consulta, atualização e remoção de uma lista.
• POST /list/:listId/export: Exportação em massa para Excel e JSON.
• GET /list/:listId/export e GET /list/:listId/export/:exportId: Histórico e acompanhamento das exportações.

Utilitários

• GET /zip/:code: Consulta de CEP.
• GET /credit: Consulta de saldo.

Autenticação

Para efetuar uma consulta, é obrigatório incluir sua Chave de API no cabeçalho Authorization. Essa chave é gerada automaticamente ao se registrar em nossa plataforma e consiste em uma sequência de 73 caracteres.

A ausência de uma chave válida resultará em erro na resposta da API:

Para visualizar sua chave, acesse a página de Chave de API .

Créditos e Limites

O uso de nossa API é controlado por dois fatores:

• Créditos: Consumidos conforme o recurso utilizado, com o custo de cada um indicado ao longo deste guia. Nas consultas com cache configurável, apenas as realizadas online são cobradas, enquanto as pesquisas e exportações de listas são cobradas pela quantidade de registros.
• Limite de Uso: Taxa por minuto que você pode realizar consultas.

Quando os créditos são insuficientes, a resposta é:

Ao exceder a quantidade permitida de consultas por minuto, você receberá:

Os créditos e limite de uso estão vinculados ao plano contratado. Para mais detalhes, visite a página de Planos .

Consulta de Saldo

Para acompanhar seus créditos de forma automatizada, utilize o endpoint /credit. Esta consulta não consome créditos.

O retorno separa os créditos acumulados de meses anteriores (perpetual) dos créditos do mês atual (transient):

Custo da Requisição

Por padrão, a compensação dos créditos ocorre de forma assíncrona. Nas consultas que suportam o parâmetro sync, ao informar sync=true a API aguarda a compensação antes de responder e inclui o cabeçalho cnpja-request-cost na resposta, permitindo identificar o custo de cada requisição.

Este parâmetro está disponível na Consulta CNPJ e nas consultas por fonte da Receita Federal, Simples Nacional, Cadastro de Contribuintes e SUFRAMA.

Códigos de Erro

Todos os erros são retornados em JSON contendo o código HTTP em code e uma descrição em message:

• 400: Parâmetro mal formatado ou faltante, com detalhes em constraints.
• 401: Chave de API ausente ou incorreta.
• 404: Entidade pesquisada não registrada no órgão, ou ausente do cache ao utilizar strategy=CACHE.
• 429: Créditos esgotados ou limite por minuto excedido.
• 500: Erro interno ou falha inesperada.
• 503: Consulta online temporariamente indisponível na fonte de origem.

Exemplo de erro de validação:

O SDK em JavaScript realiza automaticamente até 3 novas tentativas em caso de erros 429 e 5xx.

Consulta CNPJ

A Consulta CNPJ, realizada pelo endpoint GET /office/:taxId, reúne em uma única requisição os dados de diversas fontes sobre um estabelecimento. Por padrão, retorna os dados cadastrais da Receita Federal, como situação da inscrição, endereço, contatos, atividades econômicas e quadro societário.

• Custo: 1 crédito por consulta online, sem custo quando atendida pelo cache, acrescido dos parâmetros adicionais escolhidos.
• Cache: O uso de dados em cache pode ser controlado pelos parâmetros strategy, maxAge e maxStale, descritos na seção Estratégias de Cache.

Exemplo de consulta usando nosso CNPJ de teste 37335118000180:

Retorno (JSON simplificado):

Parâmetros Adicionais

Informações de outras fontes podem ser incluídas na mesma requisição através dos parâmetros abaixo, que podem ser combinados livremente:

• simples=true: Opção pelo Simples Nacional e enquadramento no MEI (+1 crédito).
• simplesHistory=true: Histórico de períodos anteriores do Simples e MEI, e eventos do regime regular do IBS e da CBS, em conjunto com simples=true (+1 crédito).
• registrations: Inscrições estaduais das UFs selecionadas (+1 crédito via CCC, ou +1 crédito por UF via SINTEGRA).
• suframa=true: Inscrição na SUFRAMA e incentivos fiscais (+1 crédito).
• geocoding=true: Latitude e longitude do endereço (+1 crédito).
• links: Links públicos para visualização de comprovantes e imagens.

Exemplo combinando Simples Nacional, inscrições estaduais e geocodificação:

Simples Nacional e MEI

Com simples=true, as informações de opção pelo Simples Nacional e enquadramento no MEI são adicionadas em company.simples e company.simei. Inclua também simplesHistory=true para obter o histórico de períodos anteriores em company.simples.history e company.simei.history, além dos eventos do regime regular do IBS e da CBS em company.simples.events:

Inscrições Estaduais

O parâmetro registrations adiciona as inscrições estaduais do estabelecimento para as UFs informadas, separadas por vírgula, como em registrations=PR,RS,SC. Também são aceitos os termos especiais ORIGIN, para a mesma UF do endereço do estabelecimento, e ALL, para todas as UFs.

A fonte de dados é definida pelo parâmetro registrationsSource:

• AUTO (padrão): Atualmente equivalente a CCC, sujeito a alterações no futuro caso credenciais sejam necessárias.
• CCC: Utiliza o Cadastro Centralizado de Contribuintes para leitura de todas as inscrições, com custo de 1 crédito, independentemente da quantidade de UFs.
• SINTEGRA: Utiliza individualmente o SINTEGRA de cada estado, com custo de 1 crédito por UF consultada.

As inscrições são retornadas em registrations:

Inscrição na SUFRAMA

A Superintendência da Zona Franca de Manaus (SUFRAMA) viabiliza a consulta dos projetos associados ao CNPJ, além dos incentivos fiscais concedidos. Com suframa=true, essas informações são adicionadas em suframa:

Geocodificação

Com geocoding=true, as coordenadas de latitude e longitude são adicionadas ao endereço, permitindo exibir o estabelecimento em um mapa ou realizar análises espaciais:

Links para Arquivos

O parâmetro links adiciona URLs públicas para visualização de comprovantes e imagens do estabelecimento, que podem ser compartilhadas ou exibidas em sua aplicação sem expor sua chave de API. Informe os tipos desejados separados por vírgula:

• RFB_CERTIFICATE: Comprovante da Receita Federal.
• SIMPLES_CERTIFICATE: Comprovante do Simples Nacional.
• CCC_CERTIFICATE: Comprovante do Cadastro de Contribuintes.
• SUFRAMA_CERTIFICATE: Comprovante da SUFRAMA.
• OFFICE_MAP: Mapa aéreo.
• OFFICE_STREET: Visão da rua.

Exemplo de retorno com links=RFB_CERTIFICATE:

Consultas por Fonte

Caso precise apenas das informações de uma fonte específica, utilize as consultas por fonte. Assim como a Consulta CNPJ, elas custam 1 crédito por consulta online, não têm custo quando atendidas pelo cache e suportam os parâmetros strategy, maxAge, maxStale e sync.

Receita Federal

Retorna os dados cadastrais do estabelecimento, atividades econômicas e quadro de sócios e administradores. Diferentemente da Consulta CNPJ, os dados da empresa são retornados no mesmo nível do estabelecimento:

Retorno (JSON simplificado):

Simples Nacional

Retorna a opção pelo Simples Nacional e o enquadramento no MEI. Ao incluir history=true (+1 crédito), também são retornados o histórico de períodos anteriores e os eventos do regime regular do IBS e da CBS:

Retorno (exemplo ilustrativo):

Cadastro de Contribuintes

Retorna as inscrições estaduais e suas situações cadastrais nas UFs informadas em states, que aceita os mesmos termos especiais ORIGIN e ALL. Além do CNPJ de um estabelecimento, é possível consultar o CPF de um produtor rural, informando a UF exata. A fonte de dados pode ser escolhida pelo parâmetro source, com as mesmas opções de registrationsSource da Consulta CNPJ:

Retorno (JSON simplificado):

SUFRAMA

Retorna os dados cadastrais na SUFRAMA, situação do projeto, atividades econômicas e incentivos fiscais. Aceita tanto CNPJ quanto CPF:

Retorno (JSON simplificado):

Comprovantes

Oferecemos comprovantes de inscrição em PDF, emitidos em tempo real no momento da sua solicitação. Cada emissão custa 1 crédito.

Exemplo de emissão do comprovante da Receita Federal:

Todos os comprovantes seguem o mesmo formato, variando apenas o endpoint e os parâmetros:

• Receita Federal (GET /rfb/certificate?taxId=37335118000180&pages=REGISTRATION,MEMBERS): O parâmetro pages define as páginas incluídas, sendo REGISTRATION o comprovante de inscrição e MEMBERS o quadro de sócios e administradores. Por padrão, ambas são incluídas.
• Simples Nacional (GET /simples/certificate?taxId=37335118000180): Comprovante de opção pelo Simples Nacional e enquadramento no MEI.
• Cadastro de Contribuintes (GET /ccc/certificate?taxId=04337168000148&state=AM): O parâmetro state indica a UF de origem, obrigatória para o CPF de produtor rural.
• SUFRAMA (GET /suframa/certificate?taxId=04337168000148): Comprovante de inscrição, aceitando CNPJ ou CPF.

No SDK em JavaScript, utilize os métodos rfb.certificate(), simples.certificate(), ccc.certificate() e suframa.certificate().

Mapa Aéreo

Para visualizar a localização do estabelecimento de forma aérea, use o endpoint /office/:taxId/map. A resposta será uma imagem PNG do local e custa 3 créditos:

A imagem pode ser personalizada pelos parâmetros:

• width e height: Largura e altura em pixels, entre 80 e 640 (padrão 640).
• scale: Multiplicador de densidade de pixels, 1 ou 2 (padrão 1).
• zoom: Nível de ampliação, entre 1 e 20 (padrão 17).
• type: Tipo do mapa, sendo roadmap (padrão), terrain, satellite ou hybrid.

O arquivo resultante será um PNG:

Visão da Rua

A visão da rua permite observar o exterior do estabelecimento e seus arredores. Para isso, utilize o endpoint /office/:taxId/street, que custa 10 créditos:

A imagem pode ser personalizada pelos parâmetros:

• width e height: Largura e altura em pixels, entre 80 e 640 (padrão 640).
• fov: Campo de visão em graus, entre 60 e 120 (padrão 90).

O arquivo resultante será um PNG:

Pesquisa CNPJ

A pesquisa permite encontrar estabelecimentos a partir de filtros, sendo ideal para prospecção e segmentação de mercado. Os dados são obtidos de nossa base previamente armazenada, e o custo é de 1 crédito a cada 10 registros retornados.

Exemplo de pesquisa por estabelecimentos ativos no estado de São Paulo, com atividade principal de tratamento de dados e que possuam e-mail:

Filtros

Os filtros são compostos pelo nome do campo seguido de um operador:

• .in e .nin: Valores a serem incluídos ou excluídos. Valores separados por vírgula correspondem a registros diferentes, enquanto termos separados por espaço devem corresponder ao mesmo registro.
• .gte e .lte: Maior ou igual, e menor ou igual, para datas, valores e intervalos.
• .eq: Igualdade para indicadores, como head.eq=true para apenas matrizes.
• .ex: Existência do campo, como phones.ex=true para apenas estabelecimentos com telefone.

Os principais grupos de filtros disponíveis são:

• Nomes: Razão social e nome fantasia (names), apenas razão social (company.name) ou apenas nome fantasia (alias).
• Empresa: Capital social, natureza jurídica, porte, e opção e data de inclusão no Simples Nacional e no MEI.
• Situação: Data de abertura, matriz ou filial, situação cadastral, motivo e situação especial.
• Endereço: Município IBGE, logradouro, número, complemento, bairro, UF, CEP e país.
• Contatos: Existência, tipo, DDD e número de telefone, e existência, tipo de propriedade, endereço e domínio de e-mail.
• Atividades: Atividades econômicas principais, secundárias ou ambas.
• Listas: Exclusão dos CNPJs pertencentes a listas, informando seus identificadores em taxId.nin.

A relação completa de filtros está disponível na Referência da API .

Paginação

As pesquisas são paginadas, com até 1.000 registros por página definidos pelo parâmetro limit (padrão 10). A resposta contém a quantidade de registros disponíveis em count e o token da próxima página em next:

Para obter a página seguinte, envie apenas o token recebido, sem repetir os demais filtros, como em GET /office?token=8d47bdcbde4a7a2d4a98d5f555a19701. O SDK em JavaScript realiza essa navegação automaticamente ao percorrer o resultado com for await. Como cada página consome créditos, os exemplos interrompem o laço com break após a primeira página.

O mesmo modelo de paginação é utilizado na pesquisa de pessoas, de listas e de exportações.

Empresas

A consulta de empresas retorna os dados da empresa a partir dos oito primeiros dígitos do CNPJ, incluindo todos os sócios e estabelecimentos. Os dados são obtidos de nossa base previamente armazenada e não há consumo de créditos:

Retorno (JSON simplificado):

Pessoas

Cada sócio ou representante legal mapeado em nossa plataforma possui um código único, disponível em person.id no quadro societário das consultas de CNPJ e de empresas.

Consulta Pessoa

Retorna os dados de uma pessoa e todos os quadros societários dos quais faz parte, sem consumo de créditos:

Retorno (JSON simplificado):

O tipo da pessoa é indicado em type, podendo ser NATURAL (pessoa física), LEGAL (pessoa jurídica), FOREIGN (residente no exterior) ou UNKNOWN (desconhecida). Por questões de privacidade, o CPF é retornado de forma parcial.

Pesquisa Pessoas

Encontra pessoas a partir de filtros como tipo (type.in), nome (name.in e name.nin), CPF ou CNPJ (taxId.in), faixa etária (age.in) e país (country.id.in e country.id.nin), utilizando os mesmos operadores da Pesquisa CNPJ. Na pesquisa por CPF, a correspondência é feita pelos dígitos entre o quarto e o nono, uma vez que não armazenamos CPFs completos. O custo é de 1 crédito a cada 10 registros retornados, e a paginação segue o mesmo modelo da Pesquisa CNPJ:

Códigos Postais

A consulta de CEP retorna o endereço correspondente, incluindo o código do município no IBGE, sem consumo de créditos:

Retorno:

Listas de CNPJ

As listas permitem centralizar múltiplos CNPJs em uma única estrutura, viabilizando consultas em lote e o download dos dados em Excel ou JSON. Após criadas, as listas podem ser exportadas quantas vezes forem necessárias, mantendo os dados sempre atualizados.

Criação e Gerenciamento

Uma lista pode ser criada de duas formas, mutuamente exclusivas:

• items: Informando diretamente os números dos CNPJs.
• query: Informando filtros no mesmo formato da Pesquisa CNPJ, limitados pela quantidade definida em limit. Os CNPJs são obtidos na primeira exportação e armazenados de forma estática, com custo de 1 crédito a cada 10 registros.

Cada lista comporta até 1 milhão de CNPJs, e cada conta pode possuir até mil listas, que podem ser gerenciadas pelos endpoints:

• POST /list: Cria uma lista.
• GET /list: Pesquisa listas por título ou descrição através do parâmetro search.
• GET /list/:listId: Consulta uma lista.
• PATCH /list/:listId: Atualiza o título, a descrição ou os CNPJs de uma lista.
• DELETE /list/:listId: Remove uma lista.

Exportação

A exportação consulta todos os estabelecimentos da lista e gera os arquivos para download. Em options, é possível informar os mesmos parâmetros adicionais da Consulta CNPJ, exceto links, além dos parâmetros de estratégia de cache. O custo é de 1 crédito a cada 100 registros, acrescido dos parâmetros adicionais escolhidos.

Exemplo de criação de uma lista, solicitação da exportação e acompanhamento do seu andamento:

O andamento é indicado em status: a exportação começa em PENDING, aguardando na fila, pois apenas uma lista é processada por vez, passa por PROCESSING, PROCESSED e EXPORTING, e termina em COMPLETED, ou em FAILED com o motivo descrito em statusReason. Ao concluir, os arquivos ficam disponíveis em links:

O histórico de exportações de uma lista pode ser consultado em GET /list/:listId/export.

Estratégias de Cache

Muitos recursos da nossa API podem ser consultados em tempo real ou aproveitando dados armazenados em nosso cache. Isso ajuda a reduzir o consumo de créditos e melhorar o tempo de resposta, sem comprometer a qualidade das informações em sua aplicação.

A principal finalidade do cache é evitar solicitações online desnecessárias. Se os dados encontrados em nossa base ainda forem considerados atualizados, sua aplicação pode usá-los de imediato. Isso diminui custos e latência, especialmente em aplicações que realizam consultas recorrentes aos mesmos CNPJs.

Entretanto, caso as informações em cache estejam muito antigas, a API pode efetuar uma consulta em tempo real (online) para garantir que você disponha de dados recentes. Além disso, quando há falhas na consulta online, é possível retornar dados antigos, caso estejam dentro de um prazo de aceitação definido, mantendo a operação da aplicação.

Recursos Suportados

• Cache configurável: Consulta CNPJ, consultas por fonte da Receita Federal, Simples Nacional, Cadastro de Contribuintes e SUFRAMA, e opções de exportação de listas.
• Sempre em cache: Consultas de empresas, pessoas e CEPs, sem consumo de créditos, e pesquisas, cobradas pela quantidade de registros retornados. Esses dados são atualizados periodicamente pela plataforma.
• Sempre online: Comprovantes, mapa aéreo e visão da rua.

Configuração

O parâmetro strategy define a forma como a API decide entre usar dados em cache ou realizar uma consulta online. As opções disponíveis são:

• CACHE: Entrega somente dados em cache. Se não houver dados armazenados em nossa base, a API retorna erro 404. Não há cobrança de créditos, pois nenhuma consulta online é executada.
• CACHE_IF_FRESH: Retorna dados do cache caso estejam dentro do período de atualização definido por maxAge. Se o cache estiver vencido, faz uma nova consulta online, resultando em consumo de créditos.
• CACHE_IF_ERROR (padrão): Comporta-se como CACHE_IF_FRESH, mas se ocorrer uma falha na consulta online, retornará dados do cache (mesmo que expirados para maxAge) se ainda estiverem dentro do prazo de maxStale.
• ONLINE: Faz a consulta diretamente na fonte, sem usar cache. Geralmente não recomendado por consumir mais créditos. Em situações em que você precise de dados atualíssimos, pode substituir essa abordagem por CACHE_IF_FRESH com maxAge=1, obtendo dados praticamente em tempo real, mas ainda com algum grau de proteção contra falhas.

Defasagem Máxima

O parâmetro maxAge define, em dias, o prazo máximo de validade dos dados em cache antes de serem considerados desatualizados. Se o cache exceder esse período, a API tenta realizar uma consulta online.

• Padrão: 45 dias, podendo variar entre 1 e 3650.
• É usado junto das estratégias CACHE_IF_FRESH e CACHE_IF_ERROR.

Defasagem Máxima para Falhas

O parâmetro maxStale determina, em dias, a idade máxima que os dados em cache ainda podem ter para serem retornados caso a consulta online falhe.

• Padrão: 365 dias, podendo variar entre 1 e 3650.
• Só tem efeito com a estratégia CACHE_IF_ERROR.
• Ao usar maxStale, se o cache estiver antigo, mas dentro do período definido, a API ainda retorna esses dados se ocorrer erro online. Nesse caso, a resposta conterá "stale": true.

Exemplos Práticos

• strategy=CACHE: A API retornará dados somente se houver cache, independentemente da sua idade. Se não houver dados em cache, retorna 404. Não há consumo de créditos.
• strategy=CACHE_IF_FRESH&maxAge=7: Retorna imediatamente se o cache tiver até 7 dias. Caso contrário, tentará obter dados online, consumindo créditos.
• strategy=CACHE_IF_ERROR&maxAge=7&maxStale=30: Retorna cache se tiver até 7 dias. Se for mais antigo, faz consulta online. Em caso de falha online, retorna cache de até 30 dias e adiciona "stale": true no JSON.
• strategy=ONLINE: Ignora o cache e sempre faz consulta online (alto consumo de créditos). Como alternativa, poderia usar strategy=CACHE_IF_FRESH&maxAge=1 para ter dados praticamente em tempo real, mas sem desperdiçar créditos caso exista um cache muito recente (inferior a 1 dia).

Observações

• A opção ONLINE pode aumentar custos, pois cada tentativa faz uma requisição na fonte oficial.
• Em situações de alta criticidade ou em que as informações precisam ser atualizadas com mais frequência, valores menores de maxAge podem ser configurados, mas atente-se ao impacto nos seus créditos.
• Para saber quais serviços suportam cache, consulte a página de Contratação .

Consulta Descontinuada

O endpoint GET /companies/:taxId corresponde à versão anterior da Consulta CNPJ. Ele permanece acessível para não impactar integrações existentes, mas não recebe mais atualizações ou suporte técnico ativo. Recomendamos a migração para GET /office/:taxId, considerando as seguintes equivalências:

• company_max_age corresponde a maxAge.
• enable_cache_fallback corresponde à estratégia CACHE_IF_ERROR.
• simples_max_age corresponde a simples=true.
• sintegra_max_age corresponde a registrations.
• Os campos files e maps da resposta correspondem ao parâmetro links, com os tipos RFB_CERTIFICATE, OFFICE_MAP e OFFICE_STREET.

Considerações Finais

Com este guia, você deve estar apto a utilizar todos os recursos da API em poucos minutos, aproveitando informações cadastrais, tributárias, societárias, geográficas e visuais para apoiar suas decisões e fluxos de negócio.

Para continuar, recomendamos:

• Referência da API : Descrição completa de cada endpoint, parâmetro e campo retornado.
• Teste Online : Teste as consultas diretamente pelo navegador.
• Postman : Coleção pronta para importar e experimentar a API.
• Status da API : Disponibilidade das fontes de dados em tempo real.

Em caso de dúvidas ou dificuldades, estamos à disposição para ajudar!