Guia Rápido

O objetivo deste guia é endereçar de maneira sucinta os recursos de nossa API, permitindo que você comece a realizar consultas em poucos minutos.

Neste documento, abordaremos apenas os principais aspectos da API, sem nos aprofundarmos nos detalhes do significado de cada campo retornado.

Para um detalhamento completo, por favor, acesse a Referência da API

Autenticação

Ao fazer uma consulta, é obrigatório incluir uma Chave de API na propriedade Authorization dos cabeçalhos.

Essa chave é gerada automaticamente ao se registrar em nossa plataforma, e consiste em uma sequência de 73 caracteres usada para identificar seu usuário.

Para visualizar ou criar sua chave gratuitamente, acesse a página Chave de API

Caso já esteja autenticado na plataforma, por conveniência, os exemplos presentes neste guia irão automaticamente incluir sua Chave de API ao serem copiados.

A ausência de uma chave válida resultará em um erro na resposta da API, conforme exemplificado abaixo:

json

{
  "code": 401,
  "message": "invalid authentication"
}

Limites de Utilização

Os limites de utilização da API são definidos por dois fatores: Créditos, que são consumidos ao realizar consultas online, e Taxa por Minuto, que restringe a quantidade de consultas que podem ser efetuadas em um minuto.

Para maiores informações sobre os limites de uso, por favor, consulte a página de Créditos e Limites

Caso haja insuficiência de créditos, a consulta retornará um erro:

json

{
  "code": 429,
  "message": "not enough credits",
  "required": 10,
  "remaining": 7
}

O mesmo ocorre ao exceder o limite estabelecido por minuto:

json

{
  "code": 429,
  "message": "rate limit exceeded"
}

Receita Federal

Esta consulta fornece informações cadastrais do estabelecimento, incluindo situação da inscrição, endereço, contatos, atividades econômicas e quadro societário.

Utilizaremos nosso CNPJ como exemplo, porém, sinta-se livre para substituí-lo por qualquer outro de sua escolha:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/37335118000180' \
  --header 'Authorization: [chave-de-api]'

Após a conclusão bem-sucedida, o JSON de retorno apresentará todos os dados relevantes do estabelecimento:

json

{
  "updated": "2021-07-17T14:46:27Z",
  "taxId": "37335118000180",
  "alias": "CNPJA",
  "founded": "2020-06-05",
  "head": true,
  "company": {
    "id": 37335118,
    "name": "CNPJA TECNOLOGIA LTDA",
    "equity": 1000,
    // Demais informações da empresa...
  },
  // Demais informações do estabelecimento...
}

Simples Nacional

A consulta à Receita Federal disponibiliza os dados cadastrais, no entanto não inclui informações sobre a opção pelo regime tributário do Simples Nacional ou o enquadramento no MEI (Microempreendedor Individual).

Isso ocorre porque a obtenção dessas informações é realizada a partir de fontes distintas, o que implica custos adicionais de automação em nossa plataforma. Consequentemente, isso resulta em um maior consumo de créditos ao efetuar essas operações.

Para acessar os dados do Simples Nacional, refaça a consulta anterior, acrescentando o parâmetro simples=true:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/37335118000180?simples=true' \
  --header 'Authorization: [chave-de-api]'

Note que as informações do Simples Nacional são incorporadas nos objetos simples e simei, aninhados sob company:

json

{
  "updated": "2021-07-17T14:46:27Z",
  "taxId": "37335118000180",
  "alias": "CNPJA",
  "founded": "2020-06-05",
  "head": true,
  "company": {
    "id": 37335118,
    "name": "CNPJA TECNOLOGIA LTDA",
    "equity": 1000,
    // Informações do Simples e SIMEI:
    "simples": {
      "optant": true,
      "since": "2020-06-05"
    },
    "simei": {
      "optant": false,
      "since": null
    },
    // Demais informações da empresa...
  },
  // Demais informações do estabelecimento...
}

Cadastro de Contribuintes

Outra informação amplamente utilizada são Inscrições Estaduais, obtidas através do Cadastro Centralizado de Contribuinte (CCC), que está sujeito a cobranças adicionais similares às do regime Simples Nacional.

Para acessar os números, unidades federativas, tipos e situações cadastrais de todas as Inscrições Estaduais, inclua o parâmetro registrations=BR em sua consulta.

Se desejar restringir a consulta a unidades federativas específicas, substitua o valor BR pelas respectivas siglas, separadas por vírgulas, por exemplo: registrations=PR,RS,SC.

No exemplo a seguir, utilizaremos o CNPJ 04.337.168/0001-48 para consultar todas as Inscrições Estaduais:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/04337168000148?registrations=BR' \
  --header 'Authorization: [chave-de-api]'

As informações obtidas serão exibidas na lista registrations:

json

{
  "updated": "2021-07-17T14:46:27Z",
  "taxId": "04337168000148",
  "alias": "MOTO HONDA",
  "founded": "1975-07-05",
  "head": true,
  "company": {
    "id": 4337168,
    "name": "MOTO HONDA DA AMAZONIA LTDA",
    "equity": 1466281857,
    // Demais informações da empresa...
  },
  "registrations": [
    {
      "number": "91010453",
      "state": "RJ",
      "enabled": true,
      "statusDate": "2005-02-25",
      "status": {
        "id": 1,
        "text": "Sem restrição"
      },
      "type": {
        "id": 2,
        "text": "IE Substituto Tributário"
      }
    },
    {
      "number": "063002280",
      "state": "AM",
      "enabled": false,
      "statusDate": "2017-05-20",
      "status": {
        "id": 1,
        "text": "Sem restrição"
      },
      "type": {
        "id": 1,
        "text": "IE Normal"
      }
    },
    {
      "number": "9000000390",
      "state": "RS",
      "enabled": true,
      "statusDate": "2021-01-21",
      "status": {
        "id": 2,
        "text": "Bloqueado como Destinatário na UF"
      },
      "type": {
        "id": 2,
        "text": "IE Substituto Tributário"
      }
    },
    {
      "state": "SE",
      "number": "270850953",
      "enabled": true,
      "statusDate": "2022-04-22",
      "status": {
        "id": 3,
        "text": "Vedada operação como Destinatário na UF"
      },
      "type": {
        "id": 2,
        "text": "IE Substituto Tributário"
      }
    }
  ],
  // Demais informações do estabelecimento...
}

