API Comercial

Nossa API Comercial de consulta CNPJ oferece acesso em tempo real aos serviços da Receita Federal, Simples Nacional, Cadastro de Contribuintes 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, entre outros.

Adicionalmente, há ferramentas avançadas de inteligência de negócios como emissão de comprovantes em PDF, geolocalização precisa e visualização em mapa aéreo e visão da rua.

Este guia descreve de forma objetiva os recursos da API, permitindo que você realize consultas em poucos minutos. Para mais detalhes, consulte a Referência da API .

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 .

Limites de Utilização

O uso de nossa API é controlado por dois fatores:

• Créditos: Consumidos a cada consulta realizada online.
• 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 Contratação .

Receita Federal

Esta consulta retorna dados cadastrais do estabelecimento, como situação da inscrição, endereço, contatos, atividades econômicas e quadro societário.

Exemplo de consulta usando nosso CNPJ de teste 37335118000180:

Retorno (JSON simplificado):

Simples Nacional

A consulta da Receita Federal não inclui informação sobre o regime tributário (Simples Nacional ou MEI), pois esses dados são obtidos de fontes distintas e geram custos adicionais de automação, consumindo mais créditos.

Para incluir informações do Simples Nacional e MEI, basta adicionar ?simples=true:

No retorno, as informações do Simples e do SIMEI aparecem em company.simples e company.simei:

Cadastro de Contribuintes

Para obter Inscrições Estaduais de uma empresa, utilizamos o Cadastro Centralizado de Contribuinte (CCC). Esse serviço também implica custo adicional de créditos.

Basta incluir o parâmetro registrations=BR para buscar inscrições em todas as unidades federativas:

Retorno (exemplo):

Se desejar restringir a consulta a UFs específicas, basta substituir BR por siglas separadas por vírgula, por exemplo: registrations=PR,RS,SC.

SUFRAMA

A Superintendência da Zona Franca de Manaus (SUFRAMA) viabiliza a consulta dos projetos associados ao CNPJ, além dos incentivos fiscais concedidos. Para obter esses dados, basta adicionar suframa=true na sua requisição.

Exemplo de consulta para o CNPJ 04337168000148:

Retorno simplificado:

Comprovantes

Oferecemos diversos comprovantes de inscrição, que são emitidos em tempo real no momento da sua solicitação.

Receita Federal

Sócios (QSA)

Simples Nacional

CCC

SUFRAMA

Geocodificação

Adicione geocoding=true à consulta para obter coordenadas de latitude e longitude, permitindo exibir o estabelecimento em um mapa ou realizar análises espaciais:

Retorno (exemplo):

Mapa Aéreo

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

O arquivo resultante será um PNG:

Visão da Rua

A visão da rua permite observar o exterior do estabelecimento e arredores. Para isso, utilize o endpoint /street:

O arquivo resultante será um PNG:

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.

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
• É usado junto das estratégias CACHE_IF_FRESH e CACHE_IF_ERROR.

Defasagem Máxima para Falhas

O parâmetro maxStale determina, em dias, por quanto tempo após maxAge os dados ainda podem ser retornados caso a consulta online falhe.

• Padrão: 365 dias
• 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. Se não houver dados em cache ou estiverem mais antigos que 15 dias, 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 .

Considerações Finais

Com este guia, você deve estar apto a realizar as principais consultas em poucos minutos, aproveitando informações cadastrais, tributárias, geográficas e visuais para apoiar suas decisões e fluxos de negócio.

Caso necessite de mais detalhes sobre cada campo retornado, consulte a Referência da API .

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