# Guia Rápido

O objetivo deste guia é que entenda de forma objetiva o que faz nossa API e comece em poucos minutos a fazer consultas!

Entretanto abordaremos apenas uma pequena parcela de tudo que ela é capaz, se você gostar do conteúdo recomendamos a leitura da documentação completa.


# Chave de API

Acesse a página de sua conta em nossa plataforma para visualizar sua Chave de API, caso ainda não tenha registro você será guiado no processo de criação:

Minha Conta

Ao registrar-se você estará no plano gratuito que oferece consultas e créditos diários suficientes para completar este guia.

Ao acessar o link acima com sucesso, copie sua chave para utilizar no próximo passo, o formato dela é similar a:

27e4642e-34d1-4ff3-bc26-e34321d96326-fc7abaae-a96c-4e63-b52e-33fb48526dac

# Consulta CNPJ

Escolha um exemplo de requisição abaixo e substitua o termo sua-chave-de-api pelo valor que obteve no passo anterior.

Neste caso iremos usar o nosso CNPJ, mas fique a vontade para alterá-lo a outro de sua preferência!

curl --location --request GET 'https://api.cnpja.com/office/37335118000180' \
--header 'Authorization: sua-chave-de-api'
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "sua-chave-de-api")

$response = Invoke-RestMethod 'https://api.cnpja.com/office/37335118000180' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.cnpja.com/office/37335118000180")
  .method("GET", null)
  .addHeader("Authorization", "sua-chave-de-api")
  .build();