Comprovantes

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

Receita Federal

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/rfb/certificate?taxId=37335118000180&pages=REGISTRATION' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_rfb.pdf"

Sócios (QSA)

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/rfb/certificate?taxId=37335118000180&pages=MEMBERS' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_qsa.pdf"

Simples Nacional

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/simples/certificate?taxId=37335118000180' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_simples.pdf"

SUFRAMA

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/suframa/certificate?taxId=04337168000148' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_suframa.pdf"

Geocodificação

A geocodificação é o processo de converter endereços em coordenadas geográficas (latitude e longitude), que podem ser utilizadas para posicionar esses locais em um mapa ou realizar análises espaciais.

É possível calcular a geolocalização de um estabelecimento acrescentando o parâmetro geocoding=true:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/37335118000180?geocoding=true' \
  --header 'Authorization: [chave-de-api]'

O resultado conterá as propriedades latitude e longitude junto ao objeto address:

json

{
  "updated": "2021-07-17T14:46:27Z",
  "taxId": "37335118000180",
  "alias": "CNPJA",
  "founded": "2020-06-05",
  "head": true,
  "company": {
    "id": 37335118,
    "name": "CNPJA TECNOLOGIA LTDA",
    "equity": 1000,
    // Demais informações da empresa...
  },
  "address": {
    "latitude": -23.5774994,
    "longitude": -46.6864608,
    "municipality": 3550308,
    "street": "Avenida Brig Faria Lima",
    "number": "2369",
    "details": "Conj 1102",
    "district": "Jardim Paulistano",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01452922",
    "country": {
      "id": 76,
      "name": "Brasil"
    }
  }
  // Demais informações do estabelecimento...
}

Mapa Aéreo

O mapa aéreo permite visualizar terrenos, estradas, edifícios e outros recursos geográficos ao redor de um estabelecimento:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/37335118000180/map' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_mapa_aereo.png"

A consulta retornará uma imagem em formato PNG:

Visão da Rua

A visão da rua possibilita a visualização da aparência externa do estabelecimento e seus arredores:

cURL

PowerShell

bash

curl \
  --request GET \
  --url 'https://api.cnpja.com/office/37335118000180/street' \
  --header 'Authorization: [chave-de-api]' \
  --output "$HOME/Downloads/cnpja_visao_da_rua.png"

A consulta retornará uma imagem em formato PNG:

Estratégias de Cache

Em nossa plataforma, os usuários têm a opção de acessar informações em tempo real ou aquelas previamente armazenadas em nosso banco de dados.

O objetivo dessa funcionalidade é minimizar o consumo de créditos e o tempo de resposta de forma eficaz, sem prejudicar a fidelidade de sua aplicação.

Nos serviços suportados, o controle de cache é gerenciado por meio dos parâmetros de consulta: strategy, maxAge e maxStale.

É possível consultar os serviços suportados na página Créditos e Limites

O parâmetro strategy, define a estratégia de aquisição dos dados, com as seguintes opções disponíveis:

CACHE_IF_FRESH (padrão): Retorna os dados do cache respeitando o limite de tempo definido em maxAge. Se os dados estiverem desatualizados, a consulta será realizada online.
CACHE_IF_ERROR: Funciona como o CACHE_IF_FRESH, mas se a consulta online falhar, retorna os dados do cache desde que estejam dentro do limite estabelecido por maxStale.
CACHE: Entrega os dados mais recentes do cache, evitando consultas online e cobranças de créditos. Se os dados não estiverem disponíveis, resultará em um erro 404.
ONLINE: Realiza a consulta diretamente na fonte online, ignorando o cache. Geralmente não recomendado devido ao alto consumo de créditos que pode lhe ocasionar em uma falha de sua rotina. Sugerimos configurar maxAge=1 como alternativa.

O parâmetro maxAge, controla o limite máximo de tempo, em dias, que um dado em cache é aceite pela sua aplicação antes de ser considerado desatualizado. Por padrão será adotado 45 dias.

O mesmo pode ser usado em conjunto com as estratégias CACHE_IF_FRESH ou CACHE_IF_ERROR.

Por fim, o parâmetro maxStale, controla o limite máximo de tempo, em dias, que um dado em cache é aceite pela sua aplicação se a consulta online falhar.

Tem efeito apenas com a estratégia CACHE_IF_ERROR e considera também o valor de maxAge. Exemplos:

maxAge=7&maxStale=30: Retorna dados do cache se mais recentes que 7 dias, caso contrário, tenta a consulta online. Se houver uma falha, retorna do cache se mais recente que 30 dias.
maxAge=60&maxStale=365: Retorna dados do cache se mais recentes que 60 dias, caso contrário, tenta a consulta online. Se houver uma falha, retorna do cache se mais recente que 365 dias.

Ao utilizar a estratégia CACHE_IF_ERROR, em caso de falha durante a consulta online, se os dados no cache estiverem dentro do intervalo permitido por maxStale, a consulta será considerada bem-sucedida e a propriedade stale será adicionada ao retorno:

json

{
  "stale": true,
  // Demais dados da consulta...
}