Response response = client.newCall(request).execute();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cnpja.com/office/37335118000180',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: sua-chave-de-api'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://api.cnpja.com/office/37335118000180',
  headers: { 
    'Authorization': 'sua-chave-de-api'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
const settings = {
  "url": "https://api.cnpja.com/office/37335118000180",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "sua-chave-de-api"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
import http.client

conn = http.client.HTTPSConnection("api.cnpja.com")
payload = ''
headers = {
  'Authorization': 'sua-chave-de-api'
}
conn.request("GET", "/office/37335118000180", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Esta consulta irá retornar os dados de um estabelecimento cadastrado na Receita Federal, ao ser concluída com sucesso o JSON de retorno irá iniciar com:

{
  "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...
}

A fim de manter o guia sucinto, não iremos abordar todos os dados aqui, para conhecer detalhadamente cada propriedade do retorno acesse:

Estabelecimentos
/api/data/office/

Guarde o resultado desta e demais consultas no guia, pois ao término explicarmos sobre nosso Cache.


# Simples Nacional

A consulta anterior retornou os dados do cadastro na Receita, entretanto não contém as informações de regime do Simples Nacional e SIMEI.

Isto ocorre pois a aquisição em tempo real destas informações originam de locais diferentes, e estão sujeitas a adicionais custos de automação em nossa plataforma.

Para receber os dados do Simples, repita a consulta anterior adicionando o parâmetro: simples=true.

curl --location --request GET 'https://api.cnpja.com/office/37335118000180?simples=true' \
--header 'Authorization: sua-chave-de-api'
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "sua-chave-de-api")

$response = Invoke-RestMethod 'https://api.cnpja.com/office/37335118000180?simples=true' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.cnpja.com/office/37335118000180?simples=true")
  .method("GET", null)
  .addHeader("Authorization", "sua-chave-de-api")
  .build();
Response response = client.newCall(request).execute();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cnpja.com/office/37335118000180?simples=true',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: sua-chave-de-api'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://api.cnpja.com/office/37335118000180?simples=true',
  headers: { 
    'Authorization': 'sua-chave-de-api'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
const settings = {
  "url": "https://api.cnpja.com/office/37335118000180?simples=true",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "sua-chave-de-api"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
import http.client

conn = http.client.HTTPSConnection("api.cnpja.com")
payload = ''
headers = {
  'Authorization': 'sua-chave-de-api'
}
conn.request("GET", "/office/37335118000180?simples=true", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Observe que novas informações foram adicionadas ao mesmo retorno do exemplo anterior:

{
  "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...
}

# Inscrições Estaduais

Outra informação amplamente utilizada, que se encaixa no mesmo cenário explicado no passo anterior, são as Inscrições Estaduais do estabelecimento.

Para adicioná-las, o processo é similar, adicionando o parâmetro: registrations={UFs}.

Onde UFs deve ser substituído por uma ou mais siglas separadas por vírgula dos estados que deseja consultar as IEs.

Também é possível utilizar o termo BR que indica que deseja as IEs de todas as UFs. A cobrança em créditos é por estado, ao utilizar ester termo o valor será multiplicado por 27.

Neste exemplo utilizaremos o CNPJ 04.337.168/0001-48, e os estados do Acre, Amazonas e Roraima:

curl --location --request GET 'https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR' \
--header 'Authorization: sua-chave-de-api'
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "sua-chave-de-api")

$response = Invoke-RestMethod 'https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR")
  .method("GET", null)
  .addHeader("Authorization", "sua-chave-de-api")
  .build();
Response response = client.newCall(request).execute();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: sua-chave-de-api'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR',
  headers: { 
    'Authorization': 'sua-chave-de-api'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
const settings = {
  "url": "https://api.cnpja.com/office/04337168000148?registrations=AM,AC,RR",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "sua-chave-de-api"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
import http.client

conn = http.client.HTTPSConnection("api.cnpja.com")
payload = ''
headers = {
  'Authorization': 'sua-chave-de-api'
}
conn.request("GET", "/office/04337168000148?registrations=AM,AC,RR", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

O retorno irá conter os detalhes das IEs para os estados escolhidos:

{
  "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": [
    {
      "state": "AC",
      "number": "0100198400108",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "041568176",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "070002207",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "063002280",
      "enabled": false
    },
    {
      "state": "AM",
      "number": "062002562",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "047200243",
      "enabled": false
    },
    {
      "state": "AM",
      "number": "063009382",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "041533704",
      "enabled": true
    },
    {
      "state": "AM",
      "number": "041533704",
      "enabled": true
    },
    {
      "state": "RR",
      "number": "240035786",
      "enabled": true
    }
  ]
  // Demais informações do estabelecimento...
}

# Cache e Online

As consultas anteriores retornaram uma propriedade updated, com estampa de tempo em UTC.
Em comparação com o horário brasileiro este valor é 3 horas a frente, ou seja, no exemplo a seguir:

"updated": "2021-07-17T14:46:27Z"

Significa que os dados foram atualizados 17 de julho de 2021 às 11:56 no Brasil.

Agora, resgate qualquer um dos resultados dos passos anteriores e confira o valor em updated:

Se ele for menor que a data e hora atual

A consulta foi realizada em Cache e não consumiu créditos, apenas contou para sua taxa por minuto.

Se ele for igual a data e hora atual

A consulta foi realizada Online e consumiu tanto seus créditos como contou para sua taxa por minuto.

Por padrão, o máximo valor em updated será uma data até 30 dias atrás. Entretanto, você pode controlar este valor como preferir utilizando o parâmetro de query maxAge=dias.

Para testar este comportamento, faça uma consulta com um CNPJ diferente, e adicione maxAge como 365 (1 ano):

curl --location --request GET 'https://api.cnpja.com/office/seu-cnpj?maxAge=365' \
--header 'Authorization: sua-chave-de-api'
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "sua-chave-de-api")

$response = Invoke-RestMethod 'https://api.cnpja.com/office/seu-cnpj?maxAge=365' -Method 'GET' -Headers $headers
$response | ConvertTo-Json
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.cnpja.com/office/seu-cnpj?maxAge=365")
  .method("GET", null)
  .addHeader("Authorization", "sua-chave-de-api")
  .build();
Response response = client.newCall(request).execute();
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cnpja.com/office/seu-cnpj?maxAge=365',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: sua-chave-de-api'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://api.cnpja.com/office/seu-cnpj?maxAge=365',
  headers: { 
    'Authorization': 'sua-chave-de-api'
  }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
const settings = {
  "url": "https://api.cnpja.com/office/seu-cnpj?maxAge=365",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "sua-chave-de-api"
  },
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
import http.client

conn = http.client.HTTPSConnection("api.cnpja.com")
payload = ''
headers = {
  'Authorization': 'sua-chave-de-api'
}
conn.request("GET", "/office/seu-cnpj?maxAge=365", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Desta forma, há uma alta probabilidade da consulta ser concluída em Cache, ou seja, com updated retroativo. Se isto não ocorrer, escolha outro CNPJ até encontrar um exemplo.

Por fim, realize a mesma consulta trocando maxAge=365 por maxAge=1, você irá observar que o tempo de resposta será maior, porém desta vez a estampa de tempo de retorna será a hora atual e os dados estarão atualizados.

O cenário que testamos é apenas uma amostra de tudo o que o controle de cache é capaz, para conhecer mais a respeito acesse:

Estratégias de Cache
/api/core/cache/


# Próximos Passos

Este guia abordou como obter os dados de cadastro de um CNPJ na Receita Federal, Inscrições Estaduais e regime do Simples Nacional através da rota /office/:taxId.

Se você gosta de documentações (como nós), sugerimos que siga a leitura em ordem e ao término não se esqueça de enviar o seu feedback!

Por outro lado, se tem interesse apenas em um tópico específico, confira esta relação dos tópicos mais populares: