# Changelog
Todas as alterações notáveis na API serão documentadas nesta página.
O formato é baseado em [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
e este projeto adere ao [Controle de versão semântica](https://semver.org/spec/v2.0.0.html).
\[Unreleased] [#unreleased]
* Adicionar dados do IBAMA na API Comercial.
* Adicionar latitude e longitude referente ao endereço da empresa.
\_ Adicionar informações referente a dívida ativa com a união.
\[1.0.5] 24/01/2022 [#105-24012022]
Added [#added]
\_ Regimes Tributários
\_ Validação Suframa
\[1.0.4] - 27/12/2021 [#104---27122021]
Added [#added-1]
* Adicionar dados referentes ao Suframa na API Comercial.
\[1.0.3] - 02/10/2021 [#103---02102021]
Changed [#changed]
* Redimensionamento do Banco de Dados
Added [#added-2]
* Endpoint para consulta de consumo de requisições na API
\[1.0.2] - 11/09/2021 [#102---11092021]
Fixed [#fixed]
Correção na grafia das incrições estaduais no JSON
inscricoes\_estatudais -> inscricoes\_estaduais
\[1.0.2] - 15/08/2021 [#102---15082021]
Changed [#changed-1]
O serviço foi dividio em 2 servidores, um para a API Pública e outro para a API Comercial. Agora os respectivos endpoints são as seguintes:
* API Pública: ([https://publica.cnpj.ws](https://publica.cnpj.ws))
* API Comercial: ([https://comercial.cnpj.ws](https://comercial.cnpj.ws))
Até o dia **01/09/2021** o endpoint antigo ([https://data.cnpj.ws](https://data.cnpj.ws)) antigo continuará recebendo requisições, após essa data é necessário migrar para um dos novos endpoints.
\[1.0.1] - 10/08/2021 [#101---10082021]
Fixed [#fixed-1]
* Correção referente as incrições estaduais do estado do Paraná para utilizar o formato do sintegra.
\[1.0.0] - 20/06/2021 [#100---20062021]
Entrada em produção da API
# Visão Geral
[](https://insomnia.rest/run/?label=CNPJ.ws\&uri=https%3A%2F%2Fwww.cnpj.ws%2Finsomnia.json)
A API do **CNPJ.ws** fornece, de maneira simples e rápida, dados sobre empresas brasileiras através do número do CNPJ. Esses dados são obtidos junto a órgãos públicos como a SEFAZ, CADESP, Sintegra, Suframa e são organizados para permitir o máximo de informações úteis, ampliando as possibilidades de uso desses dados.
Estrutura básica do JSON [#estrutura-básica-do-json]
Os dados são estruturados para trazer a maior quantidade de informações úteis, possibilitando a integração com diversos sistemas.
Tipos de dados utilizados:
| Sigla | Descrição |
| :---: | :-------- |
| A | Array |
| S | String |
| D | Data |
| N | Numérico |
| O | Objeto |
Abaixo está a estrutura básica retornada pela API de CNPJ:
| Campo | Tipo | Descrição |
| ----------------------------- | :--: | :------------------------------------------- |
| cnpj\_raiz | S | Raiz do CNPJ |
| razao\_social | S | Razão social da empresa |
| capital\_social | S | Capital social |
| responsavel\_federativo | S | Responsável federativo |
| criado\_em | S | Data do cadastro na base de dados do CNPJ.ws |
| atualizado\_em | S | Data da última atualização das informações |
| porte | O | Porte da empresa |
| natureza\_juridica | O | Natureza jurídica |
| qualificacao\_do\_responsavel | O | Qualificação do responsável |
| socios | O | Lista de Sócios |
| estabelecimento | O | Estabelecimento |
| simples | O | Dados do Simples e do MEI |
Defasagem dos Dados [#defasagem-dos-dados]
A defasagem máxima dos dados é de 45 dias, sendo que diariamente são feitas integrações com os Sintegras estaduais com os quais possuímos integração.
Qualquer dúvida, estamos aqui para te apoiar! Mande um e-mail para [contato@cnpj.ws](mailto:contato@cnpj.ws)!
[](https://www.digitalocean.com/?refcode=58b7deafafad\&utm_campaign=Referral_Invite\&utm_medium=Referral_Program\&utm_source=badge)
# CNPJ Alfanumérico de Teste
Use o CNPJ de exemplo `UKPVME1E8HI996` para testar sua integração com o novo formato
A partir de julho de 2026 a Receita Federal poderá emitir novas inscrições no CNPJ no formato alfanumérico (com letras e números). Os cadastros existentes não serão alterados. Se quiser entender como o novo formato funciona e como calcular os dígitos verificadores, veja o artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
A API do CNPJ.ws já está preparada para o novo formato. Para ajudar quem está adaptando seus sistemas, criamos um **CNPJ alfanumérico de exemplo** que você pode usar para testar sua validação de dígitos verificadores e sua integração com a API antes que as inscrições reais entrem em circulação.
CNPJ de exemplo [#cnpj-de-exemplo]
```
UKPVME1E8HI996
```
Formatado, fica assim:
```
UK.PVM.E1E/8HI9-96
```
Repare na estrutura, que segue o mesmo padrão do CNPJ atual:
| Parte | Valor | Descrição |
| ----- | ---------- | ---------------------------------------------------------- |
| Raiz | `UKPVME1E` | Identifica a empresa (8 caracteres, alfanuméricos) |
| Ordem | `8HI9` | Identifica o estabelecimento (4 caracteres, alfanuméricos) |
| DV | `96` | Dígitos verificadores (2 caracteres, sempre numéricos) |
Os dígitos verificadores `96` foram calculados a partir dos doze primeiros caracteres usando o módulo 11, exatamente como descrito no artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico). Ou seja: é um CNPJ válido do ponto de vista do algoritmo, ideal para validar a sua implementação.
Testando a validação dos dígitos verificadores [#testando-a-validação-dos-dígitos-verificadores]
Se você implementou o cálculo dos DVs no seu sistema, rode o algoritmo sobre os doze primeiros caracteres (`UKPVME1E8HI9`) e confira se o resultado é `96`. Se bater, sua validação está correta.
Para conferir manualmente, basta substituir cada caractere pelo seu valor (ASCII − 48), aplicar os pesos de 2 a 9 da direita para a esquerda e tirar o resto da divisão por 11 — o passo a passo completo está no [artigo do cálculo](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
Testando na API CNPJ.ws [#testando-na-api-cnpjws]
O CNPJ de exemplo pode ser enviado diretamente para a API, **sem caracteres especiais** (sem pontos, barra ou traço).
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/UKPVME1E8HI996`
**Exemplo com cURL**
```shell
curl https://publica.cnpj.ws/cnpj/UKPVME1E8HI996
```
**Exemplo com JavaScript / Node.js**
Usando `fetch`:
```js
async function consultarCNPJ(cnpj) {
const resposta = await fetch(`https://publica.cnpj.ws/cnpj/${cnpj}`);
const dados = await resposta.json();
console.log(dados);
}
consultarCNPJ("UKPVME1E8HI996");
```
**Exemplo com o pacote `consultar-cnpj`**
Também mantemos o pacote oficial [`consultar-cnpj`](https://github.com/cnpj-ws/consultar-cnpj) ([npm](https://www.npmjs.com/package/consultar-cnpj)), que facilita a integração em Node.js. **A partir da versão 1.0.22 ele já aceita CNPJ alfanumérico**, então basta atualizar para a última versão:
```shell
yarn add consultar-cnpj
# ou
npm i consultar-cnpj --save
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
// O token é opcional — sem ele, usa a API Pública (3 consultas/min)
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
const empresa = await consultarCNPJ("UKPVME1E8HI996", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
getCNPJ();
```
> **Importante:** por se tratar de um CNPJ fictício, criado apenas para testes, ele **não retorna dados cadastrais de uma empresa real**. O objetivo é validar que sua aplicação aceita, trata e envia o formato alfanumérico corretamente em toda a cadeia — do formulário até a chamada da API. Para receber dados reais, utilize um CNPJ existente.
# CNPJ Alfanumérico
A partir de julho de 2026 a Receita Federal poderá emitir novas inscrições no CNPJ no formato alfanumérico (com letras e números), os cadastros existentes não serão alterados.
A API do CNPJ.ws já está preparada para esse novo formato e aceita consultas usando CNPJ alfanumérico.
Cálculo dos dígitos verificadores [#cálculo-dos-dígitos-verificadores]
O novo CNPJ alfanumérico é composto por 14 dígitos, como o atual, sendo os doze primeiros alfanuméricos e os dois restante, os dígitos verificadores, numéricos.
Os dígitos verificadores são calculados a partir dos doze primeiros dígitos em duas etapas, utilizando o módulo de divisão 11 e pesos distribuídos de 2 a 9.
Cálculo do primeiro dígito [#cálculo-do-primeiro-dígito--]
Para cada um dos caracteres do CNPJ, você deve atribuir o valor da coluna "Valor para cálculo do DV", conforme a tabela abaixo, ou subtrair 48 do "Valor ASCII":
| CNPJ Alfanumérico | Valor ASCII | Valor para cálculo do DV |
| ----------------- | ----------- | ------------------------ |
| 0 | 48 | 0 |
| 1 | 49 | 1 |
| 2 | 50 | 2 |
| 3 | 51 | 3 |
| 4 | 52 | 4 |
| 5 | 53 | 5 |
| 6 | 54 | 6 |
| 7 | 55 | 7 |
| 8 | 56 | 8 |
| 9 | 57 | 9 |
| A | 65 | 17 |
| B | 66 | 18 |
| C | 67 | 19 |
| D | 68 | 20 |
| E | 69 | 21 |
| F | 70 | 22 |
| G | 71 | 23 |
| H | 72 | 24 |
| I | 73 | 25 |
| J | 74 | 26 |
| K | 75 | 27 |
| L | 76 | 28 |
| M | 77 | 29 |
| N | 78 | 30 |
| O | 79 | 31 |
| P | 80 | 32 |
| Q | 81 | 33 |
| R | 82 | 34 |
| S | 83 | 35 |
| T | 84 | 36 |
| U | 85 | 37 |
| V | 86 | 38 |
| W | 87 | 39 |
| X | 88 | 40 |
| Y | 89 | 41 |
| Z | 90 | 42 |
Exemplo:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
Distribuir os pesos de 2 a 9 da direita para a esquerda (recomeçando depois do oitavo caractere), conforme o exemplo:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
Multiplicar valor e peso de cada coluna e somar todos os resultados:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Multi | 5 | 8 | 51 | 36 | 171 | 24 | 28 | 30 | 0 | 4 | 60 | 42 |
`5 + 8 + 51 + 36 + 171 + 24 +28 + 30 + 0 + 4 + 60 + 42 = 459`
Obter o resto da divisão do somatório por 11.
\
Se o resto da divisão for igual a 1 ou 0, o primeiro dígito será igual a 0 (zero).
\
Senão, o primeiro dígito será igual ao resultado de 11 – resto.
No exemplo:
\
Resto da divisão `459/11 = 8` então o primeiro dígito verificador é o `3` (resultado de `11-8`)
Cálculo do segundo dígito verificador [#cálculo-do-segundo-dígito-verificador]
Para o cálculo do segundo dígito é necessário acrescentar o primeiro DV ao final do CNPJ,
\
formando assim treze caracteres, e repetir os passos realizados para o primeiro dígito.
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E | 3 |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 | 3 |
| Peso | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Multi | 6 | 10 | 68 | 54 | 38 | 27 | 32 | 35 | 0 | 5 | 80 | 63 | 6 |
`6 + 10 + 68 + 54 + 38 + 27 + 32 + 35 + 0 + 5 + 80 + 63 + 6 = 424`
Resto da divisão `424/11 = 6` então o segundo dígito verificador é o `5` (resultado de 11-6)
Resultado final: `12.ABC.345/01DE-``35`
# Projeto CNPJ.ws
Esse projeto é um subproduto do [**Bitize**](https://www.bitize.com.br/) que é uma platafoma de gestão de compras focada em encontrar bons fornecedores.
O [**Bitize**](https://www.bitize.com.br/) está desenvolvendo uma ferramenta para prospecção de **Fornecedores** e para isso foi desenvolvida uma base com informações públicas de empresas brasileiras que vem sendo enriquecida com informações de diversos orgãos públicos.
O foco do CNPJ.ws é disponibiliza umar API rápida, atualizada e fácil de usar que retorna dados públicos de empresas brasileiras disponibilizados pela [Lei de Acesso a Informação](http://www.planalto.gov.br/ccivil_03/_Ato2011-2014/2011/Lei/L12527.htm).
Temos uma API pública pois essas informações devem estar ao alcançe de todos.
O desafio agora é conseguir os dados referentes as inscrições estaduais, já possuímos de alguns estados ([veja aqui os estados](https://docs.cnpj.ws/modelos-de-dados/inscricoes-estaduais)) mas a tarefa realmente é complicada devido a falta de padronização entre os estados. Estamos trabalhando duro nisso!
Vamos postando as novidades aqui! Até mais!
# Como automatizar o cadastro de clientes com uma API de consulta CNPJ
Quantas vezes a sua equipe já digitou razão social, endereço, CNAE e inscrição estadual de um cliente novo — campo por campo — copiando do cartão CNPJ da Receita Federal? Além de lento, esse processo é a principal porta de entrada de erros cadastrais: um dígito trocado no CNPJ, um endereço desatualizado, uma razão social abreviada de forma diferente em cada sistema.
A boa notícia é que nada disso precisa ser manual. Com uma **API de consulta CNPJ**, o seu sistema pede apenas um dado ao usuário — o número do CNPJ — e preenche todo o resto sozinho, com informações oficiais e atualizadas. Neste post, mostramos como esse fluxo funciona, como implementá-lo com a API do CNPJ.ws e como um ERP brasileiro usa exatamente essa abordagem em produção.
O problema do cadastro manual [#o-problema-do-cadastro-manual]
Todo sistema que atende empresas — ERP, CRM, plataforma de cobrança, e-commerce B2B — precisa cadastrar pessoas jurídicas. No fluxo manual, isso significa um formulário com 10 a 20 campos que alguém preenche consultando documentos. Os custos aparecem em três frentes:
* **Tempo**: cada cadastro consome minutos de trabalho repetitivo, multiplicado por todos os clientes e fornecedores da base.
* **Erros**: digitação manual gera divergências que se propagam para notas fiscais, boletos e contratos — e retrabalho para corrigir.
* **Dados desatualizados**: a empresa muda de endereço ou de situação cadastral, e o cadastro no sistema continua com a informação antiga.
Como funciona uma API de consulta CNPJ [#como-funciona-uma-api-de-consulta-cnpj]
Uma API de consulta CNPJ expõe os dados públicos das empresas brasileiras em formato estruturado (JSON), pronto para ser consumido por qualquer aplicação. No caso do CNPJ.ws, uma única requisição HTTP retorna razão social, nome fantasia, situação cadastral, natureza jurídica, porte, endereço completo, CNAEs, quadro societário, inscrições estaduais e regime tributário (Simples Nacional/MEI).
O fluxo de automação tem três passos:
1\. O usuário informa só o CNPJ [#1-o-usuário-informa-só-o-cnpj]
No formulário de cadastro, o único campo obrigatório passa a ser o CNPJ. Vale validar os dígitos verificadores no front-end antes de consultar, evitando chamadas desnecessárias.
2\. O sistema consulta a API [#2-o-sistema-consulta-a-api]
```bash
curl https://publica.cnpj.ws/cnpj/00000000000191
```
A resposta traz o objeto completo da empresa. A API pública do CNPJ.ws permite até 3 consultas por minuto — suficiente para testar e para volumes baixos. Para uso em produção, a API comercial oferece limites maiores, dados adicionais e SLA.
3\. O formulário se preenche sozinho [#3-o-formulário-se-preenche-sozinho]
Com a resposta em mãos, o sistema popula todos os campos: razão social, endereço, CNAE principal, regime tributário. O usuário apenas confere e confirma. O que antes levava minutos passa a levar segundos — e os dados chegam exatamente como constam na base oficial.
Caso real: cadastro de clientes por IA no bitERP [#caso-real-cadastro-de-clientes-por-ia-no-biterp]
Um exemplo de quem usa esse fluxo em produção é o [bitERP, um ERP com inteligência artificial](https://www.biterp.ai), desenvolvido no Brasil. No bitERP, o usuário pode pedir no chat algo como *"cadastra o cliente CNPJ 00.000.000/0001-00"* — e o agente de IA consulta a API do CNPJ.ws, preenche o cadastro completo na tela e pede apenas a confirmação final.
A combinação é interessante porque junta duas automações: a IA elimina a navegação por menus e formulários, e a API de consulta CNPJ elimina a busca e digitação dos dados. O resultado é um onboarding de cliente que se resolve em uma única frase, com dados oficiais da Receita Federal — sem erro de digitação e sem cadastro incompleto.
O mesmo padrão se aplica a fornecedores, transportadoras e qualquer outra entidade PJ do sistema.
Boas práticas ao integrar [#boas-práticas-ao-integrar]
Para tirar o máximo da integração, vale seguir algumas recomendações:
* **Valide o CNPJ antes de consultar** — dígito verificador é cálculo local, não gaste requisição com número inválido.
* **Trate os limites de requisição** — implemente retry com backoff para o erro 429 e considere a API comercial para volume.
* **Guarde a data da consulta** — dados cadastrais mudam; saber quando o cadastro foi sincronizado permite programar atualizações periódicas.
* **Alerta de situação cadastral** — se a empresa constar como baixada, suspensa ou inapta, sinalize antes de concluir o cadastro. Isso evita emitir nota para CNPJ irregular.
* **Deixe o usuário revisar** — automação preenche, humano confirma. Especialmente campos que o cliente pode querer sobrescrever, como nome fantasia.
Comece agora [#comece-agora]
Você pode testar a consulta neste momento, sem cadastro: basta chamar `https://publica.cnpj.ws/cnpj/{número}` e ver o JSON retornado. Para levar a integração para produção, conheça os [planos da API comercial do CNPJ.ws](https://www.cnpj.ws/pt-BR#precos) — e se quiser ver o fluxo de cadastro automatizado funcionando dentro de um ERP, o exemplo do bitERP mostra até onde essa automação pode chegar.
# Consultar CNPJ com PHP
O PHP é uma das linguagens mais utilizadas no desenvolvimento web e com ela é muito simples fazer uma consulta na API do [CNPJ.ws](https://www.cnpj.ws/pt-BR).
Com a integração podemos usar a API para consultar o endereço, inscrição estadual, situação cadastral, CNAE e muitas outras informações que podem ser importantes no momento do cadastro do cliente ou fornecedor através do CNPJ.
API Pública [#api-pública]
O [CNPJ.ws](https://www.cnpj.ws/pt-BR) disponibiliza uma API pública para consultas onde você pode fazer até 3 consultas por minuto. [Veja a documentação](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
```php
Integração CNPJ.ws x Excel - Macros
Como pesquisar [#como-pesquisar]
Para pesquisar basta preencher com o CNPJ da empresa na coluna CNPJ (na planilha **"Consultas"**) e depois clicar no botão acima **"Consultar/Atualizar"**:
Após clicar no botão **“Consultar/Atualizar”**, a planilha fornecerá todos os dados disponíveis, simples né?
Lembrando que o [CNPJ.ws](https://www.cnpj.ws/pt-BR) possui uma API pública e você pode consultar CNPJs gratuitamente, basta não preencher o Token. Mas a API pública possui uma limitação de **3 consultas por minuto** ([veja a documentação](https://docs.cnpj.ws/referencia-de-api/api-publica/limitacoes)), o que torna a consulta um pouco lenta, mas para um volume pequeno de consultas pode ser viável.
Caso precise de mais velocidade ou um volume maior de consultas, verifique [nossos planos](https://www.cnpj.ws/pt-BR#precos). Fizemos um comparativo, consultando 100 CNPJs diferentes, com e sem o token:
| Usando o Token | Consultas | Tempo |
| :------------: | :-------: | :----------: |
| Sim | 100 | **00:00:57** |
| Não | 100 | 00:34:40 |
[**Clique aqui para baixar a Planilha Gratuitamente**](https://www.cnpj.ws/ConsultaDadosEmpresariaisViaCNPJws.zip)
Esta planilha é fornecida apenas como um exemplo e não representa um produto oficial do CNPJ.ws. Por isso, não oferecemos suporte para questões relacionadas ao Excel. Fique à vontade para personalizar este exemplo de acordo com suas necessidades. Se tiver dúvidas ou sugestões, estamos aqui para ajudar! Entre em contato conosco pelo e-mail: [contato@cnpj.ws](mailto:contato@cnpj.ws).
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Um abraço!
# Consultar CNPJ Gratuitamente com Java
Se você está em busca de uma maneira eficiente e gratuita de consultar dados de CNPJ diretamente de sua aplicação Java, você chegou ao lugar certo! Neste guia, vamos explorar como você pode integrar sua aplicação Java com a API do [CNPJ.ws](https://www.cnpj.ws/pt-BR) para acessar informações detalhadas de empresas registradas na Receita Federal.
O [CNPJ.ws](https://www.cnpj.ws/pt-BR) disponibiliza uma API pública para consultas onde você pode fazer até 3 consultas por minuto. [Veja a documentação](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
Vamos dividir este tutorial em seções para facilitar a compreensão. Acompanhe!
Pré-Requisitos [#pré-requisitos]
**Java**: Certifique-se de ter o JDK instalado em sua máquina. **IDE**: Um ambiente de desenvolvimento Java, como o Eclipse ou IntelliJ IDEA.
Configurando o Ambiente [#configurando-o-ambiente]
Crie um novo projeto Java em seu IDE favorito.
Adicione a biblioteca OkHttp: Vamos utilizar a biblioteca OkHttp para facilitar as requisições HTTP. Adicione a dependência em seu arquivo pom.xml se estiver usando Maven:
```xml
com.squareup.okhttp3
okhttp
4.9.0
```
Desenvolvendo a Classe de Consulta [#desenvolvendo-a-classe-de-consulta]
Crie uma nova classe Java chamada ConsultaCNPJ. Nessa classe, implementaremos o método para realizar a consulta de CNPJ:
```java
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
public class ConsultaCNPJ {
private static final String URL_BASE = "https://publica.cnpj.ws/cnpj/";
//Caso use a API Comercial a URL é diferente, veja a doc:
public static void main(String[] args) {
try {
String cnpj = "27865757000102";
String jsonResponse = consultaCNPJ(cnpj);
System.out.println(jsonResponse);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String consultaCNPJ(String cnpj) throws IOException {
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url(URL_BASE + cnpj)
.get()
.build();
try (Response response = client.newCall(request).execute()) {
return response.body().string();
}
}
}
```
Explicação: [#explicação]
* **OkHttpClient**: Usamos essa classe para enviar requisições HTTP.
* **Request**: Aqui construímos nossa requisição, definindo a URL com o número do CNPJ que desejamos consultar.
* **Response**: Armazenamos a resposta da API para processá-la posteriormente.
Testando a Consulta [#testando-a-consulta]
Execute a classe ConsultaCNPJ e verifique o console. Você deverá ver a resposta JSON contendo as informações detalhadas sobre o CNPJ consultado.
Conclusão [#conclusão]
Neste guia, você aprendeu como realizar consultas de CNPJ de forma gratuita usando a API pública do CNPJ.WS em um aplicativo Java. Aproveite essa funcionalidade para enriquecer seus projetos Java com dados empresariais precisos e atualizados.
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Até mais!
# Consultar CNPJ com Javascript e Node.JS
Consultar um CNPJ utilizando a API do CNPJ.ws com Javascript e Node.JS é muito fácil!
Manter o cadastro de clientes/fornecedores ou até mesmo fazer uma consulta aos dados de empresas para facilitar algum cadastro interno do seu sistema é algo muito comum e a API do CNPJ.ws disponibiliza uma maneira fácil e rápida para desenvolver essa integração.
Com a integração podemos usar a API para consultar o endereço, inscrição estadual, situação cadastral, CNAE e muitas outras informações que podem ser importantes no momento do cadastro do cliente ou fornecedor através do CNPJ.
Os dados retornados pela API são obtidos de diversos órgãos públicos (Receita Federal, Sintegra, SERPRO, Suframa, etc), aglutinados e organizados para facilitar o uso por outros sistemas através de uma API Rest.
Instalação [#instalação]
Nós desenvolvemos um pacote para facilitar essa integração, veja no [Github](https://github.com/cnpj-ws/consultar-cnpj).
Lembrando que você pode usar nossa API gratuita para consultar CNPJ ou pode adquirir um dos nossos planos comerciais.
Para começar, vamos instalar o pacote:
Utilizando YARN:
```shell
yarn add consultar-cnpj
```
Utilizando NPM:
```shell
npm i consultar-cnpj --save
```
Utilização [#utilização]
O CNPJ.ws possui uma API Pública e uma Comercial, para utilização da API Pública você não precisa de um token, mas só pode fazer até 3 consultas por minuto. Caso esteja utilizando a API Comercial você deve passar o token como segundo parâmetro na consulta para utilizar os seus benefícios. Você pode ver mais detalhes dos planos comerciais na nossa [página de preços](https://www.cnpj.ws/pt-BR#precos).
```javascript
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
// O Token é opcional
const empresa = await consultarCNPJ("40154884000153", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
```
Retorno [#retorno]
Abaixo o JSON retornado pela API:
```json
{
"cnpj_raiz": "40154884",
"razao_social": "STARLINK BRAZIL SERVICOS DE INTERNET LTDA.",
"capital_social": "800000.00",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T08:21:13.130Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2062",
"descricao": "Sociedade Empresária Limitada"
},
"qualificacao_do_responsavel": {
"id": 5,
"descricao": "Administrador "
},
"socios": [
{
"cpf_cnpj_socio": "***966178**",
"nome": "VITOR JAMES URNER",
"tipo": "Pessoa Física",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "71 a 80 anos",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "39523686000130",
"nome": "STARLINK BRAZIL HOLDING LTDA.",
"tipo": "Pessoa Jurídica",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***966178**",
"nome_representante": "VITOR JAMES URNER",
"faixa_etaria": "Não se aplica",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 22,
"descricao": "Sócio"
},
"qualificacao_representante": {
"id": 5,
"descricao": "Administrador "
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "40154884000153",
"atividades_secundarias": [
{
"id": "6190699",
"secao": "J",
"divisao": "61",
"grupo": "61.9",
"classe": "61.90-6",
"subclasse": "6190-6/99",
"descricao": "Outras atividades de telecomunicações não especificadas anteriormente"
},
{
"id": "6462000",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.62-0",
"subclasse": "6462-0/00",
"descricao": "Holdings de instituições não financeiras"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
}
],
"cnpj_raiz": "40154884",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "53",
"tipo": "Matriz",
"nome_fantasia": null,
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2020-12-18",
"data_inicio_atividade": "2020-12-18",
"nome_cidade_exterior": null,
"tipo_logradouro": "ALAMEDA",
"logradouro": "SANTOS",
"numero": "74",
"complemento": "ANDAR 7 CONJ 72 SALA 10",
"bairro": "CERQUEIRA CESAR",
"cep": "01418000",
"ddd1": "11",
"telefone1": "30229503",
"ddd2": null,
"telefone2": null,
"ddd_fax": null,
"fax": null,
"email": "VITOR@URNER.COM.BR",
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6130200",
"secao": "J",
"divisao": "61",
"grupo": "61.3",
"classe": "61.30-2",
"subclasse": "6130-2/00",
"descricao": "Telecomunicações por satélite"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
},
"cidade": {
"id": 3832,
"nome": "São Paulo",
"ibge_id": 3550308,
"siafi_id": "7107"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "130287771116",
"ativo": true,
"atualizado_em": "2021-08-25T16:59:58.589Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
Conclusão [#conclusão]
Utilizando a API do CNPJ.ws você obtém os dados das empresas brasileiras de forma simples e fácil, dê uma olhada em nossa [documentação](https://docs.cnpj.ws/).
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Qualquer dúvida nós estamos aqui para te apoiar, mande um e-mail para [contato@cnpj.ws](mailto:contato@cnpj.ws)!
# Gatilho para consultar CNPJ no Protheus
Cadastrar clientes ou fornecedores no Protheus pode ficar mais fácil se consultarmos o CNPJ na API do [***CNPJ.ws***](https://www.cnpj.ws/pt-BR)
Com a integração podemos usar a API para consultar o endereço, inscrição estadual, situação cadastral, CNAE e muitas outras informações que podem ser importantes no momento do cadastro do cliente ou fornecedor.
Já criamos uma classe em ADVPL para integramos o Protheus ao [***CNPJ.ws***](https://www.cnpj.ws/pt-BR) no post: [Consultar CNPJ com ADVPL (Protheus)](https://docs.cnpj.ws/artigos/integracao-protheus).
Nesse post vamos usar essa classe ADVPL para desenvolvermos um gatilho que utilizaremos tanto no cadastro de clientes quanto no cadastro de fornecedores. Lembrando que você pode usar nossa API gratuita para consultar CNPJ, mas com uma limitação de 3 consultas por minuto ou pode adquirir um dos nossos planos comerciais.
Função getCNPJ [#função-getcnpj]
Vamos começar criando uma user function que iremos chamar nos nossos gatilhos. Veja que ela recebe dois parâmetros:
* cTab: SA1 ou SA2, indicando se estamos trabalhando com clientes ou fornecedores
* cCNPJ: o número do CNPJ
Também fizemos um tratamento usando a função `isBlind` para caso o gatilho seja chamado via execauto, sem a interface do usuário. E usamos a função `FWMsgRun` para que o usuário tenha um retorno visual e não apenas uma tela "travada" enquanto o processo é executado.
```js
#include 'totvs.ch'
user function getCNPJ(cTab,cCNPJ)
local aArea:= getArea()
local cRet := ''
default cTab := 'SA1'
default cCNPJ:= ''
cCNPJ:= allTrim(cCNPJ)
if !empty(cTab) .and. len(cCNPJ) == 14
if isBlind()
cRet:= consulta(cTab,cCNPJ)
else
FWMsgRun(,{||cRet:= consulta(cTab,cCNPJ)},'CNPJ.ws','Consultando...')
endif
endif
restArea(aArea)
return cRet
```
Vamos criar uma static function que será a responsável pela comunicação com o [***CNPJ.ws***](https://www.cnpj.ws/pt-BR) . Você deve revisar bem esse código para atender as suas necessidades aí na sua empresa, aqui eu preenchi todos os campos que me vieram a cabeça, mas sinta-se à vontade para fazer alterações:
```javascript
static function consulta(cTab,cCNPJ)
local oCNPJws:= CNPJws():new()
local oJSON := nil
local nX := 1
local cRet := ''
local lJob := isBlind()
local oModel := nil
default cTab := 'SA1'
default cCNPJ:= ''
if oCNPJws:consultarCNPJ(cCNPJ)
oJSON:= oCNPJws:getResponse()
cRet:= oJSON['razao_social']
if oJSON['estabelecimento']['situacao_cadastral'] <> 'Ativa'
if lJob
conout(cCNPJ + ': A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
else
alert('A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
endif
endif
if cTab == 'SA1'
M->A1_MSBLQL:= if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1')
If ExistTrigger('A1_MSBLQL')
RunTrigger(1,Nil,Nil,,'A1_MSBLQL')
Endif
M->A1_CNAE:= oJSON['estabelecimento']['atividade_principal']['id']
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+M->A1_CNAE))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
If ExistTrigger('A1_CNAE')
RunTrigger(1,Nil,Nil,,'A1_CNAE')
Endif
M->A1_PESSOA := 'J'
If ExistTrigger('A1_PESSOA')
RunTrigger(1,Nil,Nil,,'A1_PESSOA')
Endif
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH')+ '0' + oJSON['estabelecimento']['pais']['id'] ))
M->A1_CODPAIS := CCH->CCH_CODIGO
If ExistTrigger('A1_CODPAIS')
RunTrigger(1,Nil,Nil,,'A1_CODPAIS')
Endif
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
M->A1_PAIS := SYA->YA_CODGI
If ExistTrigger('A1_PAIS')
RunTrigger(1,Nil,Nil,,'A1_PAIS')
Endif
endif
endif
M->A1_NREDUZ := oJSON['estabelecimento']['nome_fantasia']
if empty(M->A1_NREDUZ) //Caso nao possua nome fantasia
M->A1_NREDUZ := avKey(cRet, 'A1_NREDUZ')
endif
If ExistTrigger('A1_NREDUZ')
RunTrigger(1,Nil,Nil,,'A1_NREDUZ')
Endif
M->A1_CEP := oJSON['estabelecimento']['cep']
If ExistTrigger('A1_CEP')
RunTrigger(1,Nil,Nil,,'A1_CEP')
Endif
M->A1_EST := oJSON['estabelecimento']['estado']['sigla']
If ExistTrigger('A1_EST')
RunTrigger(1,Nil,Nil,,'A1_EST')
Endif
M->A1_COD_MUN:= substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5)
If ExistTrigger('A1_COD_MUN')
RunTrigger(1,Nil,Nil,,'A1_COD_MUN')
Endif
M->A1_BAIRRO := oJSON['estabelecimento']['bairro']
If ExistTrigger('A1_BAIRRO')
RunTrigger(1,Nil,Nil,,'A1_BAIRRO')
Endif
M->A1_END := oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero']
If ExistTrigger('A1_END')
RunTrigger(1,Nil,Nil,,'A1_END')
Endif
M->A1_COMPLEM:= oJSON['estabelecimento']['complemento']
If ExistTrigger('A1_COMPLEM')
RunTrigger(1,Nil,Nil,,'A1_COMPLEM')
Endif
M->A1_DDD := oJSON['estabelecimento']['ddd1']
If ExistTrigger('A1_DDD')
RunTrigger(1,Nil,Nil,,'A1_DDD')
Endif
M->A1_TEL := oJSON['estabelecimento']['telefone1']
If ExistTrigger('A1_TEL')
RunTrigger(1,Nil,Nil,,'A1_TEL')
Endif
M->A1_FAX := oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax']
If ExistTrigger('A1_FAX')
RunTrigger(1,Nil,Nil,,'A1_FAX')
Endif
M->A1_EMAIL := oJSON['estabelecimento']['email']
If ExistTrigger('A1_EMAIL')
RunTrigger(1,Nil,Nil,,'A1_EMAIL')
Endif
if valType(oJSON['simples']) == 'J'
M->A1_SIMPNAC:= if(oJSON['simples']['simples'] == 'Sim', '1', '2')
else
M->A1_SIMPNAC:= '2'
endif
If ExistTrigger('A1_SIMPNAC')
RunTrigger(1,Nil,Nil,,'A1_SIMPNAC')
Endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
M->A1_INSCR:= oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual']
If ExistTrigger('A1_INSCR')
RunTrigger(1,Nil,Nil,,'A1_INSCR')
Endif
EXIT
endif
next
elseIf cTab == 'SA2'
//MATA020 está em MVC
oModel := FWModelActive()
oModel:SetValue('SA2MASTER','A2_MSBLQL' ,if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1'))
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+oJSON['estabelecimento']['atividade_principal']['id']))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
oModel:SetValue('SA2MASTER','A2_CNAE',oJSON['estabelecimento']['atividade_principal']['id'])
oModel:SetValue('SA2MASTER','A2_TIPO', 'J')
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH') + '0' + oJSON['estabelecimento']['pais']['id']))
oModel:SetValue('SA2MASTER','A2_CODPAIS', allTrim(CCH->CCH_CODIGO))
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
oModel:SetValue('SA2MASTER','A2_PAIS', allTrim(SYA->YA_CODGI))
endif
endif
if !empty(oJSON['estabelecimento']['nome_fantasia'])
oModel:SetValue('SA2MASTER','A2_NREDUZ',oJSON['estabelecimento']['nome_fantasia'])
else
oModel:SetValue('SA2MASTER','A2_NREDUZ',avKey(cRet, 'A2_NREDUZ'))
endif
oModel:SetValue('SA2MASTER','A2_CEP', oJSON['estabelecimento']['cep'])
oModel:SetValue('SA2MASTER','A2_EST', oJSON['estabelecimento']['estado']['sigla'])
oModel:SetValue('SA2MASTER','A2_COD_MUN', substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5))
oModel:SetValue('SA2MASTER','A2_BAIRRO', oJSON['estabelecimento']['bairro'])
oModel:SetValue('SA2MASTER','A2_END',oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero'])
oModel:SetValue('SA2MASTER','A2_COMPLEM', oJSON['estabelecimento']['complemento'])
oModel:SetValue('SA2MASTER','A2_DDD', oJSON['estabelecimento']['ddd1'])
oModel:SetValue('SA2MASTER','A2_TEL', oJSON['estabelecimento']['telefone1'])
oModel:SetValue('SA2MASTER','A2_FAX', oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax'])
oModel:SetValue('SA2MASTER','A2_EMAIL', oJSON['estabelecimento']['email'])
if valType(oJSON['simples']) == 'J'
oModel:SetValue('SA2MASTER','A2_SIMPNAC', if(oJSON['simples']['simples'] == 'Sim', '1', '2'))
else
oModel:SetValue('SA2MASTER','A2_SIMPNAC', '2')
endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
oModel:SetValue('SA2MASTER','A2_INSCR', oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual'])
EXIT
endif
next
endif
else
if lJob
conout('Erro ao consultar CNPJ: ' + oCNPJws:getError())
else
alert('Erro ao consultar CNPJ: ' + oCNPJws:getError())
endif
endif
return cRet
```
Gatilho A1_CGC [#gatilho-a1_cgc]
Abaixo o preenchimento do gatilho do campo A1\_CGC, nele chamamos user function `u_getcnpj` passando como parâmetros a **SA1** além do CNPJ:
Gatilho A2_CGC [#gatilho-a2_cgc]
Abaixo o preenchimento do gatilho do campo A2\_CGC, nele chamamos user function `u_getcnpj` passando como parâmetros a **SA2** além do CNPJ:
Conclusão [#conclusão]
O resultado deve ser como o gif abaixo, ao digitar o CNPJ o Protheus irá consultar o [***CNPJ.ws***](https://www.cnpj.ws/pt-BR) e preencher os campos automaticamente:
Você pode consultar os fontes desse projeto no [GitHub](https://github.com/cnpj-ws/protheus), a classe mencionada está nesse repositório também.
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Até mais!
# Consultar CNPJ com ADVPL (Protheus)
O sistema Protheus da Totvs é o ERP líder do mercado brasileiro e pode ser integrado com a API do CNPJ.ws de maneira fácil e simples para consultar clientes ou fornecedores através do CNPJ.
O Protheus utiliza a linguagem proprietária da Totvs, o ADVPL (Advanced Protheus Language), que é uma linguagem de programação padrão xBase (Clipper, Visual Objects e depois Fivewin).
Para essa integração vamos construir uma classe genérica de comunicação que poderá ser usada em diversos tipos de projeto. Você também pode encontrar esse projeto no [GitHub](https://github.com/cnpj-ws/protheus).
Lembrando que você pode usar nossa API gratuita para consultar CNPJ, mas com uma limitação de 3 consultas por minuto ou pode adquirir um dos nossos planos comerciais.
Com a integração podemos usar a API para consultar o endereço, inscrição estadual, situação cadastral, CNAE e muitas outras informações que podem ser importantes no momento do cadastro do cliente ou fornecedor, pessoa jurídica, através do CNPJ.
Integração CNPJ.ws com o ERP Totvs Protheus [#integração-cnpjws-com-o-erp-totvs-protheus]
Vamos começar, abaixo a declaração da classe:
```javascript
#include 'totvs.ch'
#include 'protheus.ch'
class CNPJws
data lVerb as Logical
data cURL as String
data cToken as String
data cErro as String
data cRet as String
data oRet as String
data aHeaders as Array
data lRet as Logical
method new() CONSTRUCTOR
method consoleLog(cMsg,lErro)
method setError(oRest)
method consultarCNPJ(cCNPJ)
method getResponse()
method getError()
endClass
```
Teremos 6 métodos na nossa classe:
* **new**: Responsável por instanciar a classe;
* **setError**: Método interno para geração dos erros;
* **consultarCNPJ**: Responsável por fazer a consulta do CNPJ junto a API do CNPJ.ws;
* **getResponse**: Retorna a resposta da API em formato JSON;
* **getError**: Retorna a mensagem de erro;
Agora vamos desenvolver o método `new`, que é o nosso método construtor. Veja que esse método recebe o parâmetro `lTest` (o valor default é falso) e sim, vamos fazer testes com a nossa classe de integração.
Veja também que temos um parâmetro **CN\_TOKEN**, devemos criá-lo caso estejamos usando a API Comercial (sem restrições) e preenchê-lo com o Token que foi enviado no seu e-mail.
```javascript
method new(lTest) class CNPJws
default lTest:= .f.
::cToken := if(lTest, '', superGetMV('CN_TOKEN',.f.,''))
::cURL := if(empty(::cToken),'https://publica.cnpj.ws','https://comercial.cnpj.ws')
::lVerb := if(lTest, .t., superGetMV('CN_VERBO',.f.,.t.)) //Indica se ira imprimir todas as msgs no console
::cErro := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::aHeaders:= {"Content-Type: application/json; charset=utf-8"}
if !empty(::cToken)
aAdd(::aHeaders,'x_api_token: ' + allTrim(::cToken))
endif
::consoleLog('Classe instanciada com sucesso!')
return Self
```
No método `new` nós usamos o método `consoleLog`, então vamos desenvolver ele agora. Esse método visa padronizar as mensagens emitidas pela classe.
Caso o parâmetro **CN\_VERBO** esteja como .T. a classe irá imprimir todas as mensagens no console.log do Protheus.
```javascript
method consoleLog(cMsg,lErro) class CNPJws
local cLog:= ''
default cMsg := ''
default lErro:= .f.
if ::lVerb .or. lErro
cLog:= '[' + dtoc(date()) + ']'
cLog+= '[' + time() + ']'
cLog+= '[' + ProcName(1) + ']'
cLog+= '[' + cValToChar(ProcLine(1)) + ']'
cLog+= '['+allTrim(cMsg)+']'
if lErro
::cErro:= cLog
::lRet := .f.
endif
if ::lVerb .or. lErro
conout(cLog)
endif
endif
return
```
Abaixo o método `setError` usado pela classe para gerar as mensagens de erro:
```javascript
method setError(oRest,cPath) class CNPJws
local cLog := ''
local cAux := ''
local cStatus := ''
default cPath := ''
::oRet := nil
::cRet:= oRest:GetResult()
if valType(::cRet) <> 'C'
::cRet:= ''
endif
if !empty(::cRet)
::cRet:= FWNoAccent(DecodeUtf8(::cRet))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
endif
cAux:= FWNoAccent(DecodeUtf8(oRest:GetLastError()))
if empty(cAux)
cAux:= FWNoAccent(oRest:GetLastError())
endif
cStatus:= oRest:GetHTTPCode()
cLog+= 'Host: ' + ::cURL + CRLF
cLog+= 'Operacao: ' + ProcName(1) + ' ' + cPath + CRLF
cLog+= 'HTTP Code: ' + cStatus + CRLF
cLog+= 'Erro: ' + cAux + CRLF
cLog+= 'Resultado: ' + ::cRet + CRLF
::consoleLog(cLog,.T.)
return
```
Agora sim, vamos desenvolver o método responsável por se comunicar com a API do CNPJ.ws, o método `consultarCNPJ`. Aqui vamos utilizar a classe [FWREST](https://tdn.engpro.totvs.com.br/display/framework/FWRest?focusedCommentId=446697540) para fazer a comunicação com a API, esse método receber o CNPJ como parâmetro e faz a consulta na API.
O método retorna um boolean, caso de tudo certo ele vai retornar true, caso ocorra um erro o retorno será falso, veja abaixo:
```javascript
method consultarCNPJ(cCNPJ) class CNPJws
local oRest := FWRest():New(::cURL)
local cPath := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::cErro:= ''
cPath+= allTrim(cCNPJ)
oRest:setPath(cPath)
if oRest:Get(::aHeaders)
if !empty(oRest:GetResult())
::cRet:= FWNoAccent(DecodeUtf8(oRest:GetResult()))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
::cRet:= strTran(::cRet,'\/','/')
::cRet:= strtran(::cRet,":null",': " "')
::cRet:= strtran(::cRet,'"self"','"_self"')
::oRet:= JsonObject():new()
::oRet:fromJson(::cRet)
::lRet := .t.
::cErro:= ''
else
::oRet := nil
::cErro:= ''
::lRet := .t.
endif
::consoleLog('Sucesso! ' + cPath)
else
::setError(oRest,cPath)
endif
FreeObj(oRest)
return ::lRet
```
Abaixo temos o método responsável por retornar o JSON que a API do [***CNPJ.ws***](https://www.cnpj.ws/pt-BR) retornou na consulta:
```javascript
method getResponse() class CNPJws
return ::oRet
```
Abaixo temos o método responsável por retornar a mensagem de erro caso a consulta não obtenha sucesso:
```javascript
method getError() class CNPJws
return ::cErro
```
Legal, construímos nossa classe, agora é um bom momento para desenvolvermos uma rotina para utilizarmos nossa classe:
```javascript
user function tstCNPJ()
local oCNPJ:= nil
local oJSON:= nil
RpcSetType(3)
if !RpcSetEnv('99','01')
return
endif
oCNPJ:= CNPJws():new()//Instancia a classe
if oCNPJ:consultarCNPJ('40154884000153')
oJSON:= oCNPJ:getResponse()
endif
RPCClearEnv()
return
```
Caso precise de apoio para implementar essa integração na sua base, nós recomendamos a [Apply System](https://applysystem.com.br/site/), nossa parceira, que possui consultores especializados na integração entre sistemas!
Esse post ficou grande, não é? Então vou deixar para fazer uma parte 2 utilizando o TL++ para criarmos um teste para a classe de integração, porém os fontes já estão no [GitHub](https://github.com/cnpj-ws/protheus) caso queira dar uma olhada!
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Até mais!
# Manter o cadastro de clientes e fornecedores atualizados
Manter os seus cadastros de clientes e fornecedores sempre atualizados é uma tarefa difícil, porém necessária. Independentemente do tamanho da sua empresa é muito importante ter esses cadastros sempre atualizados, pois eles ajudam a padronizar e controlar informações sobre o seu negócio.
A API do CNPJ.ws obtém dados de diversos órgãos públicos (Receita Federal, Sintegra, SERPRO, Suframa, etc), aglutina e organiza esses dados para facilitar o uso por outros sistemas através de uma API Rest.
Dessa forma você consegue em uma só API obter dados dos sócios, CNAE e inscrições estaduais de maneira simples e automatizada.
Dê uma olhada em nossa [documentação](https://docs.cnpj.ws/).
Para saber mais sobre nossos planos e formas de pagamento acesse [CNPJ.ws](https://www.cnpj.ws/pt-BR#precos).
Qualquer dúvida nós estamos aqui para te apoiar, mande um e-mail para [contato@cnpj.ws](mailto:contato@cnpj.ws)!
# O que é o CNPJ
O Cadastro Nacional de Pessoa Jurídica é o registro utilizado pela Receita Federal para a abertura de uma instituição com ou sem fins lucrativos, a fim de acompanhar as movimentações financeiras dessas organizações, por meio do CNPJ, a empresa existe perante o governo e sua atuação no mercado é legalizada.
O CNPJ é composto por 14 números, sendo que, os 8 primeiros são a inscrição da empresa, os próximos 4 são para demonstrar se a instituição é uma matriz ou uma filial, o número conhecido como “mil contra”, 0001, é utilizado para matrizes, e os números seguintes, 0002, 0003 e outras, são usados para filiais. Os 2 últimos números são os dígitos verificadores. O padrão para o registro é: XX.XXX.XXX/000X-XX.
A funções do documento variam, podendo ser para comprovar a existência da organização, emitir notas fiscais, contratar fornecedores ou funcionários, pegar empréstimos ou fazer financiamentos. Por estes motivos, não são só empresas que precisam do CNPJ, outras instituições também usufruem desse registro, por exemplo, igrejas, associações, ONGs, partidos políticos e outros.
Nas informações encontradas no Cadastro Nacional de Pessoa Jurídica constam o número do CNPJ, a data de abertura da organização, o nome da instituição e o nome fantasia, as atividades econômicas em que a empresa atua, endereço e telefone. Para ter este registro, é preciso entrar com um pedido online no site da Receita Federal e preencher a ficha cadastral com os documentos necessários.
Para achar o CPNJ de uma empresa, basta acessar o site do CNPJws, uma API, desenvolvida para consultar dados de pessoas jurídicas, a plataforma tem 5 planos, sendo eles: Gratuito, Básico, Intermediário, Avançado e Premium.
# Atividades Econômicas
Abaixo o modelo de dados referente as atividades econômicas:
| Campo | Tipo | Descrição |
| --------- | :--: | :-------- |
| id | S | ID |
| secao | S | Seção |
| divisao | S | Divisão |
| grupo | S | Grupo |
| classe | S | Classe |
| subclasse | S | Subclasse |
| descricao | S | Descrição |
# Cidades
Abaixo o modelo de dados referente as cidades:
| Campo | Tipo | Descrição |
| --------- | :--: | :------------- |
| id | N | ID |
| nome | S | Nome da cidade |
| ibge\_id | N | Código IBGE |
| siafi\_id | S | Código SIAFI |
Fonte: [https://www.ibge.gov.br/explica/codigos-dos-municipios.php](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)
# Estabelecimentos
Abaixo o modelo de dados referente aos estabelecimentos:
Estabelecimento [#estabelecimento]
| Campo | Tipo | Descrição |
| --------------------------- | :--: | :---------------------------- |
| cnpj | S | CNPJ |
| cnpj\_raiz | S | Raiz do CNPJ |
| cnpj\_ordem | S | Orderm do CNPJ |
| cnpj\_digito\_verificador | S | Dígito verificador do CNPJ |
| tipo | S | Tipo (Filial ou Matriz) |
| nome\_fantasia | S | Nome fantasia |
| situacao\_cadastral | S | Situação cadastral |
| data\_situacao\_cadastral | D | Data da situação cadastral |
| data\_inicio\_atividade | D | Data de início das atividades |
| nome\_cidade\_exterior | S | Nome da Cidade (Exterior) |
| pais | O | Pais |
| estado | O | Estado |
| cidade | O | Cidade |
| cep | S | CEP |
| tipo\_logradouro | S | Tipo de Logradouro |
| logradouro | S | Logradouro |
| numero | S | Número |
| complemento | S | Complemento |
| bairro | S | Bairro |
| ddd1 | S | DDD Telefone 1 |
| telefone1 | S | Telefone 1 |
| ddd2 | S | DDD Telefone 2 |
| telefone2 | S | Telefone 2 |
| ddd\_fax | S | DDD Fax |
| fax | S | Fax |
| email | S | E-mail |
| situacao\_especial | S | Situação especial |
| data\_situacao\_especial | D | Data da situação especial |
| atividade\_principal | O | Atividade principal |
| atividades\_secundarias | A | Atividades secundárias |
| motivo\_situacao\_cadastral | O | Motivo situação cadastral |
| inscricoes\_estaduais | A | Inscrições Estaduais |
| inscricoes\_suframa\* | A | Inscrições Suframa |
| regimes\_tributarios\* | A | Regimes Tributários |
**Atenção**
As incrições no Suframa e os Regimes Tributários estão disponíveis apenas na API Comercial
# Estados
Abaixo o modelo de dados referente ao estados:
| Campo | Tipo | Descrição |
| -------- | :--: | :-------------- |
| id | N | ID |
| nome | S | Nome do estado |
| sigla | S | Sigla do estado |
| ibge\_id | N | Código IBGE |
# Modelos de Dados
Esta sessão contém a documentação dos diferentes modelos de dados retornados pelas APIs, detalhando os campos e suas descrições. Inclui:
* **Atividades Econômicas**: Descrição dos códigos de atividades econômicas (CNAE).
* **Cidades**: Informações sobre as cidades, incluindo códigos IBGE.
* **Estabelecimentos**: Dados sobre os estabelecimentos comerciais, como endereços e situações cadastrais.
* **Estados**: Detalhes dos estados brasileiros, com códigos IBGE.
* **Inscrições Estaduais**: Informações sobre as inscrições estaduais associadas a CNPJs.
* **Suframa**: Documentação sobre inscrições no Suframa.
* **Mensagens de Erro**: Lista de possíveis mensagens de erro retornadas pelas APIs.
* **Naturezas Jurídicas**: Detalhes sobre as naturezas jurídicas das empresas.
* **Países**: Informações sobre os países, com códigos do BACEN.
* **Portes**: Descrições dos portes das empresas (ME, EPP, etc.).
* **Qualificações Societárias**: Detalhes sobre as qualificações dos sócios.
* **Regimes Tributários**: Informações sobre os regimes tributários das empresas.
* **Simples Nacional e MEI**: Dados relacionados ao Simples Nacional e ao MEI.
* **Situações Cadastrais**: Detalhes sobre as situações cadastrais das empresas na Receita Federal.
* **Sócios**: Informações sobre os sócios das empresas.
Esses documentos são essenciais para entender os tipos de dados que podem ser consultados e recebidos pelas APIs.
# Inscrições Estaduais
Abaixo o modelo de dados referente as inscrições estaduais:
| Campo | Tipo | Descrição |
| ------------------- | :--: | ------------------ |
| inscricao\_estadual | S | Inscrição estadual |
| regime | S | Regime |
| ativo | B | Inscrição ativa |
| estado | O | Estado |
**Atenção** No momento só estamos retornando apenas as inscrições estaduais dos estados abaixo:
* Bahia
* Goiás
* Minas Gerais
* Paraíba
* Paraná
* Pernambuco
* Rio Grande do Sul
* Santa Catarina
* São Paulo
* Sergipe
Estamos trabalhando para trazer as inscrições estaduais de outros estados!
# Suframa
Abaixo o modelo de dados referente as inscrições no suframa:
| Campo | Tipo | Descrição |
| ------------------ | :--: | :---------------- |
| inscricao\_suframa | S | Inscrição Suframa |
| ativo | B | Inscrição ativa |
**Atenção**
As incrições no Suframa estão disponíveis apenas na API Comercial
# Mensagens de Erro
A API pode retornar os códigos de erro abaixo:
| Código | Descrição |
| :----: | ------------------- |
| 400 | Requisição inválida |
| 401 | Não autorizado |
| 403 | Acesso negado |
| 404 | Não encontrado |
| 429 | Excesso de pedidos |
| 500 | Erro interno |
Abaixo o modelo de JSON padrão:
```json
{
"status": 400,
"titulo": "Requisição inválida",
"detalhes": "CNPJ inválido",
"validacao": []
}
```
# Naturezas Jurídicas
Abaixo o modelo de dados referente as naturezas jurídicas:
| Campo | Tipo | Descrição |
| --------- | :--: | :------------------------- |
| id | S | ID do da natureza jurídica |
| descricao | S | Descrição |
# Países
Abaixo o modelo de dados referente aos países:
| Campo | Tipo | Descrição |
| --------- | :--: | :------------------ |
| id | S | Código BACEN |
| iso2 | S | Código do país IS02 |
| iso3 | S | Código do país ISO3 |
| nome | S | Nome do país |
| comex\_id | S | Código COMEX |
# Portes
Modelo de dados referente ao porte da empresa:
| Campo | Tipo | Descrição |
| --------- | :--: | :---------- |
| id | S | ID do porte |
| descricao | S | Descrição |
Lista de portes cadastrados:
| ID | Descrição |
| -- | :----------------------- |
| 00 | Não informado |
| 01 | Micro Empresa |
| 03 | Empresa de Pequeno Porte |
| 05 | Demais |
# Qualificações Societárias
Abaixo o modelo de dados referente as qualificações societárias:
| Campo | Tipo | Descrição |
| --------- | :--: | :----------------- |
| id | N | ID da qualificação |
| descricao | S | Descrição |
# Regimes Tributários
A partir do ano de 2021, a RFB passa a disponibilizar as informações sobre o regime tributário das pessoas jurídicas, divulgado anualmente.
Os dados são extraídos da Escrituração Contábil Fiscal (ECF). Raramente, quando, devido à ocorrência de situação especial ou existência de Sociedades em Conta de Participação (SCP), há entrega pela instituição de mais de uma escrituração no ano com formas de tributação diferentes ou domicílio em mais de uma cidade, existirá mais de um registro para o CNPJ.
Lembrando que estão dispensados da transmissão do ECF pessoas jurídicas optantes pelo Simples Nacional, órgãos públicos, autarquias e fundações públicas. Os PJs inativos também não precisam enviar o ECF, desde que não tenham realizado nenhum tipo de atividade durante todo o ano-calendário.
Abaixo o modelo de dados referente aos regimes tributários:
| Campo | Tipo | Descrição |
| --------------------- | :--: | ------------------- |
| ano | S | Ano da Apuração |
| regime\_tributario | S | Regime |
| forma\_de\_tributacao | S | Forma de tributação |
Abaixo está a lista de valores possíveis para o campo regime\_tributario:
| Valor | Descrição |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| IMUNES E ISENTAS | Empresas dispensadas do pagamento de determinados tributos por imunidade constitucional ou por isenção prevista em lei. |
| LUCRO ARBITRADO | Regime aplicado pela Receita Federal em casos onde a empresa não apresenta condições de comprovar o lucro real ou presumido. |
| LUCRO PRESUMIDO | Regime em que a base de cálculo do imposto é definida a partir de um percentual fixo sobre a receita bruta. |
| LUCRO REAL | Regime em que a tributação é calculada sobre o lucro líquido contábil ajustado pelas adições e exclusões previstas em lei. |
A Receita disponibiliza essas dados sempre no ano posterior a entrega da ECF.
**Atenção** As informações referentes aos regimes tributários estão disponíveis apenas na API Comercial
# Simples Nacional e MEI
Abaixo o modelo de dados referente aos dados do Simples Nacional e do MEI:
Simples Nacional [#simples-nacional]
| Campo | Tipo | Descrição |
| ----------------------- | :--: | :----------------------------- |
| simples | S | Optante pelo Simples Nacional? |
| data\_opcao\_simples | S | Data da opção pelo Simples |
| data\_exclusao\_Simples | S | Data de exclusão do Simples |
| mei | S | Optante pelo MEI? |
| data\_opcao\_mei | S | Data da opão pelo MEI |
| data\_exclusao\_mei | S | Data da exclusão do MEI |
**Atenção**
Esse registro só é preenchido caso a empresa seja MEI, Simples ou tenha sido um dos dois em algum momento.
# Situações Cadastrais
Abaixo o modelo de dados referente as situações cadastrais:
| Campo | Tipo | Descrição |
| --------- | :--: | :------------- |
| id | N | ID da situação |
| descricao | S | Descrição |
# Sócios
Abaixo o modelo de dados referente aos sócios:
| Campo | Tipo | Descrição |
| --------------------------- | :--: | :--------------------------- |
| cpf\_cnpj\_socio | S | CPF\* ou CNPJ |
| nome | S | Descrição |
| tipo | S | Tipo de pessoa |
| data\_entrada | S | Data de entrada |
| cpf\_representante\_legal | S | CPF\* do representante legal |
| nome\_representante | S | Nome do representante legal |
| faixa\_etaria | S | Faixa etária |
| pais\_id | S | Código do País (BACEN) |
| qualificacao\_socio | O | Qualificação |
| qualificacao\_representante | O | Qualificação |
**Importante:**
**O campo cpf\_cnpj\_socio e cpf\_representante\_legal são descaracterizados conforme a regra abaixo:**
Ocultação de informações pessoais sigilosas como no caso do CPF, o qual deve ser
descaracterizado por meio da ocultação dos três primeiros dígitos e dos dois dígitos
verificadores, conforme orientação disposta no art. 129 § 2o da Lei no 13.473/2017 (LDO
2018\).
# Consultando CNPJ na API Comercial
Na API comercial você pode fazer uma consulta direta por um CNPJ em nossa base. Nesse endpoint você deve enviar o header `x_api_token` com o token que lhe foi enviado via e-mail.
Você também pode passar o token como um parâmetro na URL, exemplo:
`https://comercial.cnpj.ws/cnpj/27865757000102?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj/NUMERO_DO_CNPJ_SEM_CARACTERES_ESPECIAIS`
Exemplos de Requisição [#exemplos-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const empresa = await consultarCNPJ("27865757000102", token);
console.log(empresa);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pelo CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2023-11-11T03:00:00.000Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***189808**",
"nome": "AMAURI SERGIO SOARES",
"tipo": "Pessoa Física",
"data_entrada": "2022-02-11",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6209100",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.09-1",
"subclasse": "6209-1/00",
"descricao": "Suporte técnico, manutenção e outros serviços em tecnologia da informação"
},
{
"id": "6311900",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.11-9",
"subclasse": "6311-9/00",
"descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na Internet"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
},
{
"id": "9512600",
"secao": "S",
"divisao": "95",
"grupo": "95.1",
"classe": "95.12-6",
"subclasse": "9512-6/00",
"descricao": "Reparação e manutenção de equipamentos de comunicação"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atualizado_em": "2023-11-11T03:00:00.000Z",
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
},
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "9000073850",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 23,
"nome": "Rio Grande do Sul",
"sigla": "RS",
"ibge_id": 43
}
},
{
"inscricao_estadual": "0629985490214",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 11,
"nome": "Minas Gerais",
"sigla": "MG",
"ibge_id": 31
}
},
{
"inscricao_estadual": "819017430118",
"ativo": true,
"atualizado_em": "2023-11-20T03:00:00.000Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
],
"inscricoes_suframa": [],
"regimes_tributarios": [
{
"ano": 2021,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2020,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2019,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2018,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2017,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2016,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2015,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2014,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
}
]
}
}
```
# Consultando o Consumo de Requisições Mensais
Nesse endpoint é possível consultar a quantidade de requisições que foram feitas por mês. Você deve enviar o header `x_api_token` com o token ou passar o token por query string na URL.
Você também pode passar o token como um parâmetro na URL, exemplo:
`https://comercial.cnpj.ws/consumo?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/consumo`
**Atenção:** As consultas nesse endpoint também contam como uma requisição à API.
Exemplo de Requisição [#exemplo-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const consumo = await consultarCNPJ.consumo(token);
console.log(consumo);
}
```
[Mais informações](https://www.npmjs.com/package/consultar-cnpj)
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado:
```json
{
"filtros_disponiveis": ["ano", "mes"],
"filtros_aplicados": {},
"ordenacao": ["ano", "mes"],
"data": [
{
"mes": 9,
"ano": 2021,
"quantidade": 1,
"atualizado_em": "2021-09-29T20:41:55.144Z",
"cnpjws_usuario_id": "d046b852-XXXX-XXXX-XXXX-8dccdf11d417"
}
]
}
```
# Consultando pela Raiz do CNPJ
Na API comercial você também pode fazer uma consulta utilizando a raiz do CNPJ, que são os 8 primeiros dígitos do CNPJ e que, nesse caso, irá retornar todos os CNPJs da empresa em questão. Nesse endpoint, você deve enviar o header `x_api_token` com o token que lhe foi enviado via e-mail.
Você também pode passar o token como um parâmetro na URL, exemplo:
`https://comercial.cnpj.ws/cnpj-raiz/27865757?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj-raiz/RAIZ_DO_CNPJ`
Exemplo de Requisição [#exemplo-de-requisição]
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getRaiz() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const data = await consultarCNPJ.raiz("27865757", token);
console.log(data);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Paginação [#paginação]
Caso a empresa possua mais de 20 filiais a API irá dividir a resposta em páginas. Você pode verificar isso no JSON de retono da API, na propriedade "paginacao", que exibe a página atual, o total de páginas e o total de filiais:
```json
{
"paginacao": {
"limite": 20,
"pagina": 1,
"paginas": 5,
"total": 87
}
}
```
Para buscar uma página específica basta informar o número da página na requisição:
```shell
curl -X GET https://comercial.cnpj.ws/cnpj-raiz/27865757?page=2 -H "x_api_token: SEU_TOKEN"
```
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pela raiz do CNPJ **27865757**:
```json
{
"data": [
"27865757002148",
"27865757002229",
"27865757002300",
"27865757002490",
"27865757002571",
"27865757002652",
"27865757002733",
"27865757002814",
"27865757002903",
"27865757003039",
"27865757003110",
"27865757003209",
"27865757003381",
"27865757003462",
"27865757003543",
"27865757003624",
"27865757003705",
"27865757003896",
"27865757003977",
"27865757004000"
],
"paginacao": {
"limite": 20,
"pagina": 2,
"paginas": 5,
"total": 87
},
"ordenacao": [],
"filtros_disponiveis": ["nome_fantasia", "pais_id", "estado_id", "cidade_id"],
"filtros_aplicados": {}
}
```
# API Comercial
Esta sessão contém documentação detalhada sobre a API Comercial, que oferece várias funcionalidades relacionadas à consulta de CNPJs, consumo de API e validação de inscrições no Suframa. Aqui estão os arquivos contidos:
* **Consultando CNPJ na API Comercial**: Guia sobre como consultar informações de CNPJ na API Comercial.
* **Consultando o Consumo de Requisições Mensais**: Instruções para consultar o consumo de requisições mensais.
* **Consultando pela Raiz do CNPJ**: Explicação sobre como consultar a raiz do CNPJ e retornar todas as filiais associadas.
* **Pesquisa de Empresas**: Informações sobre como realizar pesquisas de empresas utilizando filtros.
* **Validando Inscrição no Suframa**: Detalhes sobre a validação de inscrições no Suframa.
Esses arquivos oferecem exemplos de uso, incluindo código em diferentes linguagens, e descrevem as respostas retornadas pela API.
# Pesquisa de Empresas
Na API Comercial, no `Plano Premium`, você consegue fazer pesquisas utilizando filtros para encontrar empresas que atendam aos seus requisitos. Essa pesquisa é feita com **paginação baseada em cursor**.
**Atenção:** O acesso a esse endpoint é exclusivo para assinantes do Plano Premium.
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/v2/pesquisa?ADICIONE_OS_FILTROS`
Filtros [#filtros]
Você pode utilizar os filtros abaixo em suas consultas:
| Campo | Descrição |
| ------------------------------ | ----------------------------------------------------------------------- |
| atividade\_principal\_id | Código CNAE |
| atividade\_secundaria\_id | Código CNAE |
| atividade\_id | Código CNAE (pesquisa na atividade principal e secundária) |
| natureza\_juridica\_id | Código da Natureza Jurídica |
| razao\_social | Razão Social |
| nome\_fantasia | Nome Fantasia |
| pais\_id | Código do País do BACEN |
| estado\_id | Código IBGE do estado |
| cidade\_id | Código IBGE da Cidade |
| cep | CEP |
| situacao\_cadastral | Situação cadastral na Receita Federal |
| data\_situacao\_cadastral\_de | Data da Situação Cadastral (A partir dessa data) no formato YYYY-MM-DD |
| data\_situacao\_cadastral\_ate | Data da Situação Cadastral (Até essa data) no formato YYYY-MM-DD |
| porte\_id | Id do porte da empresa |
| socio\_nome | Nome do Sócio |
| data\_inicio\_atividade\_de | Data de Inicio de Atividade (A partir dessa data) no formato YYYY-MM-DD |
| data\_inicio\_atividade\_ate | Data de Inicio de Atividade (Até essa data) no formato YYYY-MM-DD |
É crucial destacar que as consultas realizadas neste endpoint baseiam-se em nosso banco de dados e não no da Receita Federal. Portanto, podem ocorrer discrepâncias entre as informações, já que nosso banco de dados pode ter uma defasagem de até 45 dias em relação aos dados atualizados da Receita Federal. Vale ressaltar que, embora realizemos cadastros diariamente devido às consultas de CNPJ feitas na API, a defasagem ainda pode ocorrer.
**Lista de Situações Cadastrais:**
* Ativa
* Baixada
* Inapta
* Nula
* Suspensa
**Lista de Portes Cadastrados:**
| ID | Descrição |
| -- | ------------------------ |
| 00 | Não informado |
| 01 | Micro Empresa |
| 03 | Empresa de Pequeno Porte |
| 05 | Demais |
Exemplos de Requisição [#exemplos-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const page = 2;
const data = await consultarCNPJ.pesquisa(
{ atividade_principal_id: "6203100", estado_id: 28 },
token,
page
);
console.log(data);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Paginação por Cursor [#paginação-por-cursor]
Quando a pesquisa retorna mais de **20 CNPJs**, a API divide a resposta em múltiplas páginas utilizando **paginação baseada em cursor** (*cursor-based pagination*).
As informações de paginação são retornadas no objeto `paginacao` do JSON de resposta, que indica se existem páginas anteriores ou seguintes e fornece os **cursores necessários para continuar a navegação**.
```json
{
"paginacao": {
"limite": 20,
"total": 320430,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMTkxMDAiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
}
}
```
Como navegar entre as páginas [#como-navegar-entre-as-páginas]
Primeira página
* Na primeira requisição **não é necessário informar nenhum cursor**. A API retornará automaticamente a primeira página de resultados.
Próxima página
* Para obter a próxima página, utilize o valor retornado em `proximo_cursor` como parâmetro na próxima requisição:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9 -H "x_api_token: SEU_TOKEN"
```
A próxima página só estará disponível quando `tem_proxima_pagina` for `true`.
Página anterior
* Caso seja necessário retornar para a página anterior, utilize o valor de `cursor_anterior`:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor= -H "x_api_token: SEU_TOKEN"
```
A página anterior só estará disponível quando `tem_pagina_anterior` for `true`.
Também é possível alterar a quantidade de CNPJ's retornados, o padrão é 20 mas pode ser até 100:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?atividade_principal_id=6203100&limite=100 -H "x_api_token: SEU_TOKEN"
```
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se pesquisar pelo CNAE **6203100**:
```json
{
"paginacao": {
"limite": 20,
"total": 38876,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMjgwMDAxMjkiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMTA2NTcwMDAyMTAiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
},
"filtros_disponiveis": [
"atividade_principal_id",
"atividade_secundaria_id",
"atividade_id",
"natureza_juridica_id",
"razao_social",
"nome_fantasia",
"pais_id",
"estado_id",
"cidade_id",
"cep",
"situacao_cadastral",
"data_situacao_cadastral_de",
"data_situacao_cadastral_ate",
"porte_id",
"socio_nome",
"socio_cpf_cnpj",
"data_inicio_atividade_de",
"data_inicio_atividade_ate"
],
"filtros_aplicados": {
"atividade_principal_id": "6203100"
},
"data": [
"00000028000129",
"00000135000157",
"00000266000215",
"00000342000101",
"00000390000108",
"00000544000153",
"00000635000199",
"00000664000150",
"00001713000170",
"00001871000120",
"00001871000200",
"00002440000188",
"00003800000166",
"00003821000181",
"00004032000165",
"00004387000154",
"00007190000250",
"00009301000186",
"00010657000130",
"00010657000210"
]
}
```
# Validando Inscrição no Suframa
Na API Comercial é possível fazer consultas de uma inscrição no Suframa utilizando o método POST.
Lembre-se de enviar o CNPJ sem os caracteres especiais.
**Método:** `POST`
**Endpoint:** `https://comercial.cnpj.ws/suframa`
Exemplos de Requisição [#exemplos-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao, token);
console.log(empresa);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pelo CNPJ **61940292006682** e inscrição **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# Consultando CNPJ na API Pública
Na API pública é possível fazer até 3 consultas por minuto de um CNPJ utilizando o método GET. Essa consulta é feita apenas em nossa base de dados.
Lembre-se de enviar o CNPJ sem os caracteres especiais.
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/NUMERO_DO_CNPJ_SEM_CARACTERES_ESPECIAIS`
Exemplos de Requisição [#exemplos-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const empresa = await consultarCNPJ("27865757000102");
console.log(empresa);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pelo CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T05:41:44.884Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***720677**",
"nome": "MANZAR GOMES FERES",
"tipo": "Pessoa Física",
"data_entrada": "2021-04-26",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***617850**",
"nome": "CARLOS HENRIQUE SCHRODER",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***632567**",
"nome": "JORGE LUIZ DE BARROS NOBREGA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***030727**",
"nome": "MARCELO LUIS MENDES SOARES DA SILVA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***050187**",
"nome": "PEDRO BORGES GARCIA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***649137**",
"nome": "MANUEL LUIS ROQUETE CAMPELO BELMAR DA COSTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***492757**",
"nome": "RICARDO CAPILLE WADDINGTON",
"tipo": "Pessoa Física",
"data_entrada": "2021-06-24",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO SOMLIVRE GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2021-08-18T20:40:56.654Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
# API Pública
Esta sessão contém documentação sobre a API Pública, que permite a consulta de informações sobre empresas brasileiras com limites específicos de uso. Os documentos incluem:
* **Consultando CNPJ na API Pública**: Guia sobre como consultar informações de CNPJ na API Pública.
* **Limitações**: Informações sobre as limitações de uso da API Pública, como limites de requisições por minuto.
* **Validando Inscrição no Suframa na API Pública**: Detalhes sobre como validar inscrições no Suframa utilizando a API Pública.
Esses documentos são voltados para usuários que precisam de acesso público e limitado a informações empresariais.
# Limitações
A API Pública possui a limitação de atender apenas 3 requisições por minuto de um mesmo IP, entenda que essa limitação é independente ao fato de a consulta ter obtido sucesso ao encontrar o CNPJ. Após ultrapassar esse limite o requisitante terá que aguardar completar os 60 segundos para poder fazer a próxima requisição.
O usuário receberá uma mensagem de erro e HTTP Status Code 429:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 3 consultas por minuto. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
Caso a API identifique um volume anormal de erros — mais de 360 erros HTTP 429 na mesma hora, sinal de que o requisitante continua insistindo mesmo após ser bloqueado — o IP será penalizado e não poderá fazer consultas por 1 hora. Persistindo o comportamento, o bloqueio será renovado por mais 1 hora. Exemplo:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 360 erros HTTP 429 por hora. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
Omissão de dados pessoais [#omissão-de-dados-pessoais]
Alguns CNPJs podem retornar o campo `observacao` informando que parte dos dados foi omitida a pedido do responsável pela empresa. Campos sensíveis (endereço completo, contato, documentos de sócios, faixa etária etc.) vêm como `null` ou reduzidos, sem remover chaves do JSON. A API Comercial autenticada não aplica essa omissão.
# Validando Inscrição no Suframa na API Pública
Na API Pública é possível fazer até 3 consultas por minuto de uma inscrição no Suframa utilizando o método POST.
Lembre-se de enviar o CNPJ sem os caracteres especiais.
**Método:** `POST`
**Endpoint:** `https://publica.cnpj.ws/suframa`
Exemplos de Requisição [#exemplos-de-requisição]
Nós possuímos um pacote que pode te ajudar na integração com JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao);
console.log(empresa);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pelo CNPJ **61940292006682** e inscrição **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# Changelog
All notable changes to the API will be documented on this page.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
\[Unreleased] [#unreleased]
* Add IBAMA data to the Commercial API.
* Add latitude and longitude related to the company's address.
* Add information regarding active debt with the union.
\[1.0.5] 24/01/2022 [#105-24012022]
Added [#added]
* Tax Regimes
* Suframa Validation
\[1.0.4] - 27/12/2021 [#104---27122021]
Added [#added-1]
* Add data related to Suframa in the Commercial API.
\[1.0.3] - 02/10/2021 [#103---02102021]
Changed [#changed]
* Database resizing
Added [#added-2]
* Endpoint for request consumption query in the API
\[1.0.2] - 11/09/2021 [#102---11092021]
Fixed [#fixed]
Correction in the spelling of state registrations in JSON
inscricoes\_estatudais -> inscricoes\_estaduais
\[1.0.2] - 15/08/2021 [#102---15082021]
Changed [#changed-1]
The service was divided into 2 servers, one for the Public API and another for the Commercial API. Now the respective endpoints are as follows:
* Public API: ([https://publica.cnpj.ws](https://publica.cnpj.ws))
* Commercial API: ([https://comercial.cnpj.ws](https://comercial.cnpj.ws))
Until **01/09/2021** the old endpoint ([https://data.cnpj.ws](https://data.cnpj.ws)) will continue receiving requests, after this date it is necessary to migrate to one of the new endpoints.
\[1.0.1] - 10/08/2021 [#101---10082021]
Fixed [#fixed-1]
* Correction regarding state registrations of the state of Paraná to use the Sintegra format.
\[1.0.0] - 20/06/2021 [#100---20062021]
API production entry
# Overview
[](https://insomnia.rest/run/?label=CNPJ.ws\&uri=https%3A%2F%2Fwww.cnpj.ws%2Finsomnia.json)
The **CNPJ.ws** API provides simple and fast access to information about Brazilian companies through their CNPJ number. These data are obtained from public agencies such as SEFAZ, CADESP, Sintegra, and Suframa and are organized to deliver the most useful information, expanding the possibilities of utilizing these data.
Basic JSON Structure [#basic-json-structure]
The data is structured to provide the maximum amount of useful information, enabling integration with various systems.
Data Types Used:
| Abbreviation | Description |
| :----------: | ----------- |
| A | Array |
| S | String |
| D | Date |
| N | Number |
| O | Objct |
Below is the basic structure returned by the CNPJ API:
| Field | Type | Description |
| ----------------------------- | :--: | ----------------------------------------- |
| cnpj\_raiz | S | CNPJ Root |
| razao\_social | S | Company Name |
| capital\_social | S | Share Capital |
| responsavel\_federativo | S | Federative Responsible |
| criado\_em | S | Registration Date in the CNPJ.ws database |
| atualizado\_em | S | Last Update Date of the Information |
| porte | O | Company Size |
| natureza\_juridica | O | Legal Nature |
| qualificacao\_do\_responsavel | O | Qualification of the Responsible |
| socios | O | List of Partners |
| estabelecimento | O | Establishment |
| simples | O | Simples and MEI Data |
Data Lag [#data-lag]
The maximum data lag is 45 days, with daily integrations with the state Sintegras with which we have integration.
If you have any questions, we are here to support you! Send an email to [contato@cnpj.ws](mailto:contato@cnpj.ws)!
[](https://www.digitalocean.com/?refcode=58b7deafafad\&utm_campaign=Referral_Invite\&utm_medium=Referral_Program\&utm_source=badge)
# CNPJ Alfanumérico de Teste
Use o CNPJ de exemplo `UKPVME1E8HI996` para testar sua integração com o novo formato
A partir de julho de 2026 a Receita Federal poderá emitir novas inscrições no CNPJ no formato alfanumérico (com letras e números). Os cadastros existentes não serão alterados. Se quiser entender como o novo formato funciona e como calcular os dígitos verificadores, veja o artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
A API do CNPJ.ws já está preparada para o novo formato. Para ajudar quem está adaptando seus sistemas, criamos um **CNPJ alfanumérico de exemplo** que você pode usar para testar sua validação de dígitos verificadores e sua integração com a API antes que as inscrições reais entrem em circulação.
CNPJ de exemplo [#cnpj-de-exemplo]
```
UKPVME1E8HI996
```
Formatado, fica assim:
```
UK.PVM.E1E/8HI9-96
```
Repare na estrutura, que segue o mesmo padrão do CNPJ atual:
| Parte | Valor | Descrição |
| ----- | ---------- | ---------------------------------------------------------- |
| Raiz | `UKPVME1E` | Identifica a empresa (8 caracteres, alfanuméricos) |
| Ordem | `8HI9` | Identifica o estabelecimento (4 caracteres, alfanuméricos) |
| DV | `96` | Dígitos verificadores (2 caracteres, sempre numéricos) |
Os dígitos verificadores `96` foram calculados a partir dos doze primeiros caracteres usando o módulo 11, exatamente como descrito no artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico). Ou seja: é um CNPJ válido do ponto de vista do algoritmo, ideal para validar a sua implementação.
Testando a validação dos dígitos verificadores [#testando-a-validação-dos-dígitos-verificadores]
Se você implementou o cálculo dos DVs no seu sistema, rode o algoritmo sobre os doze primeiros caracteres (`UKPVME1E8HI9`) e confira se o resultado é `96`. Se bater, sua validação está correta.
Para conferir manualmente, basta substituir cada caractere pelo seu valor (ASCII − 48), aplicar os pesos de 2 a 9 da direita para a esquerda e tirar o resto da divisão por 11 — o passo a passo completo está no [artigo do cálculo](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
Testando na API CNPJ.ws [#testando-na-api-cnpjws]
O CNPJ de exemplo pode ser enviado diretamente para a API, **sem caracteres especiais** (sem pontos, barra ou traço).
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/UKPVME1E8HI996`
**Exemplo com cURL**
```shell
curl https://publica.cnpj.ws/cnpj/UKPVME1E8HI996
```
**Exemplo com JavaScript / Node.js**
Usando `fetch`:
```js
async function consultarCNPJ(cnpj) {
const resposta = await fetch(`https://publica.cnpj.ws/cnpj/${cnpj}`);
const dados = await resposta.json();
console.log(dados);
}
consultarCNPJ("UKPVME1E8HI996");
```
**Exemplo com o pacote `consultar-cnpj`**
Também mantemos o pacote oficial [`consultar-cnpj`](https://github.com/cnpj-ws/consultar-cnpj) ([npm](https://www.npmjs.com/package/consultar-cnpj)), que facilita a integração em Node.js. **A partir da versão 1.0.22 ele já aceita CNPJ alfanumérico**, então basta atualizar para a última versão:
```shell
yarn add consultar-cnpj
# ou
npm i consultar-cnpj --save
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
// O token é opcional — sem ele, usa a API Pública (3 consultas/min)
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
const empresa = await consultarCNPJ("UKPVME1E8HI996", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
getCNPJ();
```
> **Importante:** por se tratar de um CNPJ fictício, criado apenas para testes, ele **não retorna dados cadastrais de uma empresa real**. O objetivo é validar que sua aplicação aceita, trata e envia o formato alfanumérico corretamente em toda a cadeia — do formulário até a chamada da API. Para receber dados reais, utilize um CNPJ existente.
# CNPJ Alfanumérico
A partir de julho de 2026 a Receita Federal poderá emitir novas inscrições no CNPJ no formato alfanumérico (com letras e números), os cadastros existentes não serão alterados.
A API do CNPJ.ws já está preparada para esse novo formato e aceita consultas usando CNPJ alfanumérico.
Cálculo dos dígitos verificadores [#cálculo-dos-dígitos-verificadores]
O novo CNPJ alfanumérico é composto por 14 dígitos, como o atual, sendo os doze primeiros alfanuméricos e os dois restante, os dígitos verificadores, numéricos.
Os dígitos verificadores são calculados a partir dos doze primeiros dígitos em duas etapas, utilizando o módulo de divisão 11 e pesos distribuídos de 2 a 9.
Cálculo do primeiro dígito [#cálculo-do-primeiro-dígito--]
Para cada um dos caracteres do CNPJ, você deve atribuir o valor da coluna "Valor para cálculo do DV", conforme a tabela abaixo, ou subtrair 48 do "Valor ASCII":
| CNPJ Alfanumérico | Valor ASCII | Valor para cálculo do DV |
| ----------------- | ----------- | ------------------------ |
| 0 | 48 | 0 |
| 1 | 49 | 1 |
| 2 | 50 | 2 |
| 3 | 51 | 3 |
| 4 | 52 | 4 |
| 5 | 53 | 5 |
| 6 | 54 | 6 |
| 7 | 55 | 7 |
| 8 | 56 | 8 |
| 9 | 57 | 9 |
| A | 65 | 17 |
| B | 66 | 18 |
| C | 67 | 19 |
| D | 68 | 20 |
| E | 69 | 21 |
| F | 70 | 22 |
| G | 71 | 23 |
| H | 72 | 24 |
| I | 73 | 25 |
| J | 74 | 26 |
| K | 75 | 27 |
| L | 76 | 28 |
| M | 77 | 29 |
| N | 78 | 30 |
| O | 79 | 31 |
| P | 80 | 32 |
| Q | 81 | 33 |
| R | 82 | 34 |
| S | 83 | 35 |
| T | 84 | 36 |
| U | 85 | 37 |
| V | 86 | 38 |
| W | 87 | 39 |
| X | 88 | 40 |
| Y | 89 | 41 |
| Z | 90 | 42 |
Exemplo:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
Distribuir os pesos de 2 a 9 da direita para a esquerda (recomeçando depois do oitavo caractere), conforme o exemplo:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
Multiplicar valor e peso de cada coluna e somar todos os resultados:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Multi | 5 | 8 | 51 | 36 | 171 | 24 | 28 | 30 | 0 | 4 | 60 | 42 |
`5 + 8 + 51 + 36 + 171 + 24 +28 + 30 + 0 + 4 + 60 + 42 = 459`
Obter o resto da divisão do somatório por 11.
\
Se o resto da divisão for igual a 1 ou 0, o primeiro dígito será igual a 0 (zero).
\
Senão, o primeiro dígito será igual ao resultado de 11 – resto.
No exemplo:
\
Resto da divisão `459/11 = 8` então o primeiro dígito verificador é o `3` (resultado de `11-8`)
Cálculo do segundo dígito verificador [#cálculo-do-segundo-dígito-verificador]
Para o cálculo do segundo dígito é necessário acrescentar o primeiro DV ao final do CNPJ,
\
formando assim treze caracteres, e repetir os passos realizados para o primeiro dígito.
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E | 3 |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 | 3 |
| Peso | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Multi | 6 | 10 | 68 | 54 | 38 | 27 | 32 | 35 | 0 | 5 | 80 | 63 | 6 |
`6 + 10 + 68 + 54 + 38 + 27 + 32 + 35 + 0 + 5 + 80 + 63 + 6 = 424`
Resto da divisão `424/11 = 6` então o segundo dígito verificador é o `5` (resultado de 11-6)
Resultado final: `12.ABC.345/01DE-``35`
# CNPJ.ws Project
This project is a byproduct of **[Bitize](https://www.bitize.com.br/)**, a procurement management platform focused on finding good suppliers.
**[Bitize](https://www.bitize.com.br/)** is developing a tool for prospecting **Suppliers** and for this, a database with public information of Brazilian companies has been developed and is being enriched with information from various public agencies.
The focus of CNPJ.ws is to provide a fast, updated, and easy-to-use API that returns public data of Brazilian companies made available by the [Access to Information Law](http://www.planalto.gov.br/ccivil_03/_Ato2011-2014/2011/Lei/L12527.htm).
We have a public API because this information should be accessible to everyone.
The challenge now is to obtain data regarding state registrations. We already have data from some states ([see the states here](https://docs.cnpj.ws/modelos-de-dados/inscricoes-estaduais)) but the task is really complicated due to the lack of standardization among the states. We are working hard on this!
We will be posting updates here! See you soon!
# Como automatizar o cadastro de clientes com uma API de consulta CNPJ
Quantas vezes a sua equipe já digitou razão social, endereço, CNAE e inscrição estadual de um cliente novo — campo por campo — copiando do cartão CNPJ da Receita Federal? Além de lento, esse processo é a principal porta de entrada de erros cadastrais: um dígito trocado no CNPJ, um endereço desatualizado, uma razão social abreviada de forma diferente em cada sistema.
A boa notícia é que nada disso precisa ser manual. Com uma **API de consulta CNPJ**, o seu sistema pede apenas um dado ao usuário — o número do CNPJ — e preenche todo o resto sozinho, com informações oficiais e atualizadas. Neste post, mostramos como esse fluxo funciona, como implementá-lo com a API do CNPJ.ws e como um ERP brasileiro usa exatamente essa abordagem em produção.
O problema do cadastro manual [#o-problema-do-cadastro-manual]
Todo sistema que atende empresas — ERP, CRM, plataforma de cobrança, e-commerce B2B — precisa cadastrar pessoas jurídicas. No fluxo manual, isso significa um formulário com 10 a 20 campos que alguém preenche consultando documentos. Os custos aparecem em três frentes:
* **Tempo**: cada cadastro consome minutos de trabalho repetitivo, multiplicado por todos os clientes e fornecedores da base.
* **Erros**: digitação manual gera divergências que se propagam para notas fiscais, boletos e contratos — e retrabalho para corrigir.
* **Dados desatualizados**: a empresa muda de endereço ou de situação cadastral, e o cadastro no sistema continua com a informação antiga.
Como funciona uma API de consulta CNPJ [#como-funciona-uma-api-de-consulta-cnpj]
Uma API de consulta CNPJ expõe os dados públicos das empresas brasileiras em formato estruturado (JSON), pronto para ser consumido por qualquer aplicação. No caso do CNPJ.ws, uma única requisição HTTP retorna razão social, nome fantasia, situação cadastral, natureza jurídica, porte, endereço completo, CNAEs, quadro societário, inscrições estaduais e regime tributário (Simples Nacional/MEI).
O fluxo de automação tem três passos:
1\. O usuário informa só o CNPJ [#1-o-usuário-informa-só-o-cnpj]
No formulário de cadastro, o único campo obrigatório passa a ser o CNPJ. Vale validar os dígitos verificadores no front-end antes de consultar, evitando chamadas desnecessárias.
2\. O sistema consulta a API [#2-o-sistema-consulta-a-api]
```bash
curl https://publica.cnpj.ws/cnpj/00000000000191
```
A resposta traz o objeto completo da empresa. A API pública do CNPJ.ws permite até 3 consultas por minuto — suficiente para testar e para volumes baixos. Para uso em produção, a API comercial oferece limites maiores, dados adicionais e SLA.
3\. O formulário se preenche sozinho [#3-o-formulário-se-preenche-sozinho]
Com a resposta em mãos, o sistema popula todos os campos: razão social, endereço, CNAE principal, regime tributário. O usuário apenas confere e confirma. O que antes levava minutos passa a levar segundos — e os dados chegam exatamente como constam na base oficial.
Caso real: cadastro de clientes por IA no bitERP [#caso-real-cadastro-de-clientes-por-ia-no-biterp]
Um exemplo de quem usa esse fluxo em produção é o [bitERP, um ERP com inteligência artificial](https://www.biterp.ai), desenvolvido no Brasil. No bitERP, o usuário pode pedir no chat algo como *"cadastra o cliente CNPJ 00.000.000/0001-00"* — e o agente de IA consulta a API do CNPJ.ws, preenche o cadastro completo na tela e pede apenas a confirmação final.
A combinação é interessante porque junta duas automações: a IA elimina a navegação por menus e formulários, e a API de consulta CNPJ elimina a busca e digitação dos dados. O resultado é um onboarding de cliente que se resolve em uma única frase, com dados oficiais da Receita Federal — sem erro de digitação e sem cadastro incompleto.
O mesmo padrão se aplica a fornecedores, transportadoras e qualquer outra entidade PJ do sistema.
Boas práticas ao integrar [#boas-práticas-ao-integrar]
Para tirar o máximo da integração, vale seguir algumas recomendações:
* **Valide o CNPJ antes de consultar** — dígito verificador é cálculo local, não gaste requisição com número inválido.
* **Trate os limites de requisição** — implemente retry com backoff para o erro 429 e considere a API comercial para volume.
* **Guarde a data da consulta** — dados cadastrais mudam; saber quando o cadastro foi sincronizado permite programar atualizações periódicas.
* **Alerta de situação cadastral** — se a empresa constar como baixada, suspensa ou inapta, sinalize antes de concluir o cadastro. Isso evita emitir nota para CNPJ irregular.
* **Deixe o usuário revisar** — automação preenche, humano confirma. Especialmente campos que o cliente pode querer sobrescrever, como nome fantasia.
Comece agora [#comece-agora]
Você pode testar a consulta neste momento, sem cadastro: basta chamar `https://publica.cnpj.ws/cnpj/{número}` e ver o JSON retornado. Para levar a integração para produção, conheça os [planos da API comercial do CNPJ.ws](https://www.cnpj.ws/pt-BR#precos) — e se quiser ver o fluxo de cadastro automatizado funcionando dentro de um ERP, o exemplo do bitERP mostra até onde essa automação pode chegar.
# Consult CNPJ with PHP
PHP is one of the most used languages in web development and with it, it is very simple to make a query in the [CNPJ.ws](https://www.cnpj.ws/en-US) API.
With the integration, we can use the API to query the address, state registration, registration status, CNAE, and many other information that may be important when registering a customer or supplier through the CNPJ.
Public API [#public-api]
[CNPJ.ws](https://www.cnpj.ws/en-US) provides a public API for queries where you can make up to 3 queries per minute. [See the documentation](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
```php
How to search [#how-to-search]
To search, simply fill in the company's CNPJ in the CNPJ column (in the **"Consultas"** spreadsheet) and then click the **"Consult/Update"** button above:
After clicking the **"Consult/Update"** button, the spreadsheet will provide all the available data, simple right?
Remember that [CNPJ.ws](https://www.cnpj.ws/en-US) has a public API and you can consult CNPJs for free, just don't fill in the Token. However, the public API has a limitation of **3 queries per minute** ([see the documentation](https://docs.cnpj.ws/referencia-de-api/api-publica/limitacoes)), which makes the query a bit slow, but for a small volume of queries it can be viable.
If you need more speed or a larger volume of queries, check out [our plans](https://www.cnpj.ws/en-US#precos). We made a comparison, consulting 100 different CNPJs, with and without the token:
| Using the Token | Queries | Time |
| :-------------: | :-----: | :----------: |
| Yes | 100 | **00:00:57** |
| No | 100 | 00:34:40 |
[**Click here to download the Spreadsheet for Free**](https://www.cnpj.ws/ConsultaDadosEmpresariaisViaCNPJws.zip)
This spreadsheet is provided as an example only and does not represent an official CNPJ.ws product. Therefore, we do not offer support for Excel-related issues. Feel free to customize this example according to your needs. If you have any questions or suggestions, we are here to help! Contact us at: [contato@cnpj.ws](mailto:contato@cnpj.ws).
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
Best regards!
# Consult CNPJ for Free with Java
If you are looking for an efficient and free way to consult CNPJ data directly from your Java application, you have come to the right place! In this guide, we will explore how you can integrate your Java application with the [CNPJ.ws](https://www.cnpj.ws/en-US) API to access detailed information about companies registered with Receita Federal.
[CNPJ.ws](https://www.cnpj.ws/en-US) provides a public API for queries where you can make up to 3 queries per minute. [See the documentation](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
We will divide this tutorial into sections for easier understanding. Follow along!
Prerequisites [#prerequisites]
**Java**: Make sure you have the JDK installed on your machine.
**IDE**: A Java development environment, such as Eclipse or IntelliJ IDEA.
Setting Up the Environment [#setting-up-the-environment]
Create a new Java project in your favorite IDE.
Add the OkHttp library: We will use the OkHttp library to facilitate HTTP requests. Add the dependency to your pom.xml file if you are using Maven:
```xml
com.squareup.okhttp3
okhttp
4.9.0
```
Developing the Query Class [#developing-the-query-class]
Create a new Java class called ConsultaCNPJ. In this class, we will implement the method to perform the CNPJ query:
```java
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
public class ConsultaCNPJ {
private static final String URL_BASE = "https://publica.cnpj.ws/cnpj/";
//Caso use a API Comercial a URL é diferente, veja a doc:
public static void main(String[] args) {
try {
String cnpj = "27865757000102";
String jsonResponse = consultaCNPJ(cnpj);
System.out.println(jsonResponse);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String consultaCNPJ(String cnpj) throws IOException {
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url(URL_BASE + cnpj)
.get()
.build();
try (Response response = client.newCall(request).execute()) {
return response.body().string();
}
}
}
```
Explanation: [#explanation]
* **OkHttpClient**: We use this class to send HTTP requests.
* **Request**: Here we build our request, defining the URL with the CNPJ number we want to query.
* **Response**: We store the API response to process it later.
Testing the Query [#testing-the-query]
Run the ConsultaCNPJ class and check the console. You should see the JSON response containing detailed information about the queried CNPJ.
Conclusion [#conclusion]
In this guide, you learned how to perform CNPJ queries for free using the CNPJ.WS public API in a Java application. Use this functionality to enrich your Java projects with accurate and up-to-date business data.
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
See you soon!
# Consult CNPJ with Javascript and Node.JS
Consulting a CNPJ using the CNPJ.ws API with Javascript and Node.JS is very easy!
Keeping customer/supplier records up to date or even querying company data to facilitate some internal registration of your system is very common, and the CNPJ.ws API provides an easy and quick way to develop this integration.
With the integration, we can use the API to query the address, state registration, registration status, CNAE, and many other information that may be important when registering a customer or supplier through the CNPJ.
The data returned by the API is obtained from various public agencies (Receita Federal, Sintegra, SERPRO, Suframa, etc.), aggregated and organized to facilitate use by other systems through a Rest API.
Installation [#installation]
We have developed a package to facilitate this integration, see it on [Github](https://github.com/cnpj-ws/consultar-cnpj).
Remember that you can use our free API to consult CNPJ or you can purchase one of our commercial plans.
To get started, let's install the package:
Using YARN:
```shell
yarn add consultar-cnpj
```
Using NPM:
```shell
npm i consultar-cnpj --save
```
Usage [#usage]
CNPJ.ws has a Public API and a Commercial API. To use the Public API, you do not need a token, but you can only make up to 3 queries per minute. If you are using the Commercial API, you must pass the token as the second parameter in the query to use its benefits. You can see more details about the commercial plans on our [pricing page](https://www.cnpj.ws/en-US#precos).
```javascript
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
// O Token é opcional
const empresa = await consultarCNPJ("40154884000153", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
```
Return [#return]
Below is the JSON returned by the API:
```json
{
"cnpj_raiz": "40154884",
"razao_social": "STARLINK BRAZIL SERVICOS DE INTERNET LTDA.",
"capital_social": "800000.00",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T08:21:13.130Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2062",
"descricao": "Sociedade Empresária Limitada"
},
"qualificacao_do_responsavel": {
"id": 5,
"descricao": "Administrador "
},
"socios": [
{
"cpf_cnpj_socio": "***966178**",
"nome": "VITOR JAMES URNER",
"tipo": "Pessoa Física",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "71 a 80 anos",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "39523686000130",
"nome": "STARLINK BRAZIL HOLDING LTDA.",
"tipo": "Pessoa Jurídica",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***966178**",
"nome_representante": "VITOR JAMES URNER",
"faixa_etaria": "Não se aplica",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 22,
"descricao": "Sócio"
},
"qualificacao_representante": {
"id": 5,
"descricao": "Administrador "
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "40154884000153",
"atividades_secundarias": [
{
"id": "6190699",
"secao": "J",
"divisao": "61",
"grupo": "61.9",
"classe": "61.90-6",
"subclasse": "6190-6/99",
"descricao": "Outras atividades de telecomunicações não especificadas anteriormente"
},
{
"id": "6462000",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.62-0",
"subclasse": "6462-0/00",
"descricao": "Holdings de instituições não financeiras"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
}
],
"cnpj_raiz": "40154884",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "53",
"tipo": "Matriz",
"nome_fantasia": null,
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2020-12-18",
"data_inicio_atividade": "2020-12-18",
"nome_cidade_exterior": null,
"tipo_logradouro": "ALAMEDA",
"logradouro": "SANTOS",
"numero": "74",
"complemento": "ANDAR 7 CONJ 72 SALA 10",
"bairro": "CERQUEIRA CESAR",
"cep": "01418000",
"ddd1": "11",
"telefone1": "30229503",
"ddd2": null,
"telefone2": null,
"ddd_fax": null,
"fax": null,
"email": "VITOR@URNER.COM.BR",
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6130200",
"secao": "J",
"divisao": "61",
"grupo": "61.3",
"classe": "61.30-2",
"subclasse": "6130-2/00",
"descricao": "Telecomunicações por satélite"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
},
"cidade": {
"id": 3832,
"nome": "São Paulo",
"ibge_id": 3550308,
"siafi_id": "7107"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "130287771116",
"ativo": true,
"atualizado_em": "2021-08-25T16:59:58.589Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
Conclusion [#conclusion]
Using the CNPJ.ws API, you can obtain data from Brazilian companies in a simple and easy way. Take a look at our [documentation](https://docs.cnpj.ws/).
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
If you have any questions, we are here to support you. Send an email to [contato@cnpj.ws](mailto:contato@cnpj.ws)!
# Trigger to Consult CNPJ in Protheus
Registering customers or suppliers in Protheus can be easier if we consult the CNPJ in the [***CNPJ.ws***](https://www.cnpj.ws/en-US) API.
With the integration, we can use the API to query the address, state registration, registration status, CNAE, and many other information that may be important when registering a customer or supplier.
We have already created a class in ADVPL to integrate Protheus with [***CNPJ.ws***](https://www.cnpj.ws/en-US) in the post: [Consult CNPJ with ADVPL (Protheus)](https://docs.cnpj.ws/artigos/integracao-protheus).
In this post, we will use this ADVPL class to develop a trigger that we will use both in the customer registration and in the supplier registration. Remember that you can use our free API to consult CNPJ, but with a limitation of 3 queries per minute, or you can purchase one of our commercial plans.
Function getCNPJ [#function-getcnpj]
Let's start by creating a user function that we will call in our triggers. Note that it receives two parameters:
* cTab: SA1 or SA2, indicating whether we are working with customers or suppliers
* cCNPJ: the CNPJ number
We also handled the case using the `isBlind` function in case the trigger is called via execauto, without the user interface. And we used the `FWMsgRun` function so that the user has visual feedback and not just a "frozen" screen while the process is running.
```js
#include 'totvs.ch'
user function getCNPJ(cTab,cCNPJ)
local aArea:= getArea()
local cRet := ''
default cTab := 'SA1'
default cCNPJ:= ''
cCNPJ:= allTrim(cCNPJ)
if !empty(cTab) .and. len(cCNPJ) == 14
if isBlind()
cRet:= consulta(cTab,cCNPJ)
else
FWMsgRun(,{||cRet:= consulta(cTab,cCNPJ)},'CNPJ.ws','Consultando...')
endif
endif
restArea(aArea)
return cRet
```
Let's create a static function that will be responsible for communicating with [***CNPJ.ws***](https://www.cnpj.ws/en-US). You should review this code carefully to meet your company's needs. Here, I filled in all the fields that came to mind, but feel free to make changes:
```javascript
static function consulta(cTab,cCNPJ)
local oCNPJws:= CNPJws():new()
local oJSON := nil
local nX := 1
local cRet := ''
local lJob := isBlind()
local oModel := nil
default cTab := 'SA1'
default cCNPJ:= ''
if oCNPJws:consultarCNPJ(cCNPJ)
oJSON:= oCNPJws:getResponse()
cRet:= oJSON['razao_social']
if oJSON['estabelecimento']['situacao_cadastral'] <> 'Ativa'
if lJob
conout(cCNPJ + ': A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
else
alert('A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
endif
endif
if cTab == 'SA1'
M->A1_MSBLQL:= if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1')
If ExistTrigger('A1_MSBLQL')
RunTrigger(1,Nil,Nil,,'A1_MSBLQL')
Endif
M->A1_CNAE:= oJSON['estabelecimento']['atividade_principal']['id']
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+M->A1_CNAE))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
If ExistTrigger('A1_CNAE')
RunTrigger(1,Nil,Nil,,'A1_CNAE')
Endif
M->A1_PESSOA := 'J'
If ExistTrigger('A1_PESSOA')
RunTrigger(1,Nil,Nil,,'A1_PESSOA')
Endif
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH')+ '0' + oJSON['estabelecimento']['pais']['id'] ))
M->A1_CODPAIS := CCH->CCH_CODIGO
If ExistTrigger('A1_CODPAIS')
RunTrigger(1,Nil,Nil,,'A1_CODPAIS')
Endif
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
M->A1_PAIS := SYA->YA_CODGI
If ExistTrigger('A1_PAIS')
RunTrigger(1,Nil,Nil,,'A1_PAIS')
Endif
endif
endif
M->A1_NREDUZ := oJSON['estabelecimento']['nome_fantasia']
if empty(M->A1_NREDUZ) //Caso nao possua nome fantasia
M->A1_NREDUZ := avKey(cRet, 'A1_NREDUZ')
endif
If ExistTrigger('A1_NREDUZ')
RunTrigger(1,Nil,Nil,,'A1_NREDUZ')
Endif
M->A1_CEP := oJSON['estabelecimento']['cep']
If ExistTrigger('A1_CEP')
RunTrigger(1,Nil,Nil,,'A1_CEP')
Endif
M->A1_EST := oJSON['estabelecimento']['estado']['sigla']
If ExistTrigger('A1_EST')
RunTrigger(1,Nil,Nil,,'A1_EST')
Endif
M->A1_COD_MUN:= substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5)
If ExistTrigger('A1_COD_MUN')
RunTrigger(1,Nil,Nil,,'A1_COD_MUN')
Endif
M->A1_BAIRRO := oJSON['estabelecimento']['bairro']
If ExistTrigger('A1_BAIRRO')
RunTrigger(1,Nil,Nil,,'A1_BAIRRO')
Endif
M->A1_END := oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero']
If ExistTrigger('A1_END')
RunTrigger(1,Nil,Nil,,'A1_END')
Endif
M->A1_COMPLEM:= oJSON['estabelecimento']['complemento']
If ExistTrigger('A1_COMPLEM')
RunTrigger(1,Nil,Nil,,'A1_COMPLEM')
Endif
M->A1_DDD := oJSON['estabelecimento']['ddd1']
If ExistTrigger('A1_DDD')
RunTrigger(1,Nil,Nil,,'A1_DDD')
Endif
M->A1_TEL := oJSON['estabelecimento']['telefone1']
If ExistTrigger('A1_TEL')
RunTrigger(1,Nil,Nil,,'A1_TEL')
Endif
M->A1_FAX := oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax']
If ExistTrigger('A1_FAX')
RunTrigger(1,Nil,Nil,,'A1_FAX')
Endif
M->A1_EMAIL := oJSON['estabelecimento']['email']
If ExistTrigger('A1_EMAIL')
RunTrigger(1,Nil,Nil,,'A1_EMAIL')
Endif
if valType(oJSON['simples']) == 'J'
M->A1_SIMPNAC:= if(oJSON['simples']['simples'] == 'Sim', '1', '2')
else
M->A1_SIMPNAC:= '2'
endif
If ExistTrigger('A1_SIMPNAC')
RunTrigger(1,Nil,Nil,,'A1_SIMPNAC')
Endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
M->A1_INSCR:= oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual']
If ExistTrigger('A1_INSCR')
RunTrigger(1,Nil,Nil,,'A1_INSCR')
Endif
EXIT
endif
next
elseIf cTab == 'SA2'
//MATA020 está em MVC
oModel := FWModelActive()
oModel:SetValue('SA2MASTER','A2_MSBLQL' ,if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1'))
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+oJSON['estabelecimento']['atividade_principal']['id']))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
oModel:SetValue('SA2MASTER','A2_CNAE',oJSON['estabelecimento']['atividade_principal']['id'])
oModel:SetValue('SA2MASTER','A2_TIPO', 'J')
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH') + '0' + oJSON['estabelecimento']['pais']['id']))
oModel:SetValue('SA2MASTER','A2_CODPAIS', allTrim(CCH->CCH_CODIGO))
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
oModel:SetValue('SA2MASTER','A2_PAIS', allTrim(SYA->YA_CODGI))
endif
endif
if !empty(oJSON['estabelecimento']['nome_fantasia'])
oModel:SetValue('SA2MASTER','A2_NREDUZ',oJSON['estabelecimento']['nome_fantasia'])
else
oModel:SetValue('SA2MASTER','A2_NREDUZ',avKey(cRet, 'A2_NREDUZ'))
endif
oModel:SetValue('SA2MASTER','A2_CEP', oJSON['estabelecimento']['cep'])
oModel:SetValue('SA2MASTER','A2_EST', oJSON['estabelecimento']['estado']['sigla'])
oModel:SetValue('SA2MASTER','A2_COD_MUN', substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5))
oModel:SetValue('SA2MASTER','A2_BAIRRO', oJSON['estabelecimento']['bairro'])
oModel:SetValue('SA2MASTER','A2_END',oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero'])
oModel:SetValue('SA2MASTER','A2_COMPLEM', oJSON['estabelecimento']['complemento'])
oModel:SetValue('SA2MASTER','A2_DDD', oJSON['estabelecimento']['ddd1'])
oModel:SetValue('SA2MASTER','A2_TEL', oJSON['estabelecimento']['telefone1'])
oModel:SetValue('SA2MASTER','A2_FAX', oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax'])
oModel:SetValue('SA2MASTER','A2_EMAIL', oJSON['estabelecimento']['email'])
if valType(oJSON['simples']) == 'J'
oModel:SetValue('SA2MASTER','A2_SIMPNAC', if(oJSON['simples']['simples'] == 'Sim', '1', '2'))
else
oModel:SetValue('SA2MASTER','A2_SIMPNAC', '2')
endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
oModel:SetValue('SA2MASTER','A2_INSCR', oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual'])
EXIT
endif
next
endif
else
if lJob
conout('Erro ao consultar CNPJ: ' + oCNPJws:getError())
else
alert('Erro ao consultar CNPJ: ' + oCNPJws:getError())
endif
endif
return cRet
```
Trigger A1_CGC [#trigger-a1_cgc]
Below is the configuration of the trigger for the A1\_CGC field, where we call the user function `u_getcnpj` passing as parameters **SA1** and the CNPJ:
Trigger A2_CGC [#trigger-a2_cgc]
Below is the configuration of the trigger for the A2\_CGC field, where we call the user function `u_getcnpj` passing as parameters **SA2** and the CNPJ:
Conclusion [#conclusion]
The result should be as shown in the gif below. When you type the CNPJ, Protheus will query [***CNPJ.ws***](https://www.cnpj.ws/en-US) and automatically fill in the fields:
You can check the source code of this project on [GitHub](https://github.com/cnpj-ws/protheus), the mentioned class is also in this repository.
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
See you soon!
# Consult CNPJ with ADVPL (Protheus)
The Totvs Protheus system is the leading ERP in the Brazilian market and can be easily and simply integrated with the CNPJ.ws API to consult customers or suppliers through the CNPJ.
Protheus uses Totvs' proprietary language, ADVPL (Advanced Protheus Language), which is a standard xBase programming language (Clipper, Visual Objects, and later Fivewin).
For this integration, we will build a generic communication class that can be used in various types of projects. You can also find this project on [GitHub](https://github.com/cnpj-ws/protheus).
Remember that you can use our free API to consult CNPJ, but with a limitation of 3 queries per minute, or you can purchase one of our commercial plans.
With the integration, we can use the API to query the address, state registration, registration status, CNAE, and many other information that may be important when registering a customer or supplier, a legal entity, through the CNPJ.
Integration of CNPJ.ws with Totvs Protheus ERP [#integration-of-cnpjws-with-totvs-protheus-erp]
Let's get started, below is the class declaration:
```javascript title="/src/cnpjws.prw"
#include 'totvs.ch'
#include 'protheus.ch'
class CNPJws
data lVerb as Logical
data cURL as String
data cToken as String
data cErro as String
data cRet as String
data oRet as String
data aHeaders as Array
data lRet as Logical
method new() CONSTRUCTOR
method consoleLog(cMsg,lErro)
method setError(oRest)
method consultarCNPJ(cCNPJ)
method getResponse()
method getError()
endClass
```
We will have 6 methods in our class:
* **new**: Responsible for instantiating the class;
* **setError**: Internal method for generating errors;
* **consultarCNPJ**: Responsible for querying the CNPJ using the CNPJ.ws API;
* **getResponse**: Returns the API response in JSON format;
* **getError**: Returns the error message;
Now let's develop the `new` method, which is our constructor method. Note that this method receives the
parameter `lTest` (the default value is false) and yes, we will run tests with our integration class.
Also note that we have a **CN\_TOKEN** parameter, which we must create if we are using the Commercial API (without restrictions) and fill it with the Token that was sent to your email.
```javascript title="/src/cnpjws.prw"
method new(lTest) class CNPJws
default lTest:= .f.
::cToken := if(lTest, '', superGetMV('CN_TOKEN',.f.,''))
::cURL := if(empty(::cToken),'https://publica.cnpj.ws','https://comercial.cnpj.ws')
::lVerb := if(lTest, .t., superGetMV('CN_VERBO',.f.,.t.)) //Indica se ira imprimir todas as msgs no console
::cErro := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::aHeaders:= {"Content-Type: application/json; charset=utf-8"}
if !empty(::cToken)
aAdd(::aHeaders,'x_api_token: ' + allTrim(::cToken))
endif
::consoleLog('Classe instanciada com sucesso!')
return Self
```
In the `new` method we use the `consoleLog` method, so let's develop it now. This method aims to standardize the messages emitted by the class.
If the **CN\_VERBO** parameter is set to .T., the class will print all messages in the Protheus console.log.
```javascript title="/src/cnpjws.prw"
method consoleLog(cMsg,lErro) class CNPJws
local cLog:= ''
default cMsg := ''
default lErro:= .f.
if ::lVerb .or. lErro
cLog:= '[' + dtoc(date()) + ']'
cLog+= '[' + time() + ']'
cLog+= '[' + ProcName(1) + ']'
cLog+= '[' + cValToChar(ProcLine(1)) + ']'
cLog+= '['+allTrim(cMsg)+']'
if lErro
::cErro:= cLog
::lRet := .f.
endif
if ::lVerb .or. lErro
conout(cLog)
endif
endif
return
```
Below is the `setError` method used by the class to generate error messages:
```javascript title="/src/cnpjws.prw"
method setError(oRest,cPath) class CNPJws
local cLog := ''
local cAux := ''
local cStatus := ''
default cPath := ''
::oRet := nil
::cRet:= oRest:GetResult()
if valType(::cRet) <> 'C'
::cRet:= ''
endif
if !empty(::cRet)
::cRet:= FWNoAccent(DecodeUtf8(::cRet))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
endif
cAux:= FWNoAccent(DecodeUtf8(oRest:GetLastError()))
if empty(cAux)
cAux:= FWNoAccent(oRest:GetLastError())
endif
cStatus:= oRest:GetHTTPCode()
cLog+= 'Host: ' + ::cURL + CRLF
cLog+= 'Operacao: ' + ProcName(1) + ' ' + cPath + CRLF
cLog+= 'HTTP Code: ' + cStatus + CRLF
cLog+= 'Erro: ' + cAux + CRLF
cLog+= 'Resultado: ' + ::cRet + CRLF
::consoleLog(cLog,.T.)
return
```
Now, let's develop the method responsible for communicating with the CNPJ.ws API, the `consultarCNPJ` method. Here we will use the [FWREST](https://tdn.engpro.totvs.com.br/display/framework/FWRest?focusedCommentId=446697540) class to communicate with the API. This method receives the CNPJ as a parameter and performs the query in the API.
The method returns a boolean, if everything goes well it will return true, if an error occurs the return will be false, see below:
```javascript title="/src/cnpjws.prw"
method consultarCNPJ(cCNPJ) class CNPJws
local oRest := FWRest():New(::cURL)
local cPath := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::cErro:= ''
cPath+= allTrim(cCNPJ)
oRest:setPath(cPath)
if oRest:Get(::aHeaders)
if !empty(oRest:GetResult())
::cRet:= FWNoAccent(DecodeUtf8(oRest:GetResult()))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
::cRet:= strTran(::cRet,'\/','/')
::cRet:= strtran(::cRet,":null",': " "')
::cRet:= strtran(::cRet,'"self"','"_self"')
::oRet:= JsonObject():new()
::oRet:fromJson(::cRet)
::lRet := .t.
::cErro:= ''
else
::oRet := nil
::cErro:= ''
::lRet := .t.
endif
::consoleLog('Sucesso! ' + cPath)
else
::setError(oRest,cPath)
endif
FreeObj(oRest)
return ::lRet
```
Below we have the method responsible for returning the JSON that the ***[CNPJ.ws](https://www.cnpj.ws/en-US)*** API returned in the query:
```javascript title="/src/cnpjws.prw"
method getResponse() class CNPJws
return ::oRet
```
Below we have the method responsible for returning the error message if the query is not successful:
```javascript title="/src/cnpjws.prw"
method getError() class CNPJws
return ::cErro
```
Great, we have built our class, now is a good time to develop a routine to use our class:
```javascript title="/src/cnpjws.prw"
user function tstCNPJ()
local oCNPJ:= nil
local oJSON:= nil
RpcSetType(3)
if !RpcSetEnv('99','01')
return
endif
oCNPJ:= CNPJws():new()//Instancia a classe
if oCNPJ:consultarCNPJ('40154884000153')
oJSON:= oCNPJ:getResponse()
endif
RPCClearEnv()
return
```
If you need support to implement this integration in your environment, we recommend [Apply System](https://applysystem.com.br/site/), our partner, which has consultants specialized in system integration!
This post is quite long, isn't it? So I will leave a part 2 using TL++ to create a test for the integration class, but the source code is already on [GitHub](https://github.com/cnpj-ws/protheus) if you want to take a look!
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
See you soon!
# Keep Customer and Supplier Records Updated
Keeping your customer and supplier records always updated is a difficult but necessary task. Regardless of the size of your company, it is very important to have these records always updated, as they help standardize and control information about your business.
The CNPJ.ws API obtains data from various public agencies (Receita Federal, Sintegra, SERPRO, Suframa, etc.), aggregates and organizes this data to facilitate use by other systems through a Rest API.
In this way, you can obtain data on partners, CNAE, and state registrations in a simple and automated manner with a single API.
Take a look at our [documentation](https://docs.cnpj.ws/).
To learn more about our plans and payment methods, visit [CNPJ.ws](https://www.cnpj.ws/en-US#precos).
# What is CNPJ
The National Register of Legal Entities is the registration used by the Federal Revenue to open an institution with or without profit purposes, in order to monitor the financial movements of these organizations. Through the CNPJ, the company exists before the government and its operation in the market is legalized.
The CNPJ is composed of 14 numbers, with the first 8 being the company's registration, the next 4 demonstrating whether the institution is a headquarters or a branch. The number known as "mil contra", 0001, is used for headquarters, and the following numbers, 0002, 0003, and others, are used for branches. The last 2 numbers are the check digits. The standard for registration is: XX.XXX.XXX/000X-XX.
The functions of the document vary, and it can be used to prove the existence of the organization, issue invoices, hire suppliers or employees, take out loans, or make financing. For these reasons, it is not only companies that need the CNPJ; other institutions also benefit from this registration, such as churches, associations, NGOs, political parties, and others.
The information found in the National Register of Legal Entities includes the CNPJ number, the organization's opening date, the institution's name and trade name, the economic activities in which the company operates, address, and phone number. To obtain this registration, you need to submit an online application on the Federal Revenue website and fill out the registration form with the necessary documents.
To find a company's CNPJ, simply access the CNPJws website, an API developed to consult legal entity data. The platform offers 5 plans: Free, Basic, Intermediate, Advanced, and Premium.
# Economic Activities
Below is the data model for economic activities:
| Field | Type | Description |
| --------- | :--: | ----------- |
| id | S | ID |
| secao | S | Section |
| divisao | S | Division |
| grupo | S | Group |
| classe | S | Class |
| subclasse | S | Subclass |
| descricao | S | Description |
# Cities
Below is the data model for cities:
| Field | Type | Description |
| --------- | :--: | ----------- |
| id | N | ID |
| nome | S | City Name |
| ibge\_id | N | IBGE Code |
| siafi\_id | S | SIAFI Code |
Source: [https://www.ibge.gov.br/explica/codigos-dos-municipios.php](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)
# Establishments
Below is the data model for establishments:
Establishment [#establishment]
| Field | Type | Description |
| ------------------------- | :--: | ----------------------------- |
| cnpj | S | CNPJ |
| cnpj\_raiz | S | CNPJ Root |
| cnpj\_ordem | S | CNPJ Order |
| cnpj\_digito\_verificador | S | CNPJ Check Digit |
| tipo | S | Type (Branch or Headquarters) |
| nome\_fantasia | S | Trade Name |
| situacao\_cadastral | S | Registration Status |
| data\_situacao\_cadastral | D | Registration Status Date |
| data\_inicio\_atividade | D | Start Date of Activities |
| nome\_cidade\_exterior | S | City Name (Abroad) |
| pais | O | Country |
| estado | O | State |
| cidade | O | City |
| cep | S | ZIP Code |
| tipo\_logradouro | S | Street Type |
| logradouro | S | Street |
| numero | S | Number |
| complemento | S | Complement |
| bairro | S | Neighborhood |
| ddd1 | S | Area Code Phone 1 |
| telefone1 | S | Phone 1 |
| ddd2 | S | Area Code Phone 2 |
**Attention** Registrations in Suframa and Tax Regimes are only available in the Commercial API
# States
Below is the data model for states:
| Field | Type | Description |
| -------- | :--: | ------------- |
| id | N | ID |
| nome | S | State Name |
| sigla | S | State Acronym |
| ibge\_id | N | IBGE Code |
# Data Models
This section contains the documentation of the different data models returned by the APIs, detailing the fields and their descriptions. Includes:
* **Economic Activities**: Description of economic activity codes (CNAE).
* **Cities**: Information about cities, including IBGE codes.
* **Establishments**: Data about commercial establishments, such as addresses and registration statuses.
* **States**: Details of Brazilian states, with IBGE codes.
* **State Registrations**: Information about state registrations associated with CNPJs.
* **Suframa**: Documentation about Suframa registrations.
* **Error Messages**: List of possible error messages returned by the APIs.
* **Legal Natures**: Details about the legal natures of companies.
* **Countries**: Information about countries, with BACEN codes.
* **Company Sizes**: Descriptions of company sizes (ME, EPP, etc.).
* **Corporate Qualifications**: Details about partner qualifications.
* **Tax Regimes**: Information about company tax regimes.
* **Simples Nacional and MEI**: Data related to Simples Nacional and MEI.
* **Registration Statuses**: Details about the registration statuses of companies with the Federal Revenue.
* **Partners**: Information about company partners.
These documents are essential to understand the types of data that can be queried and received by the APIs.
# State Registrations
Below is the data model for state registrations:
| Field | Type | Description |
| ------------------- | :--: | ------------------- |
| inscricao\_estadual | S | State Registration |
| regime | S | Regime |
| ativo | B | Active Registration |
| estado | O | State |
**Attention** Currently, we are only returning state registrations for the states below:
* Bahia
* Espírito Santo
* Goiás
* Maranhão
* Mato Grosso do Sul
* Minas Gerais
* Paraíba
* Paraná
* Rio Grande do Sul
* São Paulo
* Sergipe
We are working to bring state registrations from other states!
# Suframa
Below is the data model for Suframa registrations:
| Field | Type | Description |
| ------------------ | :--: | -------------------- |
| inscricao\_suframa | S | Suframa Registration |
| ativo | B | Active Registration |
**Attention** Suframa registrations are only available in the Commercial API
# Error Messages
The API can return the following error codes:
| Code | Description |
| :--: | ----------------- |
| 400 | Invalid request |
| 401 | Unauthorized |
| 403 | Access denied |
| 404 | Not found |
| 429 | Too many requests |
| 500 | Internal error |
Below is the standard JSON model:
```json
{
"status": 400,
"title": "Invalid request",
"details": "Invalid CNPJ",
"validation": []
}
```
# Legal Natures
Below is the data model for legal natures:
| Field | Type | Description |
| --------- | :--: | --------------- |
| id | S | Legal Nature ID |
| descricao | S | Description |
# Countries
Below is the data model for countries:
| Field | Type | Description |
| --------- | :--: | ----------------- |
| id | S | BACEN Code |
| iso2 | S | Country Code ISO2 |
| iso3 | S | Country Code ISO3 |
| nome | S | Country Name |
| comex\_id | S | COMEX Code |
# Company Sizes
Below is the data model for company sizes:
| Field | Type | Description |
| --------- | :--: | ----------- |
| id | S | Size ID |
| descricao | S | Description |
List of registered sizes:
| ID | Description |
| -- | ---------------- |
| 00 | Not informed |
| 01 | Micro Enterprise |
| 03 | Small Business |
| 05 | Others |
# Corporate Qualifications
Below is the data model for corporate qualifications:
| Field | Type | Description |
| --------- | :--: | ---------------- |
| id | N | Qualification ID |
| descricao | S | Description |
# Tax Regimes
Starting in 2021, the RFB provides information on the tax regime of legal entities, disclosed annually.
The data is extracted from the Fiscal Accounting Bookkeeping (ECF). Rarely, when due to special situations or the existence of Partnerships in Participation (SCP), there is more than one bookkeeping submission in the year with different taxation forms or domicile in more than one city, there will be more than one record for the CNPJ.
Remember that legal entities opting for Simples Nacional, public agencies, autarchies, and public foundations are exempt from submitting the ECF. Inactive legal entities also do not need to send the ECF, provided they have not carried out any activity during the entire calendar year.
Below is the data model for tax regimes:
| Field | Type | Description |
| --------------------- | :--: | ------------------ |
| ano | S | Year of Assessment |
| regime\_tributario | S | Regime |
| forma\_de\_tributacao | S | Form of Taxation |
The Receita provides this data always in the year following the ECF submission.
**Attention** Information regarding tax regimes is only available in the Commercial API
# Simples Nacional and MEI
Below is the data model for Simples Nacional and MEI:
Simples Nacional [#simples-nacional]
| Field | Type | Description |
| ----------------------- | :--: | ------------------------------ |
| simples | S | Opting for Simples Nacional? |
| data\_opcao\_simples | S | Date of opting for Simples |
| data\_exclusao\_Simples | S | Date of exclusion from Simples |
| mei | S | Opting for MEI? |
| data\_opcao\_mei | S | Date of opting for MEI |
| data\_exclusao\_mei | S | Date of exclusion from MEI |
**Attention** This record is only filled if the company is MEI, Simples, or has been one of the two at some point.
# Registration Statuses
Below is the data model for registration statuses:
| Field | Type | Description |
| --------- | :--: | ----------- |
| id | N | Status ID |
| descricao | S | Description |
# Partners
Below is the data model for partners:
| Field | Type | Description |
| --------------------------- | :--: | --------------------------------- |
| cpf\_cnpj\_socio | S | CPF\* or CNPJ |
| nome | S | Description |
| tipo | S | Type of person |
| data\_entrada | S | Entry date |
| cpf\_representante\_legal | S | CPF\* of the legal representative |
| nome\_representante | S | Name of the legal representative |
| faixa\_etaria | S | Age range |
| pais\_id | S | Country Code (BACEN) |
| qualificacao\_socio | O | Qualification |
| qualificacao\_representante | O | Qualification |
**Important:** **The fields cpf\_cnpj\_socio and cpf\_representante\_legal are decharacterized according to the rule below:**
Hiding confidential personal information such as CPF, which must be decharacterized by hiding the first three digits and the two check digits, according to the guidance provided in art. 129 § 2 of Law No. 13.473/2017 (LDO 2018).
# Consulting CNPJ in the Commercial API
In the commercial API, you can directly query a CNPJ in our database. In this endpoint, you must send the `x_api_token` header with the token that was sent to you via email.
You can also pass the token as a parameter in the URL, example:
`https://comercial.cnpj.ws/cnpj/27865757000102?token=YOUR_TOKEN`
**Method:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj/CNPJ_NUMBER_WITHOUT_SPECIAL_CHARACTERS`
Request Examples [#request-examples]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const empresa = await consultarCNPJ("27865757000102", token);
console.log(empresa);
}
```
[More information about the package](https://www.npmjs.com/package/consultar-cnpj)
Return Example [#return-example]
Below is an example of the JSON returned when searching for the CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2023-11-11T03:00:00.000Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***189808**",
"nome": "AMAURI SERGIO SOARES",
"tipo": "Pessoa Física",
"data_entrada": "2022-02-11",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6209100",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.09-1",
"subclasse": "6209-1/00",
"descricao": "Suporte técnico, manutenção e outros serviços em tecnologia da informação"
},
{
"id": "6311900",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.11-9",
"subclasse": "6311-9/00",
"descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na Internet"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
},
{
"id": "9512600",
"secao": "S",
"divisao": "95",
"grupo": "95.1",
"classe": "95.12-6",
"subclasse": "9512-6/00",
"descricao": "Reparação e manutenção de equipamentos de comunicação"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atualizado_em": "2023-11-11T03:00:00.000Z",
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
},
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "9000073850",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 23,
"nome": "Rio Grande do Sul",
"sigla": "RS",
"ibge_id": 43
}
},
{
"inscricao_estadual": "0629985490214",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 11,
"nome": "Minas Gerais",
"sigla": "MG",
"ibge_id": 31
}
},
{
"inscricao_estadual": "819017430118",
"ativo": true,
"atualizado_em": "2023-11-20T03:00:00.000Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
],
"inscricoes_suframa": [],
"regimes_tributarios": [
{
"ano": 2021,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2020,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2019,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2018,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2017,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2016,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2015,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2014,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
}
]
}
}
```
# Consulting Monthly Request Consumption
In this endpoint, you can check the number of requests made per month. You must send the `x_api_token` header with the token or pass the token via query string in the URL.
You can also pass the token as a parameter in the URL, example:
`https://comercial.cnpj.ws/consumo?token=YOUR_TOKEN`
**Method:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/consumo`
**Attention:** Queries to this endpoint also count as an API request.
Request Example [#request-example]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const consumo = await consultarCNPJ.consumo(token);
console.log(consumo);
}
```
[More information](https://www.npmjs.com/package/consultar-cnpj)
Return Example [#return-example]
Below is an example of the JSON returned:
```json
{
"filtros_disponiveis": ["ano", "mes"],
"filtros_aplicados": {},
"ordenacao": ["ano", "mes"],
"data": [
{
"mes": 9,
"ano": 2021,
"quantidade": 1,
"atualizado_em": "2021-09-29T20:41:55.144Z",
"cnpjws_usuario_id": "d046b852-XXXX-XXXX-XXXX-8dccdf11d417"
}
]
}
```
# Consulting by CNPJ Root
In the commercial API, you can also query using the CNPJ root, which are the first 8 digits of the CNPJ and, in this case, will return all CNPJs of the company in question. In this endpoint, you must send the `x_api_token` header with the token that was sent to you via email.
You can also pass the token as a parameter in the URL, example:
`https://comercial.cnpj.ws/cnpj-raiz/27865757?token=YOUR_TOKEN`
**Method:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj-raiz/CNPJ_ROOT`
Request Example [#request-example]
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getRaiz() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const data = await consultarCNPJ.raiz("27865757", token);
console.log(data);
}
```
[Mais informações do pacote](https://www.npmjs.com/package/consultar-cnpj)
Paginação [#paginação]
Caso a empresa possua mais de 20 filiais a API irá dividir a resposta em páginas. Você pode verificar isso no JSON de retono da API, na propriedade "paginacao", que exibe a página atual, o total de páginas e o total de filiais:
```json
{
"paginacao": {
"limite": 20,
"pagina": 1,
"paginas": 5,
"total": 87
}
}
```
Para buscar uma página específica basta informar o número da página na requisição:
```shell
curl -X GET https://comercial.cnpj.ws/cnpj-raiz/27865757?page=2 -H "x_api_token: SEU_TOKEN"
```
Exemplo de Retorno [#exemplo-de-retorno]
Abaixo um exemplo do JSON retornado ao se buscar pela raiz do CNPJ **27865757**:
```json
{
"data": [
"27865757002148",
"27865757002229",
"27865757002300",
"27865757002490",
"27865757002571",
"27865757002652",
"27865757002733",
"27865757002814",
"27865757002903",
"27865757003039",
"27865757003110",
"27865757003209",
"27865757003381",
"27865757003462",
"27865757003543",
"27865757003624",
"27865757003705",
"27865757003896",
"27865757003977",
"27865757004000"
],
"paginacao": {
"limite": 20,
"pagina": 2,
"paginas": 5,
"total": 87
},
"ordenacao": [],
"filtros_disponiveis": ["nome_fantasia", "pais_id", "estado_id", "cidade_id"],
"filtros_aplicados": {}
}
```
# API - Commercial
This section contains detailed documentation about the Commercial API, which offers various functionalities related to CNPJ queries, API consumption, and Suframa registration validation. Here are the included files:
* **Consulting CNPJ in the Commercial API**: Guide on how to query CNPJ information in the Commercial API.
* **Consulting Monthly Request Consumption**: Instructions for checking monthly request consumption.
* **Consulting by CNPJ Root**: Explanation on how to query by CNPJ root and return all associated branches.
* **Company Search**: Information on how to perform company searches using filters.
* **Validating Suframa Registration**: Details on validating Suframa registrations.
These files provide usage examples, including code in different languages, and describe the responses returned by the API.
# Company Search
In the Commercial API, in the `Premium Plan`, you can perform searches using filters to find companies that meet your requirements.
**Attention:** Access to this endpoint is exclusive to Premium Plan subscribers.
**Method:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/v2/pesquisa?ADD_FILTERS`
Filters [#filters]
You can use the filters below in your queries:
| Field | Description |
| ------------------------------ | --------------------------------------------------------------- |
| atividade\_principal\_id | CNAE Code |
| atividade\_secundaria\_id | CNAE Code |
| atividade\_id | CNAE Code (search in the primary and secondary activity) |
| natureza\_juridica\_id | Legal Nature Code |
| razao\_social | Company Name |
| nome\_fantasia | Trade Name |
| pais\_id | BACEN Country Code |
| estado\_id | IBGE State Code |
| cidade\_id | IBGE City Code |
| cep | ZIP Code |
| situacao\_cadastral | Registration status with the Federal Revenue |
| data\_situacao\_cadastral\_de | Registration Status Date (From this date) in YYYY-MM-DD format |
| data\_situacao\_cadastral\_ate | Registration Status Date (Until this date) in YYYY-MM-DD format |
| porte\_id | Company size ID |
| socio\_nome | Partner's Name |
| data\_inicio\_atividade\_de | Start Date of Activity (From this date) in YYYY-MM-DD format |
| data\_inicio\_atividade\_ate | Start Date of Activity (Until this date) in YYYY-MM-DD format |
It is crucial to highlight that the queries made in this endpoint are based on our database and not on the Federal Revenue database. Therefore, discrepancies may occur between the information, as our database may have a lag of up to 45 days compared to the updated data from the Federal Revenue. It is worth noting that, although we perform daily registrations due to CNPJ queries made in the API, the lag can still occur.
**List of Registration Statuses:**
* Active
* Closed
* Inactive
* Null
* Suspended
**List of Registered Sizes:**
| ID | Description |
| -- | ---------------- |
| 00 | Not informed |
| 01 | Micro Enterprise |
| 03 | Small Business |
| 05 | Others |
Request Examples [#request-examples]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const page = 2;
const data = await consultarCNPJ.pesquisa(
{ atividade_principal_id: "6203100", estado_id: 28 },
token,
page
);
console.log(data);
}
```
[More information about the package](https://www.npmjs.com/package/consultar-cnpj)
Cursor-based Pagination [#cursor-based-pagination]
When the search returns more than **20 CNPJs**, the API splits the response into multiple pages using **cursor-based pagination**.
The pagination information is returned in the `paginacao` object of the JSON response, which indicates whether there are previous or next pages and provides the **cursors needed to keep navigating**:
```json
{
"paginacao": {
"limite": 20,
"total": 320430,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMTkxMDAiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
}
}
```
**First page**
On the first request you do **not** need to provide any cursor — the API automatically returns the first page of results.
**Next page**
To get the next page, use the value returned in `proximo_cursor` as the `cursor` parameter of the next request:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9 -H "x_api_token: YOUR_TOKEN"
```
The next page is only available when `tem_proxima_pagina` is `true`.
**Previous page**
If you need to go back to the previous page, use the value of `cursor_anterior`:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor= -H "x_api_token: YOUR_TOKEN"
```
The previous page is only available when `tem_pagina_anterior` is `true`.
It is also possible to change the number of CNPJs returned, the default is 20 but it can be up to 100:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?atividade_principal_id=6203100&limite=100 -H "x_api_token: YOUR_TOKEN"
```
Return Example [#return-example]
Below is an example of the JSON returned when searching by CNAE **6203100**:
```json
{
"paginacao": {
"limite": 20,
"total": 38876,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMjgwMDAxMjkiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMTA2NTcwMDAyMTAiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
},
"filtros_disponiveis": [
"atividade_principal_id",
"atividade_secundaria_id",
"atividade_id",
"natureza_juridica_id",
"razao_social",
"nome_fantasia",
"pais_id",
"estado_id",
"cidade_id",
"cep",
"situacao_cadastral",
"data_situacao_cadastral_de",
"data_situacao_cadastral_ate",
"porte_id",
"socio_nome",
"socio_cpf_cnpj",
"data_inicio_atividade_de",
"data_inicio_atividade_ate"
],
"filtros_aplicados": {
"atividade_principal_id": "6203100"
},
"data": [
"00000028000129",
"00000135000157",
"00000266000215",
"00000342000101",
"00000390000108",
"00000544000153",
"00000635000199",
"00000664000150",
"00001713000170",
"00001871000120",
"00001871000200",
"00002440000188",
"00003800000166",
"00003821000181",
"00004032000165",
"00004387000154",
"00007190000250",
"00009301000186",
"00010657000130",
"00010657000210"
]
}
```
# Validating Suframa Registration
In the Commercial API, it is possible to query a Suframa registration using the POST method.
Remember to send the CNPJ without special characters.
**Method:** `POST`
**Endpoint:** `https://comercial.cnpj.ws/suframa`
Request Examples [#request-examples]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao, token);
console.log(empresa);
}
```
[More information about the package](https://www.npmjs.com/package/consultar-cnpj)
Return Example [#return-example]
Below is an example of the JSON returned when searching for the CNPJ **61940292006682** and registration **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# Consulting CNPJ in the Public API
In the public API, you can make up to 3 queries per minute of a CNPJ using the GET method. This query is made only in our database.
Remember to send the CNPJ without special characters.
**Method:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/CNPJ_NUMBER_WITHOUT_SPECIAL_CHARACTERS`
Request Examples [#request-examples]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const empresa = await consultarCNPJ("27865757000102");
console.log(empresa);
}
```
[More information about the package](https://www.npmjs.com/package/consultar-cnpj)
Return Example [#return-example]
Below is an example of the JSON returned when searching for the CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T05:41:44.884Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***720677**",
"nome": "MANZAR GOMES FERES",
"tipo": "Pessoa Física",
"data_entrada": "2021-04-26",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***617850**",
"nome": "CARLOS HENRIQUE SCHRODER",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***632567**",
"nome": "JORGE LUIZ DE BARROS NOBREGA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***030727**",
"nome": "MARCELO LUIS MENDES SOARES DA SILVA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***050187**",
"nome": "PEDRO BORGES GARCIA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***649137**",
"nome": "MANUEL LUIS ROQUETE CAMPELO BELMAR DA COSTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***492757**",
"nome": "RICARDO CAPILLE WADDINGTON",
"tipo": "Pessoa Física",
"data_entrada": "2021-06-24",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO SOMLIVRE GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2021-08-18T20:40:56.654Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
# API - Public
This section contains documentation about the Public API, which allows querying information about Brazilian companies with specific usage limits. The documents include:
* **Consulting CNPJ in the Public API**: Guide on how to query CNPJ information in the Public API.
* **Limitations**: Information about the usage limitations of the Public API, such as request limits per minute.
* **Validating Suframa Registration in the Public API**: Details on how to validate Suframa registrations using the Public API.
These documents are intended for users who need public and limited access to company information.
# Limitations
The Public API has a limitation of serving only 3 requests per minute from the same IP. Understand that this limitation is independent of whether the query was successful in finding the CNPJ. After exceeding this limit, the requester will have to wait for 60 seconds to make the next request.
The user will receive an error message and HTTP Status Code 429:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 3 consultas por minuto. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
If the API detects an abnormal volume of errors — more than 360 HTTP 429 errors within the same hour, a sign that the requester keeps retrying even after being blocked — the IP will be penalized and will not be able to make queries for 1 hour. If the behavior persists, the block will be renewed for another hour. Example:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 360 erros HTTP 429 por hora. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
Personal data omission [#personal-data-omission]
Some CNPJs may return the `observacao` field stating that part of the data was omitted at the request of the company representative. Sensitive fields (full address, contact details, partner documents, age range, etc.) are returned as `null` or reduced, without removing JSON keys. The authenticated Commercial API does not apply this omission.
# Validating Suframa Registration in the Public API
In the Public API, you can make up to 3 queries per minute of a Suframa registration using the POST method.
Remember to send the CNPJ without special characters.
**Method:** `POST`
**Endpoint:** `https://publica.cnpj.ws/suframa`
Request Examples [#request-examples]
We have a package that can help you integrate with JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao);
console.log(empresa);
}
```
[More information about the package](https://www.npmjs.com/package/consultar-cnpj)
Return Example [#return-example]
Below is an example of the JSON returned when searching for the CNPJ **61940292006682** and registration **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# Alphanumeric CNPJ Test Example
Use the sample CNPJ `UKPVME1E8HI996` to test your integration with the new format
Starting in July 2026, Brazil's Federal Revenue Service (Receita Federal) may issue new CNPJ registrations in an alphanumeric format (with letters and numbers). Existing registrations will not be changed. If you want to understand how the new format works and how to calculate the check digits, see the article [Alphanumeric CNPJ](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
The CNPJ.ws API is already prepared for the new format. To help everyone adapting their systems, we created a **sample alphanumeric CNPJ** that you can use to test your check-digit validation and your API integration before the real registrations start circulating.
Sample CNPJ [#sample-cnpj]
```
UKPVME1E8HI996
```
Formatted, it looks like this:
```
UK.PVM.E1E/8HI9-96
```
Note its structure, which follows the same pattern as the current CNPJ:
| Part | Value | Description |
| ------------ | ---------- | -------------------------------------------------------- |
| Root | `UKPVME1E` | Identifies the company (8 alphanumeric characters) |
| Order | `8HI9` | Identifies the establishment (4 alphanumeric characters) |
| Check digits | `96` | Verification digits (2 characters, always numeric) |
The check digits `96` were calculated from the first twelve characters using modulo 11, exactly as described in the [Alphanumeric CNPJ](https://docs.cnpj.ws/blog/cnpj-alfanumerico) article. In other words, it is a valid CNPJ from the algorithm's standpoint — ideal for validating your implementation.
Testing check-digit validation [#testing-check-digit-validation]
If you implemented the check-digit calculation in your system, run the algorithm over the first twelve characters (`UKPVME1E8HI9`) and verify that the result is `96`. If it matches, your validation is correct.
To check manually, replace each character with its value (ASCII − 48), apply weights from 2 to 9 from right to left, and take the remainder of the division by 11 — the full step-by-step is in the [calculation article](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
Testing on the CNPJ.ws API [#testing-on-the-cnpjws-api]
The sample CNPJ can be sent directly to the API, **without special characters** (no dots, slash, or dash).
**Method:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/UKPVME1E8HI996`
**cURL example**
```shell
curl https://publica.cnpj.ws/cnpj/UKPVME1E8HI996
```
**JavaScript / Node.js example**
Using `fetch`:
```js
async function lookupCNPJ(cnpj) {
const response = await fetch(`https://publica.cnpj.ws/cnpj/${cnpj}`);
const data = await response.json();
console.log(data);
}
lookupCNPJ("UKPVME1E8HI996");
```
**Example with the `consultar-cnpj` package**
We also maintain the official [`consultar-cnpj`](https://github.com/cnpj-ws/consultar-cnpj) package ([npm](https://www.npmjs.com/package/consultar-cnpj)), which makes integration in Node.js easier. **As of version 1.0.21 it already accepts alphanumeric CNPJ**, so just update to the latest version:
```shell
yarn add consultar-cnpj
# or
npm i consultar-cnpj --save
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
// The token is optional — without it, the Public API is used (3 requests/min)
const token = "ENTER YOUR ACCESS TOKEN";
try {
const company = await consultarCNPJ("UKPVME1E8HI996", token);
console.log(company);
} catch (e) {
console.log(e);
}
}
getCNPJ();
```
> **Important:** because this is a fictitious CNPJ created for testing only, it **does not return registration data for a real company**. The goal is to validate that your application accepts, handles, and sends the alphanumeric format correctly across the entire chain — from the form to the API call. To receive real data, use an existing CNPJ.
# Alphanumeric CNPJ
As of **July 2026**, the Brazilian Federal Revenue Service (Receita Federal) may issue new CNPJ registrations in an **alphanumeric format** (letters and numbers). Existing registrations will **not** be changed.
The **CNPJ.ws API** is already prepared for this new format and accepts queries using **alphanumeric CNPJ**.
Check Digit Calculation [#check-digit-calculation]
The new alphanumeric CNPJ is composed of **14 characters**, just like the current one:
* The **first 12 characters** are alphanumeric
* The **last 2 characters** are numeric **check digits**
The check digits are calculated from the first twelve characters in **two steps**, using **modulus 11** and weights distributed from **2 to 9**.
First Check Digit Calculation [#first-check-digit-calculation]
For each CNPJ character, you must assign the value from the **“Value for check digit calculation”** column according to the table below, or subtract **48 from the ASCII value**:
| Alphanumeric CNPJ | ASCII Value | Value for Check Digit Calculation |
| ----------------- | ----------- | --------------------------------- |
| 0 | 48 | 0 |
| 1 | 49 | 1 |
| 2 | 50 | 2 |
| 3 | 51 | 3 |
| 4 | 52 | 4 |
| 5 | 53 | 5 |
| 6 | 54 | 6 |
| 7 | 55 | 7 |
| 8 | 56 | 8 |
| 9 | 57 | 9 |
| A | 65 | 17 |
| B | 66 | 18 |
| C | 67 | 19 |
| D | 68 | 20 |
| E | 69 | 21 |
| F | 70 | 22 |
| G | 71 | 23 |
| H | 72 | 24 |
| I | 73 | 25 |
| J | 74 | 26 |
| K | 75 | 27 |
| L | 76 | 28 |
| M | 77 | 29 |
| N | 78 | 30 |
| O | 79 | 31 |
| P | 80 | 32 |
| Q | 81 | 33 |
| R | 82 | 34 |
| S | 83 | 35 |
| T | 84 | 36 |
| U | 85 | 37 |
| V | 86 | 38 |
| W | 87 | 39 |
| X | 88 | 40 |
| Y | 89 | 41 |
| Z | 90 | 42 |
Example:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Value | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
Distribute the weights from **2 to 9**, from **right to left** (restarting after the eighth character), as shown below:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Value | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Weight | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
Multiply the value by the weight for each column and sum all results:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Value | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Weight | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Product | 5 | 8 | 51 | 36 | 171 | 24 | 28 | 30 | 0 | 4 | 60 | 42 |
`5 + 8 + 51 + 36 + 171 + 24 +28 + 30 + 0 + 4 + 60 + 42 = 459`
Obtain the remainder of the division of the sum by **11**.\
If the remainder is **0 or 1**, the first check digit is **0**.\
Otherwise, the first check digit is **11 − remainder**.
In this example:\
Remainder of `459/11 = 8`, so the first check digit is `3` (result of `11-8`)
Second Check Digit Calculation [#second-check-digit-calculation]
To calculate the second check digit, append the **first check digit** to the end of the CNPJ, forming **13 characters**, and repeat the same steps used for the first digit.
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E | 3 |
|---|
| Value | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 | 3 |
| Weight | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Product | 6 | 10 | 68 | 54 | 38 | 27 | 32 | 35 | 0 | 5 | 80 | 63 | 6 |
`6 + 10 + 68 + 54 + 38 + 27 + 32 + 35 + 0 + 5 + 80 + 63 + 6 = 424`
Remainder of `424/11 = 6`, so the second check digit is **5** (result of `11 − 6`).
Final result: `12.ABC.345/01DE-``35`
# How to automate customer registration with a CNPJ lookup API
How many times has your team typed a new customer's legal name, address, economic activity (CNAE) and state registration — field by field — copying from the Federal Revenue's CNPJ card? Besides being slow, this process is the main entry point for registration errors: a wrong digit in the CNPJ, an outdated address, a legal name abbreviated differently in each system.
The good news is that none of this has to be manual. With a **CNPJ lookup API**, your system asks the user for a single piece of data — the CNPJ number — and fills in everything else on its own, with official and up-to-date information. In this post, we show how this flow works, how to implement it with the CNPJ.ws API, and how a Brazilian ERP uses exactly this approach in production.
The problem with manual registration [#the-problem-with-manual-registration]
Every system that serves companies — ERP, CRM, billing platform, B2B e-commerce — needs to register legal entities. In the manual flow, that means a form with 10 to 20 fields someone fills in while looking at documents. The costs show up on three fronts:
* **Time**: each registration consumes minutes of repetitive work, multiplied by every customer and supplier in the database.
* **Errors**: manual typing creates discrepancies that spread to invoices, payment slips and contracts — plus rework to fix them.
* **Outdated data**: the company changes its address or registration status, and the record in your system still holds the old information.
How a CNPJ lookup API works [#how-a-cnpj-lookup-api-works]
A CNPJ lookup API exposes public data about Brazilian companies in a structured format (JSON), ready to be consumed by any application. With CNPJ.ws, a single HTTP request returns the legal name, trade name, registration status, legal nature, company size, full address, economic activities (CNAEs), ownership structure, state registrations and tax regime (Simples Nacional/MEI).
The automation flow has three steps:
1\. The user provides only the CNPJ [#1-the-user-provides-only-the-cnpj]
In the registration form, the only required field becomes the CNPJ. It's worth validating the check digits on the front end before querying, avoiding unnecessary calls.
2\. The system queries the API [#2-the-system-queries-the-api]
```bash
curl https://publica.cnpj.ws/cnpj/00000000000191
```
The response carries the complete company object. The CNPJ.ws public API allows up to 3 queries per minute — enough for testing and for low volumes. For production use, the commercial API offers higher limits, additional data and an SLA.
3\. The form fills itself [#3-the-form-fills-itself]
With the response in hand, the system populates every field: legal name, address, primary CNAE, tax regime. The user only reviews and confirms. What used to take minutes now takes seconds — and the data arrives exactly as it appears in the official database.
Real case: AI-driven customer registration in bitERP [#real-case-ai-driven-customer-registration-in-biterp]
One example of this flow running in production is [bitERP, an ERP with artificial intelligence](https://www.biterp.ai), developed in Brazil. In bitERP, the user can ask in the chat something like *"register the customer with CNPJ 00.000.000/0001-00"* — and the AI agent queries the CNPJ.ws API, fills in the complete record on screen and only asks for the final confirmation.
The combination is interesting because it joins two automations: the AI removes the navigation through menus and forms, and the CNPJ lookup API removes the searching and typing of the data. The result is a customer onboarding that gets resolved in a single sentence, with official Federal Revenue data — no typos, no incomplete records.
The same pattern applies to suppliers, carriers and any other legal entity in the system.
Best practices when integrating [#best-practices-when-integrating]
To get the most out of the integration, here are a few recommendations:
* **Validate the CNPJ before querying** — the check digit is a local calculation, don't waste a request on an invalid number.
* **Handle the rate limits** — implement retry with backoff for the 429 error and consider the commercial API for volume.
* **Store the query date** — registration data changes; knowing when the record was synced lets you schedule periodic updates.
* **Registration status alert** — if the company is listed as closed, suspended or unfit, flag it before completing the registration. This avoids issuing invoices to an irregular CNPJ.
* **Let the user review** — automation fills in, a human confirms. Especially fields the customer may want to override, such as the trade name.
Get started now [#get-started-now]
You can test the query right now, with no sign-up: just call `https://publica.cnpj.ws/cnpj/{number}` and see the JSON returned. To take the integration to production, check out the [CNPJ.ws commercial API plans](https://www.cnpj.ws/en-US#precos) — and if you want to see the automated registration flow working inside an ERP, the bitERP example shows how far this automation can go.
# Registro de cambios
Todos los cambios notables en la API se documentarán en esta página.
El formato se basa en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
y este proyecto se adhiere a [Control de versiones semántico](https://semver.org/spec/v2.0.0.html).
\[No lanzado] [#no-lanzado]
* Agregar datos del IBAMA en la API Comercial.
* Agregar latitud y longitud correspondiente a la dirección de la empresa.
* Agregar información sobre la deuda activa con la unión.
\[1.0.5] 24/01/2022 [#105-24012022]
Añadido [#añadido]
\_ Regímenes Tributarios
\_ Validación Suframa
\[1.0.4] - 27/12/2021 [#104---27122021]
Añadido [#añadido-1]
* Agregar datos referentes a Suframa en la API Comercial.
\[1.0.3] - 02/10/2021 [#103---02102021]
Cambiado [#cambiado]
* Redimensionamiento de la Base de Datos
Añadido [#añadido-2]
* Endpoint para consulta de consumo de solicitudes en la API
\[1.0.2] - 11/09/2021 [#102---11092021]
Corregido [#corregido]
Corrección en la ortografía de las inscripciones estatales en el JSON
inscricoes\_estatudais -> inscricoes\_estaduais
\[1.0.2] - 15/08/2021 [#102---15082021]
Cambiado [#cambiado-1]
El servicio se dividió en 2 servidores, uno para la API Pública y otro para la API Comercial. Ahora los respectivos endpoints son los siguientes:
* API Pública: [https://publica.cnpj.ws](https://publica.cnpj.ws)
* API Comercial: [https://comercial.cnpj.ws](https://comercial.cnpj.ws)
Hasta el día **01/09/2021** el endpoint antiguo ([https://data.cnpj.ws](https://data.cnpj.ws)) seguirá recibiendo solicitudes, después de esa fecha es necesario migrar a uno de los nuevos endpoints.
\[1.0.1] - 10/08/2021 [#101---10082021]
Corregido [#corregido-1]
* Corrección referente a las inscripciones estatales del estado de Paraná para utilizar el formato de sintegra.
\[1.0.0] - 20/06/2021 [#100---20062021]
Entrada en producción de la API
# Visión General
[](https://insomnia.rest/run/?label=CNPJ.ws\&uri=https%3A%2F%2Fwww.cnpj.ws%2Finsomnia.json)
La API de **CNPJ.ws** proporciona, de manera simple y rápida, datos sobre empresas brasileñas a través del número de CNPJ. Estos datos se obtienen de organismos públicos como SEFAZ, CADESP, Sintegra, Suframa y se organizan para permitir la máxima cantidad de información útil, ampliando las posibilidades de uso de estos datos.
Estructura básica del JSON [#estructura-básica-del-json]
Los datos están estructurados para proporcionar la mayor cantidad de información útil, permitiendo la integración con diversos sistemas.
Tipos de datos utilizados:
| Sigla | Descripción |
| :---: | ----------- |
| A | Array |
| S | String |
| D | Fecha |
| N | Numérico |
| O | Objeto |
A continuación se muestra la estructura básica devuelta por la API de CNPJ:
| Campo | Tipo | Descripción |
| ----------------------------- | :--: | -------------------------------------------------- |
| cnpj\_raiz | S | Raíz del CNPJ |
| razao\_social | S | Razón social de la empresa |
| capital\_social | S | Capital social |
| responsavel\_federativo | S | Responsable federativo |
| criado\_em | S | Fecha de registro en la base de datos de CNPJ.ws |
| atualizado\_em | S | Fecha de la última actualización de la información |
| porte | O | Tamaño de la empresa |
| natureza\_juridica | O | Naturaleza jurídica |
| qualificacao\_do\_responsavel | O | Calificación del responsable |
| socios | O | Lista de Socios |
| estabelecimento | O | Establecimiento |
| simples | O | Datos del Simples y del MEI |
Desfase de los Datos [#desfase-de-los-datos]
El desfase máximo de los datos es de 45 días, y diariamente se realizan integraciones con los Sintegras estatales con los que tenemos integración.
¡Cualquier duda, estamos aquí para apoyarte! Envía un correo electrónico a [contacto@cnpj.ws](mailto:contacto@cnpj.ws)!
[](https://www.digitalocean.com/?refcode=58b7deafafad\&utm_campaign=Referral_Invite\&utm_medium=Referral_Program\&utm_source=badge)
# CNPJ Alfanumérico de Teste
Use o CNPJ de exemplo `UKPVME1E8HI996` para testar sua integração com o novo formato
A partir de julho de 2026 a Receita Federal poderá emitir novas inscrições no CNPJ no formato alfanumérico (com letras e números). Os cadastros existentes não serão alterados. Se quiser entender como o novo formato funciona e como calcular os dígitos verificadores, veja o artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
A API do CNPJ.ws já está preparada para o novo formato. Para ajudar quem está adaptando seus sistemas, criamos um **CNPJ alfanumérico de exemplo** que você pode usar para testar sua validação de dígitos verificadores e sua integração com a API antes que as inscrições reais entrem em circulação.
CNPJ de exemplo [#cnpj-de-exemplo]
```
UKPVME1E8HI996
```
Formatado, fica assim:
```
UK.PVM.E1E/8HI9-96
```
Repare na estrutura, que segue o mesmo padrão do CNPJ atual:
| Parte | Valor | Descrição |
| ----- | ---------- | ---------------------------------------------------------- |
| Raiz | `UKPVME1E` | Identifica a empresa (8 caracteres, alfanuméricos) |
| Ordem | `8HI9` | Identifica o estabelecimento (4 caracteres, alfanuméricos) |
| DV | `96` | Dígitos verificadores (2 caracteres, sempre numéricos) |
Os dígitos verificadores `96` foram calculados a partir dos doze primeiros caracteres usando o módulo 11, exatamente como descrito no artigo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico). Ou seja: é um CNPJ válido do ponto de vista do algoritmo, ideal para validar a sua implementação.
Testando a validação dos dígitos verificadores [#testando-a-validação-dos-dígitos-verificadores]
Se você implementou o cálculo dos DVs no seu sistema, rode o algoritmo sobre os doze primeiros caracteres (`UKPVME1E8HI9`) e confira se o resultado é `96`. Se bater, sua validação está correta.
Para conferir manualmente, basta substituir cada caractere pelo seu valor (ASCII − 48), aplicar os pesos de 2 a 9 da direita para a esquerda e tirar o resto da divisão por 11 — o passo a passo completo está no [artigo do cálculo](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
Testando na API CNPJ.ws [#testando-na-api-cnpjws]
O CNPJ de exemplo pode ser enviado diretamente para a API, **sem caracteres especiais** (sem pontos, barra ou traço).
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/UKPVME1E8HI996`
**Exemplo com cURL**
```shell
curl https://publica.cnpj.ws/cnpj/UKPVME1E8HI996
```
**Exemplo com JavaScript / Node.js**
Usando `fetch`:
```js
async function consultarCNPJ(cnpj) {
const resposta = await fetch(`https://publica.cnpj.ws/cnpj/${cnpj}`);
const dados = await resposta.json();
console.log(dados);
}
consultarCNPJ("UKPVME1E8HI996");
```
**Exemplo com o pacote `consultar-cnpj`**
Também mantemos o pacote oficial [`consultar-cnpj`](https://github.com/cnpj-ws/consultar-cnpj) ([npm](https://www.npmjs.com/package/consultar-cnpj)), que facilita a integração em Node.js. **A partir da versão 1.0.22 ele já aceita CNPJ alfanumérico**, então basta atualizar para a última versão:
```shell
yarn add consultar-cnpj
# ou
npm i consultar-cnpj --save
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
// O token é opcional — sem ele, usa a API Pública (3 consultas/min)
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
const empresa = await consultarCNPJ("UKPVME1E8HI996", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
getCNPJ();
```
> **Importante:** por se tratar de um CNPJ fictício, criado apenas para testes, ele **não retorna dados cadastrais de uma empresa real**. O objetivo é validar que sua aplicação aceita, trata e envia o formato alfanumérico corretamente em toda a cadeia — do formulário até a chamada da API. Para receber dados reais, utilize um CNPJ existente.
# CNPJ Alfanumérico
A partir de **julio de 2026**, la Receita Federal de Brasil podrá emitir nuevas inscripciones de CNPJ en un **formato alfanumérico** (letras y números). Las inscripciones existentes **no serán modificadas**.
La **API de CNPJ.ws** ya está preparada para este nuevo formato y acepta consultas utilizando **CNPJ alfanumérico**.
Cálculo de los dígitos verificadores [#cálculo-de-los-dígitos-verificadores]
El nuevo CNPJ alfanumérico está compuesto por **14 caracteres**, al igual que el actual:
* Los **primeros 12 caracteres** son alfanuméricos
* Los **últimos 2 caracteres** son **dígitos verificadores** numéricos
Los dígitos verificadores se calculan a partir de los primeros doce caracteres en **dos etapas**, utilizando el **módulo 11** y pesos distribuidos de **2 a 9**.
Cálculo del primer dígito verificador [#cálculo-del-primer-dígito-verificador]
Para cada carácter del CNPJ, se debe asignar el valor de la columna **“Valor para el cálculo del dígito verificador”** según la tabla siguiente, o restar **48 al valor ASCII**:
| CNPJ Alfanumérico | Valor ASCII | Valor para el cálculo del DV |
| ----------------- | ----------- | ---------------------------- |
| 0 | 48 | 0 |
| 1 | 49 | 1 |
| 2 | 50 | 2 |
| 3 | 51 | 3 |
| 4 | 52 | 4 |
| 5 | 53 | 5 |
| 6 | 54 | 6 |
| 7 | 55 | 7 |
| 8 | 56 | 8 |
| 9 | 57 | 9 |
| A | 65 | 17 |
| B | 66 | 18 |
| C | 67 | 19 |
| D | 68 | 20 |
| E | 69 | 21 |
| F | 70 | 22 |
| G | 71 | 23 |
| H | 72 | 24 |
| I | 73 | 25 |
| J | 74 | 26 |
| K | 75 | 27 |
| L | 76 | 28 |
| M | 77 | 29 |
| N | 78 | 30 |
| O | 79 | 31 |
| P | 80 | 32 |
| Q | 81 | 33 |
| R | 82 | 34 |
| S | 83 | 35 |
| T | 84 | 36 |
| U | 85 | 37 |
| V | 86 | 38 |
| W | 87 | 39 |
| X | 88 | 40 |
| Y | 89 | 41 |
| Z | 90 | 42 |
Ejemplo:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
Distribuya los pesos de **2 a 9**, de **derecha a izquierda** (reiniciando después del octavo carácter), como se muestra a continuación:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
Multiplique el valor por el peso de cada columna y sume todos los resultados:
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 |
| Peso | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Producto | 5 | 8 | 51 | 36 | 171 | 24 | 28 | 30 | 0 | 4 | 60 | 42 |
`5 + 8 + 51 + 36 + 171 + 24 +28 + 30 + 0 + 4 + 60 + 42 = 459`
Obtenga el resto de la división de la suma entre **11**.\
Si el resto es **0 o 1**, el primer dígito verificador será **0**.\
De lo contrario, el primer dígito verificador será **11 − resto**.
En este ejemplo:\
Resto de `459 / 11 = 8`, por lo tanto el primer dígito verificador es **3** (resultado de `11−8`) .
Cálculo del segundo dígito verificador [#cálculo-del-segundo-dígito-verificador]
Para calcular el segundo dígito verificador, agregue el **primer dígito verificador** al final del CNPJ, formando **13 caracteres**, y repita los mismos pasos utilizados para el primer dígito.
| CNPJ | 1 | 2 | A | B | C | 3 | 4 | 5 | 0 | 1 | D | E | 3 |
|---|
| Valor | 1 | 2 | 17 | 18 | 19 | 3 | 4 | 5 | 0 | 1 | 20 | 21 | 3 |
| Peso | 6 | 5 | 4 | 3 | 2 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 |
| Producto | 6 | 10 | 68 | 54 | 38 | 27 | 32 | 35 | 0 | 5 | 80 | 63 | 6 |
`6 + 10 + 68 + 54 + 38 + 27 + 32 + 35 + 0 + 5 + 80 + 63 + 6 = 424`
Resto de `424 / 11 = 6`, por lo tanto el segundo dígito verificador es **5** (resultado de `11 − 6`).
Resultado final: `12.ABC.345/01DE-``35`
# Proyecto CNPJ.ws
Este proyecto es un subproducto de **[Bitize](https://www.bitize.com.br/)** que es una plataforma de gestión de compras
focada en encontrar buenos proveedores.
**[Bitize](https://www.bitize.com.br/)** está desarrollando una herramienta para la prospección de **Proveedores**
y para eso se desarrolló una base con información pública de empresas brasileñas que ha sido enriquecida
con información de diversos organismos públicos.
El enfoque de CNPJ.ws es proporcionar una API rápida, actualizada y fácil de usar que devuelva datos públicos de
empresas brasileñas disponibles por la
[Lei de Acesso a Informação](http://www.planalto.gov.br/ccivil_03/_Ato2011-2014/2011/Lei/L12527.htm).
Tenemos una API pública porque esta información debe estar al alcance de todos.
El desafío ahora es obtener los datos referentes a las inscripciones estatales, ya poseemos de algunos estados
([vea aquí los estados](https://docs.cnpj.ws/modelos-de-dados/inscricoes-estaduais)) pero la tarea
# Como automatizar o cadastro de clientes com uma API de consulta CNPJ
Quantas vezes a sua equipe já digitou razão social, endereço, CNAE e inscrição estadual de um cliente novo — campo por campo — copiando do cartão CNPJ da Receita Federal? Além de lento, esse processo é a principal porta de entrada de erros cadastrais: um dígito trocado no CNPJ, um endereço desatualizado, uma razão social abreviada de forma diferente em cada sistema.
A boa notícia é que nada disso precisa ser manual. Com uma **API de consulta CNPJ**, o seu sistema pede apenas um dado ao usuário — o número do CNPJ — e preenche todo o resto sozinho, com informações oficiais e atualizadas. Neste post, mostramos como esse fluxo funciona, como implementá-lo com a API do CNPJ.ws e como um ERP brasileiro usa exatamente essa abordagem em produção.
O problema do cadastro manual [#o-problema-do-cadastro-manual]
Todo sistema que atende empresas — ERP, CRM, plataforma de cobrança, e-commerce B2B — precisa cadastrar pessoas jurídicas. No fluxo manual, isso significa um formulário com 10 a 20 campos que alguém preenche consultando documentos. Os custos aparecem em três frentes:
* **Tempo**: cada cadastro consome minutos de trabalho repetitivo, multiplicado por todos os clientes e fornecedores da base.
* **Erros**: digitação manual gera divergências que se propagam para notas fiscais, boletos e contratos — e retrabalho para corrigir.
* **Dados desatualizados**: a empresa muda de endereço ou de situação cadastral, e o cadastro no sistema continua com a informação antiga.
Como funciona uma API de consulta CNPJ [#como-funciona-uma-api-de-consulta-cnpj]
Uma API de consulta CNPJ expõe os dados públicos das empresas brasileiras em formato estruturado (JSON), pronto para ser consumido por qualquer aplicação. No caso do CNPJ.ws, uma única requisição HTTP retorna razão social, nome fantasia, situação cadastral, natureza jurídica, porte, endereço completo, CNAEs, quadro societário, inscrições estaduais e regime tributário (Simples Nacional/MEI).
O fluxo de automação tem três passos:
1\. O usuário informa só o CNPJ [#1-o-usuário-informa-só-o-cnpj]
No formulário de cadastro, o único campo obrigatório passa a ser o CNPJ. Vale validar os dígitos verificadores no front-end antes de consultar, evitando chamadas desnecessárias.
2\. O sistema consulta a API [#2-o-sistema-consulta-a-api]
```bash
curl https://publica.cnpj.ws/cnpj/00000000000191
```
A resposta traz o objeto completo da empresa. A API pública do CNPJ.ws permite até 3 consultas por minuto — suficiente para testar e para volumes baixos. Para uso em produção, a API comercial oferece limites maiores, dados adicionais e SLA.
3\. O formulário se preenche sozinho [#3-o-formulário-se-preenche-sozinho]
Com a resposta em mãos, o sistema popula todos os campos: razão social, endereço, CNAE principal, regime tributário. O usuário apenas confere e confirma. O que antes levava minutos passa a levar segundos — e os dados chegam exatamente como constam na base oficial.
Caso real: cadastro de clientes por IA no bitERP [#caso-real-cadastro-de-clientes-por-ia-no-biterp]
Um exemplo de quem usa esse fluxo em produção é o [bitERP, um ERP com inteligência artificial](https://www.biterp.ai), desenvolvido no Brasil. No bitERP, o usuário pode pedir no chat algo como *"cadastra o cliente CNPJ 00.000.000/0001-00"* — e o agente de IA consulta a API do CNPJ.ws, preenche o cadastro completo na tela e pede apenas a confirmação final.
A combinação é interessante porque junta duas automações: a IA elimina a navegação por menus e formulários, e a API de consulta CNPJ elimina a busca e digitação dos dados. O resultado é um onboarding de cliente que se resolve em uma única frase, com dados oficiais da Receita Federal — sem erro de digitação e sem cadastro incompleto.
O mesmo padrão se aplica a fornecedores, transportadoras e qualquer outra entidade PJ do sistema.
Boas práticas ao integrar [#boas-práticas-ao-integrar]
Para tirar o máximo da integração, vale seguir algumas recomendações:
* **Valide o CNPJ antes de consultar** — dígito verificador é cálculo local, não gaste requisição com número inválido.
* **Trate os limites de requisição** — implemente retry com backoff para o erro 429 e considere a API comercial para volume.
* **Guarde a data da consulta** — dados cadastrais mudam; saber quando o cadastro foi sincronizado permite programar atualizações periódicas.
* **Alerta de situação cadastral** — se a empresa constar como baixada, suspensa ou inapta, sinalize antes de concluir o cadastro. Isso evita emitir nota para CNPJ irregular.
* **Deixe o usuário revisar** — automação preenche, humano confirma. Especialmente campos que o cliente pode querer sobrescrever, como nome fantasia.
Comece agora [#comece-agora]
Você pode testar a consulta neste momento, sem cadastro: basta chamar `https://publica.cnpj.ws/cnpj/{número}` e ver o JSON retornado. Para levar a integração para produção, conheça os [planos da API comercial do CNPJ.ws](https://www.cnpj.ws/pt-BR#precos) — e se quiser ver o fluxo de cadastro automatizado funcionando dentro de um ERP, o exemplo do bitERP mostra até onde essa automação pode chegar.
# Consultar CNPJ con PHP
PHP es uno de los lenguajes más utilizados en el desarrollo web y con él es muy simple hacer una consulta en la API de [CNPJ.ws](https://www.cnpj.ws/es-ES).
Con la integración podemos usar la API para consultar la dirección, inscripción estatal, situación cadastral, CNAE y muchas otras informaciones que pueden ser importantes en el momento del registro del cliente o proveedor a través del CNPJ.
API Pública [#api-pública]
[CNPJ.ws](https://www.cnpj.ws/es-ES) proporciona una API pública para consultas donde puedes hacer hasta 3 consultas por minuto. [Vea la documentación](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
```php
Cómo buscar [#cómo-buscar]
Para buscar basta con llenar el CNPJ de la empresa en la columna CNPJ (en la hoja de cálculo **"Consultas"**) y luego hacer clic en el botón de arriba **"Consultar/Actualizar"**:
Después de hacer clic en el botón **“Consultar/Actualizar”**, la hoja de cálculo proporcionará todos los datos disponibles, ¿simple verdad?
Recordando que [CNPJ.ws](https://www.cnpj.ws/es-ES) tiene una API pública y puedes consultar CNPJs de forma gratuita, solo no llenes el Token. Pero la API pública tiene una limitación de **3 consultas por minuto** ([vea la documentación](https://docs.cnpj.ws/referencia-de-api/api-publica/limitacoes)), lo que hace que la consulta sea un poco lenta, pero para un volumen pequeño de consultas puede ser viable.
Si necesitas más velocidad o un mayor volumen de consultas, verifica [nuestros planes](https://www.cnpj.ws/es-ES#precos). Hicimos una comparación, consultando 100 CNPJs diferentes, con y sin el token:
| Usando el Token | Consultas | Tiempo |
| :-------------: | :-------: | :----------: |
| Sí | 100 | **00:00:57** |
| No | 100 | 00:34:40 |
[**Haz clic aquí para descargar la Hoja de Cálculo Gratuitamente**](https://www.cnpj.ws/ConsultaDadosEmpresariaisViaCNPJws.zip)
Esta hoja de cálculo se proporciona solo como un ejemplo y no representa un producto oficial de CNPJ.ws. Por eso, no ofrecemos soporte para cuestiones relacionadas con Excel. Siéntete libre de personalizar este ejemplo de acuerdo con tus necesidades. Si tienes dudas o sugerencias, estamos aquí para ayudar. Ponte en contacto con nosotros por correo electrónico: [contacto@cnpj.ws](mailto:contacto@cnpj.ws).
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
¡Un abrazo!
# Consultar CNPJ Gratuitamente con Java
Si estás en busca de una manera eficiente y gratuita de consultar datos de CNPJ directamente desde tu aplicación Java, ¡has llegado al lugar correcto! En esta guía, exploraremos cómo puedes integrar tu aplicación Java con la API de [CNPJ.ws](https://www.cnpj.ws/es-ES) para acceder a información detallada de empresas registradas en la Receita Federal.
El [CNPJ.ws](https://www.cnpj.ws/es-ES) proporciona una API pública para consultas donde puedes hacer hasta 3 consultas por minuto. [Vea la documentación](https://docs.cnpj.ws/referencia-de-api/api-publica/consultando-cnpj).
Vamos a dividir este tutorial en secciones para facilitar la comprensión. ¡Acompáñanos!
Pre-Requisitos [#pre-requisitos]
**Java**: Asegúrate de tener el JDK instalado en tu máquina.
**IDE**: Un entorno de desarrollo Java, como Eclipse o IntelliJ IDEA.
Configurando el Ambiente [#configurando-el-ambiente]
Crea un nuevo proyecto Java en tu IDE favorito.
Añade la biblioteca OkHttp: Vamos a utilizar la biblioteca OkHttp para facilitar las solicitudes HTTP. Añade la dependencia en tu archivo pom.xml si estás usando Maven:
```xml
com.squareup.okhttp3
okhttp
4.9.0
```
Desarrollando la Clase de Consulta [#desarrollando-la-clase-de-consulta]
Crea una nueva clase Java llamada ConsultaCNPJ. En esta clase, implementaremos el método para realizar la consulta de CNPJ:
```java
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
public class ConsultaCNPJ {
private static final String URL_BASE = "https://publica.cnpj.ws/cnpj/";
//Caso use a API Comercial a URL é diferente, veja a doc:
public static void main(String[] args) {
try {
String cnpj = "27865757000102";
String jsonResponse = consultaCNPJ(cnpj);
System.out.println(jsonResponse);
} catch (IOException e) {
e.printStackTrace();
}
}
public static String consultaCNPJ(String cnpj) throws IOException {
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url(URL_BASE + cnpj)
.get()
.build();
try (Response response = client.newCall(request).execute()) {
return response.body().string();
}
}
}
```
Explicación: [#explicación]
* **OkHttpClient**: Usamos esta clase para enviar solicitudes HTTP.
* **Request**: Aquí construimos nuestra solicitud, definiendo la URL con el número del CNPJ que deseamos consultar.
* **Response**: Almacenamos la respuesta de la API para procesarla posteriormente.
Probando la Consulta [#probando-la-consulta]
Ejecuta la clase ConsultaCNPJ y verifica la consola. Deberías ver la respuesta JSON que contiene la información detallada sobre el CNPJ consultado.
Conclusión [#conclusión]
En esta guía, aprendiste cómo realizar consultas de CNPJ de forma gratuita usando la API pública de CNPJ.WS en una aplicación Java. Aprovecha esta funcionalidad para enriquecer tus proyectos Java con datos empresariales precisos y actualizados.
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
¡Hasta luego!
# Consultar CNPJ con Javascript y Node.JS
¡Consultar un CNPJ utilizando la API de CNPJ.ws con Javascript y Node.JS es muy fácil!
Mantener el registro de clientes/proveedores o incluso hacer una consulta a los datos de empresas para facilitar algún registro interno de tu sistema es algo muy común y la API de CNPJ.ws proporciona una manera fácil y rápida para desarrollar esta integración.
Con la integración podemos usar la API para consultar la dirección, inscripción estatal, situación cadastral, CNAE y muchas otras informaciones que pueden ser importantes en el momento del registro del cliente o proveedor a través del CNPJ.
Los datos retornados por la API son obtenidos de diversos organismos públicos (Receita Federal, Sintegra, SERPRO, Suframa, etc.), aglutinados y organizados para facilitar el uso por otros sistemas a través de una API Rest.
Instalación [#instalación]
Nosotros desarrollamos un paquete para facilitar esta integración, vea en [Github](https://github.com/cnpj-ws/consultar-cnpj).
Recordando que puedes usar nuestra API gratuita para consultar CNPJ o puedes adquirir uno de nuestros planes comerciales.
Para empezar, vamos a instalar el paquete:
Utilizando YARN:
```shell
yarn add consultar-cnpj
```
Utilizando NPM:
```shell
npm i consultar-cnpj --save
```
Utilización [#utilización]
El CNPJ.ws posee una API Pública y una Comercial, para utilizar la API Pública no necesitas un token, pero solo puedes hacer hasta 3 consultas por minuto. Si estás utilizando la API Comercial debes pasar el token como segundo parámetro en la consulta para utilizar sus beneficios. Puedes ver más detalles de los planes comerciales en nuestra [página de precios](https://www.cnpj.ws/es-ES#precos).
```javascript
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
try {
// O Token é opcional
const empresa = await consultarCNPJ("40154884000153", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
```
Retorno [#retorno]
Abajo el JSON retornado por la API:
```json
{
"cnpj_raiz": "40154884",
"razao_social": "STARLINK BRAZIL SERVICOS DE INTERNET LTDA.",
"capital_social": "800000.00",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T08:21:13.130Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2062",
"descricao": "Sociedade Empresária Limitada"
},
"qualificacao_do_responsavel": {
"id": 5,
"descricao": "Administrador "
},
"socios": [
{
"cpf_cnpj_socio": "***966178**",
"nome": "VITOR JAMES URNER",
"tipo": "Pessoa Física",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "71 a 80 anos",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "39523686000130",
"nome": "STARLINK BRAZIL HOLDING LTDA.",
"tipo": "Pessoa Jurídica",
"data_entrada": "2020-12-18",
"cpf_representante_legal": "***966178**",
"nome_representante": "VITOR JAMES URNER",
"faixa_etaria": "Não se aplica",
"atualizado_em": "2021-07-21T06:13:26.688Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 22,
"descricao": "Sócio"
},
"qualificacao_representante": {
"id": 5,
"descricao": "Administrador "
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "40154884000153",
"atividades_secundarias": [
{
"id": "6190699",
"secao": "J",
"divisao": "61",
"grupo": "61.9",
"classe": "61.90-6",
"subclasse": "6190-6/99",
"descricao": "Outras atividades de telecomunicações não especificadas anteriormente"
},
{
"id": "6462000",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.62-0",
"subclasse": "6462-0/00",
"descricao": "Holdings de instituições não financeiras"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
}
],
"cnpj_raiz": "40154884",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "53",
"tipo": "Matriz",
"nome_fantasia": null,
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2020-12-18",
"data_inicio_atividade": "2020-12-18",
"nome_cidade_exterior": null,
"tipo_logradouro": "ALAMEDA",
"logradouro": "SANTOS",
"numero": "74",
"complemento": "ANDAR 7 CONJ 72 SALA 10",
"bairro": "CERQUEIRA CESAR",
"cep": "01418000",
"ddd1": "11",
"telefone1": "30229503",
"ddd2": null,
"telefone2": null,
"ddd_fax": null,
"fax": null,
"email": "VITOR@URNER.COM.BR",
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6130200",
"secao": "J",
"divisao": "61",
"grupo": "61.3",
"classe": "61.30-2",
"subclasse": "6130-2/00",
"descricao": "Telecomunicações por satélite"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
},
"cidade": {
"id": 3832,
"nome": "São Paulo",
"ibge_id": 3550308,
"siafi_id": "7107"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "130287771116",
"ativo": true,
"atualizado_em": "2021-08-25T16:59:58.589Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
Conclusión [#conclusión]
Utilizando la API de CNPJ.ws obtienes los datos de las empresas brasileñas de forma simple y fácil, echa un vistazo a nuestra [documentación](https://docs.cnpj.ws/).
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
Cualquier duda, estamos aquí para apoyarte, envía un correo electrónico a [contacto@cnpj.ws](mailto:contacto@cnpj.ws)!
# Gatilho para consultar CNPJ en Protheus
Registrar clientes o proveedores en Protheus puede ser más fácil si consultamos el CNPJ en la API del [***CNPJ.ws***](https://www.cnpj.ws/es-ES)
Con la integración podemos usar la API para consultar la dirección, inscripción estatal, situación cadastral, CNAE y muchas otras informaciones que pueden ser importantes en el momento del registro del cliente o proveedor.
Ya creamos una clase en ADVPL para integrar Protheus al [***CNPJ.ws***](https://www.cnpj.ws/es-ES) en el post: [Consultar CNPJ con ADVPL (Protheus)](https://docs.cnpj.ws/artigos/integracao-protheus).
En este post vamos a usar esta clase ADVPL para desarrollar un gatillo que utilizaremos tanto en el registro de clientes como en el registro de proveedores. Recordando que puedes usar nuestra API gratuita para consultar CNPJ, pero con una limitación de 3 consultas por minuto o puedes adquirir uno de nuestros planes comerciales.
Función getCNPJ [#función-getcnpj]
Vamos a comenzar creando una user function que llamaremos en nuestros gatillos. Observa que recibe dos parámetros:
* cTab: SA1 o SA2, indicando si estamos trabajando con clientes o proveedores
* cCNPJ: el número del CNPJ
También hicimos un tratamiento usando la función `isBlind` para el caso de que el gatillo sea llamado vía execauto, sin la interfaz del usuario. Y usamos la función `FWMsgRun` para que el usuario tenga un retorno visual y no solo una pantalla "congelada" mientras se ejecuta el proceso.
```js
#include 'totvs.ch'
user function getCNPJ(cTab,cCNPJ)
local aArea:= getArea()
local cRet := ''
default cTab := 'SA1'
default cCNPJ:= ''
cCNPJ:= allTrim(cCNPJ)
if !empty(cTab) .and. len(cCNPJ) == 14
if isBlind()
cRet:= consulta(cTab,cCNPJ)
else
FWMsgRun(,{||cRet:= consulta(cTab,cCNPJ)},'CNPJ.ws','Consultando...')
endif
endif
restArea(aArea)
return cRet
```
Vamos a crear una función estática que será la responsable de la comunicación con el [***CNPJ.ws***](https://www.cnpj.ws/es-ES).
Debes revisar bien este código para que se ajuste a tus necesidades en tu empresa, aquí he llenado todos los campos que se me ocurrieron, pero siéntete libre de hacer modificaciones:
```javascript
static function consulta(cTab,cCNPJ)
local oCNPJws:= CNPJws():new()
local oJSON := nil
local nX := 1
local cRet := ''
local lJob := isBlind()
local oModel := nil
default cTab := 'SA1'
default cCNPJ:= ''
if oCNPJws:consultarCNPJ(cCNPJ)
oJSON:= oCNPJws:getResponse()
cRet:= oJSON['razao_social']
if oJSON['estabelecimento']['situacao_cadastral'] <> 'Ativa'
if lJob
conout(cCNPJ + ': A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
else
alert('A situação cadastral da empresa junto a SEFAZ é ' + oJSON['estabelecimento']['situacao_cadastral'])
endif
endif
if cTab == 'SA1'
M->A1_MSBLQL:= if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1')
If ExistTrigger('A1_MSBLQL')
RunTrigger(1,Nil,Nil,,'A1_MSBLQL')
Endif
M->A1_CNAE:= oJSON['estabelecimento']['atividade_principal']['id']
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+M->A1_CNAE))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
If ExistTrigger('A1_CNAE')
RunTrigger(1,Nil,Nil,,'A1_CNAE')
Endif
M->A1_PESSOA := 'J'
If ExistTrigger('A1_PESSOA')
RunTrigger(1,Nil,Nil,,'A1_PESSOA')
Endif
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH')+ '0' + oJSON['estabelecimento']['pais']['id'] ))
M->A1_CODPAIS := CCH->CCH_CODIGO
If ExistTrigger('A1_CODPAIS')
RunTrigger(1,Nil,Nil,,'A1_CODPAIS')
Endif
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
M->A1_PAIS := SYA->YA_CODGI
If ExistTrigger('A1_PAIS')
RunTrigger(1,Nil,Nil,,'A1_PAIS')
Endif
endif
endif
M->A1_NREDUZ := oJSON['estabelecimento']['nome_fantasia']
if empty(M->A1_NREDUZ) //Caso nao possua nome fantasia
M->A1_NREDUZ := avKey(cRet, 'A1_NREDUZ')
endif
If ExistTrigger('A1_NREDUZ')
RunTrigger(1,Nil,Nil,,'A1_NREDUZ')
Endif
M->A1_CEP := oJSON['estabelecimento']['cep']
If ExistTrigger('A1_CEP')
RunTrigger(1,Nil,Nil,,'A1_CEP')
Endif
M->A1_EST := oJSON['estabelecimento']['estado']['sigla']
If ExistTrigger('A1_EST')
RunTrigger(1,Nil,Nil,,'A1_EST')
Endif
M->A1_COD_MUN:= substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5)
If ExistTrigger('A1_COD_MUN')
RunTrigger(1,Nil,Nil,,'A1_COD_MUN')
Endif
M->A1_BAIRRO := oJSON['estabelecimento']['bairro']
If ExistTrigger('A1_BAIRRO')
RunTrigger(1,Nil,Nil,,'A1_BAIRRO')
Endif
M->A1_END := oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero']
If ExistTrigger('A1_END')
RunTrigger(1,Nil,Nil,,'A1_END')
Endif
M->A1_COMPLEM:= oJSON['estabelecimento']['complemento']
If ExistTrigger('A1_COMPLEM')
RunTrigger(1,Nil,Nil,,'A1_COMPLEM')
Endif
M->A1_DDD := oJSON['estabelecimento']['ddd1']
If ExistTrigger('A1_DDD')
RunTrigger(1,Nil,Nil,,'A1_DDD')
Endif
M->A1_TEL := oJSON['estabelecimento']['telefone1']
If ExistTrigger('A1_TEL')
RunTrigger(1,Nil,Nil,,'A1_TEL')
Endif
M->A1_FAX := oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax']
If ExistTrigger('A1_FAX')
RunTrigger(1,Nil,Nil,,'A1_FAX')
Endif
M->A1_EMAIL := oJSON['estabelecimento']['email']
If ExistTrigger('A1_EMAIL')
RunTrigger(1,Nil,Nil,,'A1_EMAIL')
Endif
if valType(oJSON['simples']) == 'J'
M->A1_SIMPNAC:= if(oJSON['simples']['simples'] == 'Sim', '1', '2')
else
M->A1_SIMPNAC:= '2'
endif
If ExistTrigger('A1_SIMPNAC')
RunTrigger(1,Nil,Nil,,'A1_SIMPNAC')
Endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
M->A1_INSCR:= oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual']
If ExistTrigger('A1_INSCR')
RunTrigger(1,Nil,Nil,,'A1_INSCR')
Endif
EXIT
endif
next
elseIf cTab == 'SA2'
//MATA020 está em MVC
oModel := FWModelActive()
oModel:SetValue('SA2MASTER','A2_MSBLQL' ,if(oJSON['estabelecimento']['situacao_cadastral'] == 'Ativa','2','1'))
CC3->(dbSetOrder(1))
if !CC3->(dbSeek(xFilial('CC3')+oJSON['estabelecimento']['atividade_principal']['id']))
reclock('CC3',.t.)
CC3->CC3_FILIAL := xFilial('CC3')
CC3->CC3_COD := oJSON['estabelecimento']['atividade_principal']['id']
CC3->CC3_DESC := upper(oJSON['estabelecimento']['atividade_principal']['descricao'])
CC3->CC3_CSECAO := oJSON['estabelecimento']['atividade_principal']['secao']
CC3->CC3_CDIVIS := oJSON['estabelecimento']['atividade_principal']['divisao']
CC3->CC3_CGRUPO := strTran(oJSON['estabelecimento']['atividade_principal']['grupo'],'.')
CC3->CC3_CCLASS := strTran(strTran(oJSON['estabelecimento']['atividade_principal']['classe'],'.'),'-')
CC3->(msUnlock())
endif
oModel:SetValue('SA2MASTER','A2_CNAE',oJSON['estabelecimento']['atividade_principal']['id'])
oModel:SetValue('SA2MASTER','A2_TIPO', 'J')
if !empty(oJSON['estabelecimento']['pais']['id'])
CCH->(dbSetOrder(1))
if CCH->(dbSeek(xFilial('CCH') + '0' + oJSON['estabelecimento']['pais']['id']))
oModel:SetValue('SA2MASTER','A2_CODPAIS', allTrim(CCH->CCH_CODIGO))
endif
SYA->(dbSetOrder(2))
if SYA->(dbSeek(xFilial('SYA')+ upper(oJSON['estabelecimento']['pais']['nome'])))
oModel:SetValue('SA2MASTER','A2_PAIS', allTrim(SYA->YA_CODGI))
endif
endif
if !empty(oJSON['estabelecimento']['nome_fantasia'])
oModel:SetValue('SA2MASTER','A2_NREDUZ',oJSON['estabelecimento']['nome_fantasia'])
else
oModel:SetValue('SA2MASTER','A2_NREDUZ',avKey(cRet, 'A2_NREDUZ'))
endif
oModel:SetValue('SA2MASTER','A2_CEP', oJSON['estabelecimento']['cep'])
oModel:SetValue('SA2MASTER','A2_EST', oJSON['estabelecimento']['estado']['sigla'])
oModel:SetValue('SA2MASTER','A2_COD_MUN', substring(cValToChar(oJSON['estabelecimento']['cidade']['ibge_id']),3,5))
oModel:SetValue('SA2MASTER','A2_BAIRRO', oJSON['estabelecimento']['bairro'])
oModel:SetValue('SA2MASTER','A2_END',oJSON['estabelecimento']['logradouro'] + ', ' + oJSON['estabelecimento']['numero'])
oModel:SetValue('SA2MASTER','A2_COMPLEM', oJSON['estabelecimento']['complemento'])
oModel:SetValue('SA2MASTER','A2_DDD', oJSON['estabelecimento']['ddd1'])
oModel:SetValue('SA2MASTER','A2_TEL', oJSON['estabelecimento']['telefone1'])
oModel:SetValue('SA2MASTER','A2_FAX', oJSON['estabelecimento']['ddd_fax']+oJSON['estabelecimento']['fax'])
oModel:SetValue('SA2MASTER','A2_EMAIL', oJSON['estabelecimento']['email'])
if valType(oJSON['simples']) == 'J'
oModel:SetValue('SA2MASTER','A2_SIMPNAC', if(oJSON['simples']['simples'] == 'Sim', '1', '2'))
else
oModel:SetValue('SA2MASTER','A2_SIMPNAC', '2')
endif
for nX:=1 to len(oJSON['estabelecimento']['inscricoes_estaduais'])
if oJSON['estabelecimento']['estado']['id'] == oJSON['estabelecimento']['inscricoes_estaduais'][nX]['estado']['id']
oModel:SetValue('SA2MASTER','A2_INSCR', oJSON['estabelecimento']['inscricoes_estaduais'][nX]['inscricao_estadual'])
EXIT
endif
next
endif
else
if lJob
conout('Erro ao consultar CNPJ: ' + oCNPJws:getError())
else
alert('Erro ao consultar CNPJ: ' + oCNPJws:getError())
endif
endif
return cRet
```
Gatilho A1_CGC [#gatilho-a1_cgc]
Abajo el llenado del gatilho del campo A1\_CGC, en él llamamos a la user function `u_getcnpj` pasando como parámetros a **SA1** además del CNPJ:
Gatilho A2_CGC [#gatilho-a2_cgc]
Abajo el llenado del gatilho del campo A2\_CGC, en él llamamos a la user function `u_getcnpj` pasando como parámetros a **SA2** además del CNPJ:
Conclusión [#conclusión]
El resultado debe ser como el gif abajo, al digitar el CNPJ el Protheus irá consultar el [***CNPJ.ws***](https://www.cnpj.ws/es-ES) y llenar los campos automáticamente:
Puedes consultar los fuentes de este proyecto en [GitHub](https://github.com/cnpj-ws/protheus), la clase mencionada está en este repositorio también.
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
¡Hasta luego!
# Consultar CNPJ con ADVPL (Protheus)
El sistema Protheus de Totvs es el ERP líder del mercado brasileño y puede ser integrado con la API de CNPJ.ws de
manera fácil y simple para consultar clientes o proveedores a través del CNPJ.
El Protheus utiliza el lenguaje propietario de Totvs, el ADVPL (Advanced Protheus Language), que es un
lenguaje de programación estándar xBase (Clipper, Visual Objects y después Fivewin).
Para esta integración vamos a construir una clase genérica de comunicación que podrá ser usada en diversos tipos
de proyecto. También puedes encontrar este proyecto en [GitHub](https://github.com/cnpj-ws/protheus).
Recordando que puedes usar nuestra API gratuita para consultar CNPJ, pero con una limitación de 3 consultas por
minuto o puedes adquirir uno de nuestros planes comerciales.
Con la integración podemos usar la API para consultar la dirección, inscripción estatal, situación cadastral, CNAE y
muchas otras informaciones que pueden ser importantes en el momento del registro del cliente o proveedor, persona
jurídica, a través del CNPJ.
Integración CNPJ.ws con el ERP Totvs Protheus [#integración-cnpjws-con-el-erp-totvs-protheus]
Vamos a comenzar, abajo la declaración de la clase:
```javascript title="/src/cnpjws.prw"
#include 'totvs.ch'
#include 'protheus.ch'
class CNPJws
data lVerb as Logical
data cURL as String
data cToken as String
data cErro as String
data cRet as String
data oRet as String
data aHeaders as Array
data lRet as Logical
method new() CONSTRUCTOR
method consoleLog(cMsg,lErro)
method setError(oRest)
method consultarCNPJ(cCNPJ)
method getResponse()
method getError()
endClass
```
Tendremos 6 métodos en nuestra clase:
* **new**: Responsable de instanciar la clase;
* **setError**: Método interno para generación de errores;
* **consultarCNPJ**: Responsable de hacer la consulta del CNPJ junto a la API del CNPJ.ws;
* **getResponse**: Retorna la respuesta de la API en formato JSON;
* **getError**: Retorna el mensaje de error;
Ahora vamos a desarrollar el método `new`, que es nuestro método constructor. Observa que este método recibe el
parámetro `lTest` (el valor predeterminado es falso) y sí, vamos a hacer pruebas con nuestra clase de integración.
Observa también que tenemos un parámetro **CN\_TOKEN**, debemos crearlo en caso de que estemos usando la API Comercial (sin restricciones) y llenarlo con el Token que fue enviado a tu correo electrónico.
```javascript title="/src/cnpjws.prw"
method new(lTest) class CNPJws
default lTest:= .f.
::cToken := if(lTest, '', superGetMV('CN_TOKEN',.f.,''))
::cURL := if(empty(::cToken),'https://publica.cnpj.ws','https://comercial.cnpj.ws')
::lVerb := if(lTest, .t., superGetMV('CN_VERBO',.f.,.t.)) //Indica se ira imprimir todas as msgs no console
::cErro := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::aHeaders:= {"Content-Type: application/json; charset=utf-8"}
if !empty(::cToken)
aAdd(::aHeaders,'x_api_token: ' + allTrim(::cToken))
endif
::consoleLog('Classe instanciada com sucesso!')
return Self
```
En el método `new` usamos el método `consoleLog`, entonces vamos a desarrollarlo ahora. Este método busca
padronizar los mensajes emitidos por la clase.
En caso de que el parámetro **CN\_VERBO** esté como .T., la clase imprimirá todos los mensajes en el console.log del
Protheus.
```javascript title="/src/cnpjws.prw"
method consoleLog(cMsg,lErro) class CNPJws
local cLog:= ''
default cMsg := ''
default lErro:= .f.
if ::lVerb .or. lErro
cLog:= '[' + dtoc(date()) + ']'
cLog+= '[' + time() + ']'
cLog+= '[' + ProcName(1) + ']'
cLog+= '[' + cValToChar(ProcLine(1)) + ']'
cLog+= '['+allTrim(cMsg)+']'
if lErro
::cErro:= cLog
::lRet := .f.
endif
if ::lVerb .or. lErro
conout(cLog)
endif
endif
return
```
Abajo el método `setError` usado por la clase para generar los mensajes de error:
```javascript title="/src/cnpjws.prw"
method setError(oRest,cPath) class CNPJws
local cLog := ''
local cAux := ''
local cStatus := ''
default cPath := ''
::oRet := nil
::cRet:= oRest:GetResult()
if valType(::cRet) <> 'C'
::cRet:= ''
endif
if !empty(::cRet)
::cRet:= FWNoAccent(DecodeUtf8(::cRet))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
endif
cAux:= FWNoAccent(DecodeUtf8(oRest:GetLastError()))
if empty(cAux)
cAux:= FWNoAccent(oRest:GetLastError())
endif
cStatus:= oRest:GetHTTPCode()
cLog+= 'Host: ' + ::cURL + CRLF
cLog+= 'Operacao: ' + ProcName(1) + ' ' + cPath + CRLF
cLog+= 'HTTP Code: ' + cStatus + CRLF
cLog+= 'Erro: ' + cAux + CRLF
cLog+= 'Resultado: ' + ::cRet + CRLF
::consoleLog(cLog,.T.)
return
```
Ahora sí, vamos desarrollar el método responsable de comunicarse con la API del CNPJ.ws, el método
`consultarCNPJ`. Aquí vamos a utilizar la clase [FWREST](https://tdn.engpro.totvs.com.br/display/framework/FWRest?focusedCommentId=446697540)
para hacer la comunicación con la API, este método recibe el CNPJ como parámetro y hace la consulta en la API.
El método retorna un booleano, en caso de que todo salga bien, retornará true, en caso de error, retornará
false, vea abajo:
```javascript title="/src/cnpjws.prw"
method consultarCNPJ(cCNPJ) class CNPJws
local oRest := FWRest():New(::cURL)
local cPath := ''
::cRet := ''
::oRet := nil
::lRet := .t.
::cErro:= ''
cPath+= allTrim(cCNPJ)
oRest:setPath(cPath)
if oRest:Get(::aHeaders)
if !empty(oRest:GetResult())
::cRet:= FWNoAccent(DecodeUtf8(oRest:GetResult()))
if empty(::cRet)
::cRet:= FWNoAccent(oRest:GetResult())
endif
::cRet:= strTran(::cRet,'\/','/')
::cRet:= strtran(::cRet,":null",': " "')
::cRet:= strtran(::cRet,'"self"','"_self"')
::oRet:= JsonObject():new()
::oRet:fromJson(::cRet)
::lRet := .t.
::cErro:= ''
else
::oRet := nil
::cErro:= ''
::lRet := .t.
endif
::consoleLog('Sucesso! ' + cPath)
else
::setError(oRest,cPath)
endif
FreeObj(oRest)
return ::lRet
```
Abajo tenemos el método responsable por retornar el JSON que la API del ***[CNPJ.ws](https://www.cnpj.ws/es-ES)***
retornó en la consulta:
```javascript title="/src/cnpjws.prw"
method getResponse() class CNPJws
return ::oRet
```
Abajo tenemos el método responsable por retornar el mensaje de error en caso de que la consulta no tenga éxito:
```javascript title="/src/cnpjws.prw"
method getError() class CNPJws
return ::cErro
```
Legal, construimos nuestra clase, ahora es un buen momento para desarrollar una rutina para utilizar nuestra
clase:
```javascript title="/src/cnpjws.prw"
user function tstCNPJ()
local oCNPJ:= nil
local oJSON:= nil
RpcSetType(3)
if !RpcSetEnv('99','01')
return
endif
oCNPJ:= CNPJws():new()//Instancia a classe
if oCNPJ:consultarCNPJ('40154884000153')
oJSON:= oCNPJ:getResponse()
endif
RPCClearEnv()
return
```
Caso necesites apoyo para implementar esta integración en tu base, te recomendamos [Apply System](https://applysystem.com.br/site/),
nuestra socia, que cuenta con consultores especializados en la integración entre sistemas.
Este post quedó largo, ¿verdad? Entonces voy a dejar para hacer una parte 2 utilizando TL++ para crear una prueba
para la clase de integración, pero los fuentes ya están en [GitHub](https://github.com/cnpj-ws/protheus) por si
quieres echar un vistazo.
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
¡Hasta luego!
# Mantener el registro de clientes y proveedores actualizado
Mantener los registros de clientes y proveedores siempre actualizados es una tarea difícil, pero necesaria.
Independientemente del tamaño de tu empresa, es muy importante tener estos registros siempre actualizados, ya que
ayudan a estandarizar y controlar la información sobre tu negocio.
La API de CNPJ.ws obtiene datos de diversos organismos públicos (Receita Federal, Sintegra, SERPRO, Suframa, etc.), aglutina y organiza estos datos para facilitar su uso por otros sistemas a través de una API Rest.
De esta forma, puedes obtener en una sola API datos de los socios, CNAE e inscripciones estatales de manera simple y automatizada.
Echa un vistazo a nuestra [documentación](https://docs.cnpj.ws/).
Para saber más sobre nuestros planes y formas de pago accede a [CNPJ.ws](https://www.cnpj.ws/es-ES#precos).
# Qué es el CNPJ
O Cadastro Nacional de Pessoa Jurídica é o registro utilizado pela Receita Federal para a abertura de uma instituição com ou sem fins lucrativos, a fim de acompanhar as movimentações financeiras dessas organizações, por meio do CNPJ, a empresa existe perante o governo e sua atuação no mercado é legalizada.
El CNPJ está compuesto por 14 números, siendo que los primeros 8 son la inscripción de la empresa, los siguientes 4 son para demostrar si la institución es una matriz o una filial. El número conocido como “mil contra”, 0001, es utilizado para matrices, y los números siguientes, 0002, 0003 y otros, son usados para filiales. Los últimos 2 números son los dígitos verificadores. El estándar para el registro es: XX.XXX.XXX/000X-XX.
Las funciones del documento varían, pudiendo ser para comprobar la existencia de la organización, emitir notas fiscales, contratar proveedores o empleados, obtener préstamos o hacer financiamientos. Por estos motivos, no solo las empresas necesitan el CNPJ, otras instituciones también utilizan este registro, por ejemplo, iglesias, asociaciones, ONGs, partidos políticos y otros.
En la información encontrada en el Cadastro Nacional de Pessoa Jurídica se incluyen el número del CNPJ, la fecha de apertura de la organización, el nombre de la institución y el nombre comercial, las actividades económicas en las que la empresa actúa, dirección y teléfono. Para obtener este registro, es necesario realizar una solicitud en línea en el sitio web de la Receita Federal y completar el formulario de registro con los documentos necesarios.
Para encontrar el CNPJ de una empresa, basta con acceder al sitio web de CNPJws, una API desarrollada para consultar datos de personas jurídicas. La plataforma tiene 5 planes: Gratuito, Básico, Intermedio, Avanzado y Premium.
# Actividades Económicas
A continuación, el modelo de datos referente a las actividades económicas:
| Campo | Tipo | Descripción |
| --------- | :--: | ----------- |
| id | S | ID |
| secao | S | Sección |
| divisao | S | División |
| grupo | S | Grupo |
| classe | S | Clase |
| subclasse | S | Subclase |
| descricao | S | Descripción |
# Ciudades
A continuación, el modelo de datos referente a las ciudades:
| Campo | Tipo | Descripción |
| --------- | :--: | ------------------- |
| id | N | ID |
| nome | S | Nombre de la ciudad |
| ibge\_id | N | Código IBGE |
| siafi\_id | S | Código SIAFI |
Fuente: [https://www.ibge.gov.br/explica/codigos-dos-municipios.php](https://www.ibge.gov.br/explica/codigos-dos-municipios.php)
# Establecimientos
A continuación, el modelo de datos referente a los establecimientos:
Establecimiento [#establecimiento]
| Campo | Tipo | Descripción |
| --------------------------- | :--: | ------------------------------- |
| cnpj | S | CNPJ |
| cnpj\_raiz | S | Raíz del CNPJ |
| cnpj\_ordem | S | Orden del CNPJ |
| cnpj\_digito\_verificador | S | Dígito verificador del CNPJ |
| tipo | S | Tipo (Filial o Matriz) |
| nome\_fantasia | S | Nombre de fantasía |
| situacao\_cadastral | S | Situación registral |
| data\_situacao\_cadastral | D | Fecha de la situación registral |
| data\_inicio\_atividade | D | Fecha de inicio de actividades |
| nome\_cidade\_exterior | S | Nombre de la ciudad (Exterior) |
| pais | O | País |
| estado | O | Estado |
| cidade | O | Ciudad |
| cep | S | Código postal |
| tipo\_logradouro | S | Tipo de vía |
| logradouro | S | Vía |
| numero | S | Número |
| complemento | S | Complemento |
| bairro | S | Barrio |
| ddd1 | S | DDD Teléfono 1 |
| telefone1 | S | Teléfono 1 |
| ddd2 | S | DDD Teléfono 2 |
| telefone2 | S | Teléfono 2 |
| ddd\_fax | S | DDD Fax |
| fax | S | Fax |
| email | S | E-mail |
| situacao\_especial | S | Situación especial |
| data\_situacao\_especial | D | Fecha de la situación especial |
| atividade\_principal | O | Actividad principal |
| atividades\_secundarias | A | Actividades secundarias |
| motivo\_situacao\_cadastral | O | Motivo situación registral |
| inscricoes\_estaduais | A | Inscripciones Estatales |
| inscricoes\_suframa\* | A | Inscripciones Suframa |
| regimes\_tributarios\* | A | Regímenes Tributarios |
**Atención** Las inscripciones en Suframa y los Regímenes Tributarios están disponibles solo en la API Comercial
# Estados
A continuación, el modelo de datos referente a los estados:
| Campo | Tipo | Descripción |
| -------- | :--: | ----------------- |
| id | N | ID |
| nome | S | Nombre del estado |
| sigla | S | Sigla del estado |
| ibge\_id | N | Código IBGE |
# Modelos de datos
Esta sección contiene la documentación de los diferentes modelos de datos devueltos por las APIs, detallando los campos y sus descripciones. Incluye:
* **Actividades Económicas**: Descripción de los códigos de actividades económicas (CNAE).
* **Ciudades**: Información sobre las ciudades, incluyendo códigos IBGE.
* **Establecimientos**: Datos sobre los establecimientos comerciales, como direcciones y situaciones registrales.
* **Estados**: Detalles de los estados brasileños, con códigos IBGE.
* **Inscripciones Estatales**: Información sobre las inscripciones estatales asociadas a CNPJs.
* **Suframa**: Documentación sobre inscripciones en Suframa.
* **Mensajes de Error**: Lista de posibles mensajes de error devueltos por las APIs.
* **Naturalezas Jurídicas**: Detalles sobre las naturalezas jurídicas de las empresas.
* **Países**: Información sobre los países, con códigos del BACEN.
* **Tamaños**: Descripciones de los tamaños de las empresas (ME, EPP, etc.).
* **Calificaciones Societarias**: Detalles sobre las calificaciones de los socios.
* **Regímenes Tributarios**: Información sobre los regímenes tributarios de las empresas.
* **Simples Nacional y MEI**: Datos relacionados con el Simples Nacional y el MEI.
* **Situaciones Registrales**: Detalles sobre las situaciones registrales de las empresas en la Receita Federal.
* **Socios**: Información sobre los socios de las empresas.
Estos documentos son esenciales para entender los tipos de datos que pueden ser consultados y recibidos por las APIs.
# Inscripciones Estatales
A continuación, el modelo de datos referente a las inscripciones estatales:
| Campo | Tipo | Descripción |
| ------------------- | :--: | ------------------- |
| inscricao\_estadual | S | Inscripción estatal |
| regime | S | Régimen |
| ativo | B | Inscripción activa |
| estado | O | Estado |
**Atención** Por el momento solo estamos devolviendo las inscripciones estatales de los estados a continuación:
* Bahia
* Espírito Santo
* Goiás
* Maranhão
* Mato Grosso do Sul
* Minas Gerais
* Paraíba
* Paraná
* Rio Grande do Sul
* São Paulo
* Sergipe
¡Estamos trabajando para traer las inscripciones estatales de otros estados!
# Suframa
A continuación, el modelo de datos referente a las inscripciones en Suframa:
| Campo | Tipo | Descripción |
| ------------------ | :--: | ------------------- |
| inscricao\_suframa | S | Inscripción Suframa |
| ativo | B | Inscripción activa |
**Atención** Las inscripciones en Suframa están disponibles solo en la API Comercial
# Mensajes de Error
La API puede devolver los siguientes códigos de error:
| Código | Descripción |
| :----: | --------------------- |
| 400 | Solicitud inválida |
| 401 | No autorizado |
| 403 | Acceso denegado |
| 404 | No encontrado |
| 429 | Exceso de solicitudes |
| 500 | Error interno |
A continuación, el modelo de JSON estándar:
```json
{
"status": 400,
"titulo": "Solicitud inválida",
"detalles": "CNPJ inválido",
"validacion": []
}
```
# Naturalezas Jurídicas
A continuación, el modelo de datos referente a las naturalezas jurídicas:
| Campo | Tipo | Descripción |
| --------- | :--: | ---------------------------- |
| id | S | ID de la naturaleza jurídica |
| descricao | S | Descripción |
# Países
A continuación, el modelo de datos referente a los países:
| Campo | Tipo | Descripción |
| --------- | :--: | -------------------- |
| id | S | Código BACEN |
| iso2 | S | Código del país ISO2 |
| iso3 | S | Código del país ISO3 |
| nome | S | Nombre del país |
| comex\_id | S | Código COMEX |
# Tamaños
Modelo de datos referente al tamaño de la empresa:
| Campo | Tipo | Descripción |
| --------- | :--: | ------------- |
| id | S | ID del tamaño |
| descricao | S | Descripción |
Lista de tamaños registrados:
| ID | Descripción |
| -- | ------------------------- |
| 00 | No informado |
| 01 | Micro Empresa |
| 03 | Empresa de Pequeño Tamaño |
| 05 | Otros |
# Calificaciones Societarias
A continuación, el modelo de datos referente a las calificaciones societarias:
| Campo | Tipo | Descripción |
| --------- | :--: | --------------------- |
| id | N | ID de la calificación |
| descricao | S | Descripción |
# Regímenes Tributarios
A partir del año 2021, la RFB pasa a disponibilizar la información sobre el régimen tributario de las personas jurídicas, divulgado anualmente.
Los datos se extraen de la Escrituração Contábil Fiscal (ECF). Raramente, cuando, debido a la ocurrencia de una situación especial o la existencia de Sociedades en Cuenta de Participación (SCP), hay entrega por parte de la institución de más de una escritura en el año con formas de tributación diferentes o domicilio en más de una ciudad, existirá más de un registro para el CNPJ.
Recordando que están exentos de la transmisión del ECF las personas jurídicas optantes por el Simples Nacional, órganos públicos, autarquías y fundaciones públicas. Los PJs inactivos tampoco necesitan enviar el ECF, siempre que no hayan realizado ningún tipo de actividad durante todo el año calendario.
A continuación, el modelo de datos referente a los regímenes tributarios:
| Campo | Tipo | Descripción |
| --------------------- | :--: | ----------------------- |
| ano | S | Año de la Determinación |
| regime\_tributario | S | Régimen |
| forma\_de\_tributacao | S | Forma de tributación |
A continuación se muestra la lista de posibles valores para el campo regime\_tributario:
| Valor | Descrição |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| IMUNES E ISENTAS | Empresas exentas del pago de determinados impuestos por inmunidad constitucional o exención prevista por la ley. |
| LUCRO ARBITRADO | Régimen aplicado por la Receita Federal en los casos en que la empresa no pueda comprobar lucro real o presunto. |
| LUCRO PRESUMIDO | Régimen en el que la base de cálculo del impuesto se define con base en un porcentaje fijo de los ingresos brutos. |
| LUCRO REAL | Régimen en el que la tributación se calcula sobre el beneficio contable neto ajustado por las adiciones y exclusiones previstas en la ley. |
La Receita Federal pone estos datos a disposición siempre en el año posterior a la entrega del ECF.
**Atención** La información referente a los regímenes tributarios está disponible solo en la API Comercial
# Simples Nacional y MEI
A continuación, el modelo de datos referente a los datos del Simples Nacional y del MEI:
Simples Nacional [#simples-nacional]
| Campo | Tipo | Descripción |
| ----------------------- | :--: | --------------------------------- |
| simples | S | ¿Optante por el Simples Nacional? |
| data\_opcao\_simples | S | Fecha de opción por el Simples |
| data\_exclusao\_Simples | S | Fecha de exclusión del Simples |
| mei | S | ¿Optante por el MEI? |
| data\_opcao\_mei | S | Fecha de opción por el MEI |
| data\_exclusao\_mei | S | Fecha de exclusión del MEI |
**Atención** Este registro solo se completa si la empresa es MEI, Simples o ha sido uno de los dos en algún momento.
# Situaciones Cadastrales
A continuación, el modelo de datos referente a las situaciones cadastrales:
| Campo | Tipo | Descripción |
| --------- | :--: | ------------------ |
| id | N | ID de la situación |
| descricao | S | Descripción |
# Socios
A continuación, el modelo de datos referente a los socios:
| Campo | Tipo | Descripción |
| --------------------------- | :--: | ------------------------------ |
| cpf\_cnpj\_socio | S | CPF\* o CNPJ |
| nome | S | Descripción |
| tipo | S | Tipo de persona |
| data\_entrada | S | Fecha de entrada |
| cpf\_representante\_legal | S | CPF\* del representante legal |
| nome\_representante | S | Nombre del representante legal |
| faixa\_etaria | S | Rango de edad |
| pais\_id | S | Código del País (BACEN) |
| qualificacao\_socio | O | Calificación |
| qualificacao\_representante | O | Calificación |
**Importante:** **El campo cpf\_cnpj\_socio y cpf\_representante\_legal se despersonalizan según la regla a continuación:**
Ocultación de información personal confidencial como en el caso del CPF, que debe despersonalizarse ocultando los tres primeros dígitos y los dos dígitos verificadores, según la orientación dispuesta en el art. 129 § 2o de la Ley no 13.473/2017 (LDO 2018).
# Consultando CNPJ en la API Comercial
En la API comercial puedes hacer una consulta directa por un CNPJ en nuestra base. En este endpoint debes enviar el header `x_api_token` con el token que te fue enviado por correo electrónico.
También puedes pasar el token como un parámetro en la URL, ejemplo:
`https://comercial.cnpj.ws/cnpj/27865757000102?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj/NUMERO_DO_CNPJ_SEM_CARACTERES_ESPECIAIS`
Ejemplos de Solicitud [#ejemplos-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const empresa = await consultarCNPJ("27865757000102", token);
console.log(empresa);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por el CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2023-11-11T03:00:00.000Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
},
{
"cpf_cnpj_socio": "***189808**",
"nome": "AMAURI SERGIO SOARES",
"tipo": "Pessoa Física",
"data_entrada": "2022-02-11",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2023-10-14T03:00:00.000Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 5,
"descricao": "Administrador "
},
"qualificacao_representante": null,
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
}
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6209100",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.09-1",
"subclasse": "6209-1/00",
"descricao": "Suporte técnico, manutenção e outros serviços em tecnologia da informação"
},
{
"id": "6311900",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.11-9",
"subclasse": "6311-9/00",
"descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na Internet"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
},
{
"id": "9512600",
"secao": "S",
"divisao": "95",
"grupo": "95.1",
"classe": "95.12-6",
"subclasse": "9512-6/00",
"descricao": "Reparação e manutenção de equipamentos de comunicação"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atualizado_em": "2023-11-11T03:00:00.000Z",
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
},
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2023-07-19T04:12:55.698Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "9000073850",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 23,
"nome": "Rio Grande do Sul",
"sigla": "RS",
"ibge_id": 43
}
},
{
"inscricao_estadual": "0629985490214",
"ativo": true,
"atualizado_em": "2023-11-04T03:00:00.000Z",
"estado": {
"id": 11,
"nome": "Minas Gerais",
"sigla": "MG",
"ibge_id": 31
}
},
{
"inscricao_estadual": "819017430118",
"ativo": true,
"atualizado_em": "2023-11-20T03:00:00.000Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
],
"inscricoes_suframa": [],
"regimes_tributarios": [
{
"ano": 2021,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2020,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2019,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2018,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2017,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2016,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2015,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
},
{
"ano": 2014,
"regime_tributario": "LUCRO REAL",
"forma_de_tributacao": "LUCRO REAL",
"atualizado_em": "2023-01-26T03:00:00.000Z"
}
]
}
}
```
# Consultando el Consumo de Solicitudes Mensuales
En este endpoint es posible consultar la cantidad de solicitudes que se han realizado por mes. Debes enviar el header `x_api_token` con el token o pasar el token por query string en la URL.
También puedes pasar el token como un parámetro en la URL, ejemplo:
`https://comercial.cnpj.ws/consumo?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/consumo`
**Atención:** Las consultas en este endpoint también cuentan como una solicitud a la API.
Ejemplo de Solicitud [#ejemplo-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const consumo = await consultarCNPJ.consumo(token);
console.log(consumo);
}
```
[Más información](https://www.npmjs.com/package/consultar-cnpj)
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado:
```json
{
"filtros_disponiveis": ["ano", "mes"],
"filtros_aplicados": {},
"ordenacao": ["ano", "mes"],
"data": [
{
"mes": 9,
"ano": 2021,
"quantidade": 1,
"atualizado_em": "2021-09-29T20:41:55.144Z",
"cnpjws_usuario_id": "d046b852-XXXX-XXXX-XXXX-8dccdf11d417"
}
]
}
```
# Consultando por la Raíz del CNPJ
En la API comercial también puedes hacer una consulta utilizando la raíz del CNPJ, que son los 8 primeros dígitos del CNPJ y que, en este caso, devolverá todos los CNPJs de la empresa en cuestión. En este endpoint, debes enviar el header `x_api_token` con el token que te fue enviado por correo electrónico.
También puedes pasar el token como un parámetro en la URL, ejemplo:
`https://comercial.cnpj.ws/cnpj-raiz/27865757?token=SEU_TOKEN`
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/cnpj-raiz/RAIZ_DO_CNPJ`
Ejemplo de Solicitud [#ejemplo-de-solicitud]
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getRaiz() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const data = await consultarCNPJ.raiz("27865757", token);
console.log(data);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Paginación [#paginación]
En caso de que la empresa tenga más de 20 filiales, la API dividirá la respuesta en páginas. Puedes verificar esto en el JSON de retorno de la API, en la propiedad "paginacion", que muestra la página actual, el total de páginas y el total de filiales:
```json
{
"paginacao": {
"limite": 20,
"pagina": 1,
"paginas": 5,
"total": 87
}
}
```
Para buscar una página específica basta con informar el número de la página en la solicitud:
```shell
curl -X GET https://comercial.cnpj.ws/cnpj-raiz/27865757?page=2 -H "x_api_token: SEU_TOKEN"
```
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por la raíz del CNPJ **27865757**:
```json
{
"data": [
"27865757002148",
"27865757002229",
"27865757002300",
"27865757002490",
"27865757002571",
"27865757002652",
"27865757002733",
"27865757002814",
"27865757002903",
"27865757003039",
"27865757003110",
"27865757003209",
"27865757003381",
"27865757003462",
"27865757003543",
"27865757003624",
"27865757003705",
"27865757003896",
"27865757003977",
"27865757004000"
],
"paginacao": {
"limite": 20,
"pagina": 2,
"paginas": 5,
"total": 87
},
"ordenacao": [],
"filtros_disponiveis": ["nome_fantasia", "pais_id", "estado_id", "cidade_id"],
"filtros_aplicados": {}
}
```
# API - Comercial
Esta sección contiene documentación detallada sobre la API Comercial, que ofrece varias funcionalidades relacionadas con la consulta de CNPJs, consumo de API y validación de inscripciones en Suframa. Aquí están los archivos contenidos:
* **Consultando CNPJ en la API Comercial**: Guía sobre cómo consultar información de CNPJ en la API Comercial.
* **Consultando el Consumo de Solicitudes Mensuales**: Instrucciones para consultar el consumo de solicitudes mensuales.
* **Consultando por la Raíz del CNPJ**: Explicación sobre cómo consultar la raíz del CNPJ y retornar todas las filiales asociadas.
* **Búsqueda de Empresas**: Información sobre cómo realizar búsquedas de empresas utilizando filtros.
* **Validando Inscripción en Suframa**: Detalles sobre la validación de inscripciones en Suframa.
Estos archivos ofrecen ejemplos de uso, incluyendo código en diferentes lenguajes, y describen las respuestas retornadas por la API.
# Búsqueda de Empresas
En la API Comercial, en el `Plan Premium`, puedes hacer búsquedas utilizando filtros para encontrar empresas que cumplan con tus requisitos.
**Atención:** El acceso a este endpoint es exclusivo para suscriptores del Plan Premium.
**Método:** `GET`
**Endpoint:** `https://comercial.cnpj.ws/v2/pesquisa?ADICIONE_OS_FILTROS`
Filtros [#filtros]
Puedes utilizar los filtros a continuación en tus consultas:
| Campo | Descripción |
| ------------------------------ | --------------------------------------------------------------------------------- |
| atividade\_principal\_id | Código CNAE |
| atividade\_secundaria\_id | Código CNAE |
| atividade\_id | Código CNAE (búsqueda en la actividad principal y secundaria) |
| natureza\_juridica\_id | Código de la Naturaleza Jurídica |
| razao\_social | Razón Social |
| nome\_fantasia | Nombre Fantasía |
| pais\_id | Código del País del BACEN |
| estado\_id | Código IBGE del estado |
| cidade\_id | Código IBGE de la Ciudad |
| cep | CEP |
| situacao\_cadastral | Situación cadastral en la Receita Federal |
| data\_situacao\_cadastral\_de | Fecha de la Situación Cadastral (A partir de esta fecha) en el formato YYYY-MM-DD |
| data\_situacao\_cadastral\_ate | Fecha de la Situación Cadastral (Hasta esta fecha) en el formato YYYY-MM-DD |
| porte\_id | Id del tamaño de la empresa |
| socio\_nome | Nombre del Socio |
| data\_inicio\_atividade\_de | Fecha de Inicio de Actividad (A partir de esta fecha) en el formato YYYY-MM-DD |
| data\_inicio\_atividade\_ate | Fecha de Inicio de Actividad (Hasta esta fecha) en el formato YYYY-MM-DD |
Es crucial destacar que las consultas realizadas en este endpoint se basan en nuestra base de datos y no en la de la Receita Federal. Por lo tanto, pueden ocurrir discrepancias entre las informaciones, ya que nuestra base de datos puede tener un desfase de hasta 45 días en relación con los datos actualizados de la Receita Federal. Vale resaltar que, aunque realizamos registros diariamente debido a las consultas de CNPJ hechas en la API, el desfase aún puede ocurrir.
**Lista de Situaciones Cadastrales:**
* Activa
* Dada de baja
* Inapta
* Nula
* Suspendida
**Lista de Tamaños Registrados:**
| ID | Descripción |
| -- | ------------------------- |
| 00 | No informado |
| 01 | Micro Empresa |
| 03 | Empresa de Pequeño Tamaño |
| 05 | Otros |
Ejemplos de Solicitud [#ejemplos-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const page = 2;
const data = await consultarCNPJ.pesquisa(
{ atividade_principal_id: "6203100", estado_id: 28 },
token,
page
);
console.log(data);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Paginación por Cursor [#paginación-por-cursor]
Cuando la búsqueda retorna más de **20 CNPJs**, la API divide la respuesta en múltiples páginas utilizando **paginación basada en cursor** (*cursor-based pagination*).
La información de paginación se retorna en el objeto `paginacao` del JSON de respuesta, que indica si existen páginas anteriores o siguientes y proporciona los **cursores necesarios para continuar la navegación**:
```json
{
"paginacao": {
"limite": 20,
"total": 320430,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMTkxMDAiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
}
}
```
**Primera página**
En la primera solicitud **no es necesario informar ningún cursor** — la API retornará automáticamente la primera página de resultados.
**Próxima página**
Para obtener la próxima página, utiliza el valor retornado en `proximo_cursor` como parámetro `cursor` en la próxima solicitud:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=eyJ2IjoiMDAwMDAwMDA2NzI5NjMiLCJkIjoiYXNjIiwibSI6ImV4YyJ9 -H "x_api_token: SEU_TOKEN"
```
La próxima página solo estará disponible cuando `tem_proxima_pagina` sea `true`.
**Página anterior**
En caso de que sea necesario retornar a la página anterior, utiliza el valor de `cursor_anterior`:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor= -H "x_api_token: SEU_TOKEN"
```
La página anterior solo estará disponible cuando `tem_pagina_anterior` sea `true`.
También es posible alterar la cantidad de CNPJs retornados, el valor predeterminado es 20 pero puede ser hasta 100:
```shell
curl -X GET https://comercial.cnpj.ws/v2/pesquisa?atividade_principal_id=6203100&limite=100 -H "x_api_token: SEU_TOKEN"
```
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por el CNAE **6203100**:
```json
{
"paginacao": {
"limite": 20,
"total": 38876,
"tem_proxima_pagina": true,
"tem_pagina_anterior": false,
"cursor_consulta_atual": null,
"cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMjgwMDAxMjkiLCJkIjoiYXNjIiwibSI6ImluYyJ9",
"proximo_cursor": "eyJ2IjoiMDAwMTA2NTcwMDAyMTAiLCJkIjoiYXNjIiwibSI6ImV4YyJ9",
"cursor_anterior": null
},
"filtros_disponiveis": [
"atividade_principal_id",
"atividade_secundaria_id",
"atividade_id",
"natureza_juridica_id",
"razao_social",
"nome_fantasia",
"pais_id",
"estado_id",
"cidade_id",
"cep",
"situacao_cadastral",
"data_situacao_cadastral_de",
"data_situacao_cadastral_ate",
"porte_id",
"socio_nome",
"socio_cpf_cnpj",
"data_inicio_atividade_de",
"data_inicio_atividade_ate"
],
"filtros_aplicados": {
"atividade_principal_id": "6203100"
},
"data": [
"00000028000129",
"00000135000157",
"00000266000215",
"00000342000101",
"00000390000108",
"00000544000153",
"00000635000199",
"00000664000150",
"00001713000170",
"00001871000120",
"00001871000200",
"00002440000188",
"00003800000166",
"00003821000181",
"00004032000165",
"00004387000154",
"00007190000250",
"00009301000186",
"00010657000130",
"00010657000210"
]
}
```
# Validando Inscripción en Suframa
En la API Comercial es posible hacer consultas de una inscripción en Suframa utilizando el método POST.
Recuerda enviar el CNPJ sin los caracteres especiales.
**Método:** `POST`
**Endpoint:** `https://comercial.cnpj.ws/suframa`
Ejemplos de Solicitud [#ejemplos-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const token = "INFORME O SEU TOKEN DE ACESSO";
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao, token);
console.log(empresa);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por el CNPJ **61940292006682** y inscripción **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# Consultando CNPJ en la API Pública
En la API pública es posible hacer hasta 3 consultas por minuto de un CNPJ utilizando el método GET. Esta consulta se realiza solo en nuestra base de datos.
Recuerda enviar el CNPJ sin los caracteres especiales.
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/NUMERO_DO_CNPJ_SEM_CARACTERES_ESPECIAIS`
Ejemplos de Solicitud [#ejemplos-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const empresa = await consultarCNPJ("27865757000102");
console.log(empresa);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por el CNPJ **27865757000102**:
```json
{
"cnpj_raiz": "27865757",
"razao_social": "GLOBO COMUNICACAO E PARTICIPACOES S/A",
"capital_social": "6983568523.86",
"responsavel_federativo": "",
"atualizado_em": "2021-07-20T05:41:44.884Z",
"porte": {
"id": "05",
"descricao": "Demais"
},
"natureza_juridica": {
"id": "2054",
"descricao": "Sociedade Anônima Fechada"
},
"qualificacao_do_responsavel": {
"id": 10,
"descricao": "Diretor "
},
"socios": [
{
"cpf_cnpj_socio": "***486498**",
"nome": "RAYMUNDO COSTA PINTO BARROS",
"tipo": "Pessoa Física",
"data_entrada": "2021-03-15",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***720677**",
"nome": "MANZAR GOMES FERES",
"tipo": "Pessoa Física",
"data_entrada": "2021-04-26",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***617850**",
"nome": "CARLOS HENRIQUE SCHRODER",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***632567**",
"nome": "JORGE LUIZ DE BARROS NOBREGA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "61 a 70 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***030727**",
"nome": "MARCELO LUIS MENDES SOARES DA SILVA",
"tipo": "Pessoa Física",
"data_entrada": "2014-12-12",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***048947**",
"nome": "PAULO DAUDT MARINHO",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***223047**",
"nome": "ERICK DE MIRANDA BRETAS",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "41 a 50 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***050187**",
"nome": "PEDRO BORGES GARCIA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***649137**",
"nome": "MANUEL LUIS ROQUETE CAMPELO BELMAR DA COSTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***834960**",
"nome": "CLAUDIA FALCAO DA MOTTA",
"tipo": "Pessoa Física",
"data_entrada": "2020-01-16",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
},
{
"cpf_cnpj_socio": "***492757**",
"nome": "RICARDO CAPILLE WADDINGTON",
"tipo": "Pessoa Física",
"data_entrada": "2021-06-24",
"cpf_representante_legal": "***000000**",
"nome_representante": null,
"faixa_etaria": "51 a 60 anos",
"atualizado_em": "2021-07-21T06:55:45.553Z",
"pais_id": "1058",
"qualificacao_socio": {
"id": 10,
"descricao": "Diretor "
},
"qualificacao_representante": null
}
],
"simples": null,
"estabelecimento": {
"cnpj": "27865757000102",
"atividades_secundarias": [
{
"id": "5911102",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/02",
"descricao": "Produção de filmes para publicidade"
},
{
"id": "5911199",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.11-1",
"subclasse": "5911-1/99",
"descricao": "Atividades de produção cinematográfica, de vídeos e de programas de televisão não especificadas anteriormente"
},
{
"id": "5912002",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.12-0",
"subclasse": "5912-0/02",
"descricao": "Serviços de mixagem sonora em produção audiovisual"
},
{
"id": "5913800",
"secao": "J",
"divisao": "59",
"grupo": "59.1",
"classe": "59.13-8",
"subclasse": "5913-8/00",
"descricao": "Distribuição cinematográfica, de vídeo e de programas de televisão"
},
{
"id": "5920100",
"secao": "J",
"divisao": "59",
"grupo": "59.2",
"classe": "59.20-1",
"subclasse": "5920-1/00",
"descricao": "Atividades de gravação de som e de edição de música"
},
{
"id": "6022501",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.22-5",
"subclasse": "6022-5/01",
"descricao": "Programadoras"
},
{
"id": "6204000",
"secao": "J",
"divisao": "62",
"grupo": "62.0",
"classe": "62.04-0",
"subclasse": "6204-0/00",
"descricao": "Consultoria em tecnologia da informação"
},
{
"id": "6319400",
"secao": "J",
"divisao": "63",
"grupo": "63.1",
"classe": "63.19-4",
"subclasse": "6319-4/00",
"descricao": "Portais, provedores de conteúdo e outros serviços de informação na Internet"
},
{
"id": "6463800",
"secao": "K",
"divisao": "64",
"grupo": "64.6",
"classe": "64.63-8",
"subclasse": "6463-8/00",
"descricao": "Outras sociedades de participação, exceto holdings"
},
{
"id": "7020400",
"secao": "M",
"divisao": "70",
"grupo": "70.2",
"classe": "70.20-4",
"subclasse": "7020-4/00",
"descricao": "Atividades de consultoria em gestão empresarial, exceto consultoria técnica específica"
},
{
"id": "7490104",
"secao": "M",
"divisao": "74",
"grupo": "74.9",
"classe": "74.90-1",
"subclasse": "7490-1/04",
"descricao": "Atividades de intermediação e agenciamento de serviços e negócios em geral, exceto imobiliários"
},
{
"id": "7739099",
"secao": "N",
"divisao": "77",
"grupo": "77.3",
"classe": "77.39-0",
"subclasse": "7739-0/99",
"descricao": "Aluguel de outras máquinas e equipamentos comerciais e industriais não especificados anteriormente, sem operador"
},
{
"id": "7740300",
"secao": "N",
"divisao": "77",
"grupo": "77.4",
"classe": "77.40-3",
"subclasse": "7740-3/00",
"descricao": "Gestão de ativos intangíveis não financeiros"
},
{
"id": "9001902",
"secao": "R",
"divisao": "90",
"grupo": "90.0",
"classe": "90.01-9",
"subclasse": "9001-9/02",
"descricao": "Produção musical"
},
{
"id": "9319101",
"secao": "R",
"divisao": "93",
"grupo": "93.1",
"classe": "93.19-1",
"subclasse": "9319-1/01",
"descricao": "Produção e promoção de eventos esportivos"
}
],
"cnpj_raiz": "27865757",
"cnpj_ordem": "0001",
"cnpj_digito_verificador": "02",
"tipo": "Matriz",
"nome_fantasia": "TV/REDE/CANAIS/G2C+GLOBO SOMLIVRE GLOBO.COM GLOBOPLAY",
"situacao_cadastral": "Ativa",
"data_situacao_cadastral": "2005-11-03",
"data_inicio_atividade": "1986-01-31",
"nome_cidade_exterior": null,
"tipo_logradouro": "RUA",
"logradouro": "LOPES QUINTAS",
"numero": "303",
"complemento": null,
"bairro": "JARDIM BOTANICO",
"cep": "22460901",
"ddd1": "21",
"telefone1": "21554551",
"ddd2": "21",
"telefone2": "21554552",
"ddd_fax": "21",
"fax": "25408773",
"email": null,
"situacao_especial": null,
"data_situacao_especial": null,
"atividade_principal": {
"id": "6021700",
"secao": "J",
"divisao": "60",
"grupo": "60.2",
"classe": "60.21-7",
"subclasse": "6021-7/00",
"descricao": "Atividades de televisão aberta"
},
"pais": {
"id": "1058",
"iso2": "BR",
"iso3": "BRA",
"nome": "Brasil",
"comex_id": "105"
},
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
},
"cidade": {
"id": 3243,
"nome": "Rio de Janeiro",
"ibge_id": 3304557,
"siafi_id": "6001"
},
"motivo_situacao_cadastral": null,
"inscricoes_estaduais": [
{
"inscricao_estadual": "84295760",
"ativo": true,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "84347353",
"ativo": false,
"atualizado_em": "2021-08-13T15:11:08.241Z",
"estado": {
"id": 19,
"nome": "Rio de Janeiro",
"sigla": "RJ",
"ibge_id": 33
}
},
{
"inscricao_estadual": "113717433112",
"ativo": false,
"atualizado_em": "2021-08-18T20:40:56.654Z",
"estado": {
"id": 26,
"nome": "São Paulo",
"sigla": "SP",
"ibge_id": 35
}
}
]
}
}
```
# API - Pública
Esta sección contiene documentación sobre la API Pública, que permite la consulta de información sobre empresas brasileñas con límites específicos de uso. Los documentos incluyen:
* **Consultando CNPJ en la API Pública**: Guía sobre cómo consultar información de CNPJ en la API Pública.
* **Limitaciones**: Información sobre las limitaciones de uso de la API Pública, como límites de solicitudes por minuto.
* **Validando Inscripción en Suframa en la API Pública**: Detalles sobre cómo validar inscripciones en Suframa utilizando la API Pública.
Estos documentos están dirigidos a usuarios que necesitan acceso público y limitado a información empresarial.
# Limitaciones
La API Pública tiene la limitación de atender solo 3 solicitudes por minuto desde una misma IP, entienda que esta limitación es independiente del hecho de que la consulta haya tenido éxito al encontrar el CNPJ. Después de superar este límite, el solicitante tendrá que esperar a que se completen los 60 segundos para poder hacer la próxima solicitud.
El usuario recibirá un mensaje de error y el código de estado HTTP 429:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 3 consultas por minuto. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
Si la API detecta un volumen anormal de errores — más de 360 errores HTTP 429 en la misma hora, señal de que el solicitante sigue insistiendo incluso después de ser bloqueado — la IP será penalizada y no podrá hacer consultas durante 1 hora. Si el comportamiento persiste, el bloqueo se renovará por otra hora. Ejemplo:
```shell
{
"status": 429,
"titulo": "Muitas requisições",
"detalhes": "Excedido o limite máximo de 360 erros HTTP 429 por hora. Liberação ocorrerá em Thu Jun 03 2021 16:15:00 GMT-0300 (Horário Padrão de Brasília)"
}
```
Omisión de datos personales [#omisión-de-datos-personales]
Algunos CNPJs pueden devolver el campo `observacao` indicando que parte de los datos fue omitida a pedido del responsable de la empresa. Los campos sensibles (dirección completa, contacto, documentos de socios, rango de edad, etc.) se devuelven como `null` o reducidos, sin eliminar claves del JSON. La API Comercial autenticada no aplica esta omisión.
# Validando Inscripción en Suframa en la API Pública
En la API Pública es posible hacer hasta 3 consultas por minuto de una inscripción en Suframa utilizando el método POST.
Recuerda enviar el CNPJ sin los caracteres especiales.
**Método:** `POST`
**Endpoint:** `https://publica.cnpj.ws/suframa`
Ejemplos de Solicitud [#ejemplos-de-solicitud]
Nosotros tenemos un paquete que puede ayudarte en la integración con JavaScript:
```shell
yarn add consultar-cnpj
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
const cnpj = "61940292006682";
const incricao = "210140267";
const empresa = await consultarCNPJ.suframa(cnpj, incricao);
console.log(empresa);
}
```
[Más información del paquete](https://www.npmjs.com/package/consultar-cnpj)
Ejemplo de Retorno [#ejemplo-de-retorno]
A continuación, un ejemplo del JSON retornado al buscar por el CNPJ **61940292006682** y la inscripción **210140267**:
```json
{
"cnpj_raiz": "61940292",
"cnpj": "61940292006682",
"inscricao_suframa": "210140267",
"ativo": true,
"atualizado_em": "2022-01-16T12:28:32.384Z"
}
```
# CNPJ Alfanumérico de Prueba
Usa el CNPJ de ejemplo `UKPVME1E8HI996` para probar tu integración con el nuevo formato
A partir de julio de 2026, la Receita Federal de Brasil podrá emitir nuevas inscripciones de CNPJ en formato alfanumérico (con letras y números). Las inscripciones existentes no se modificarán. Si quieres entender cómo funciona el nuevo formato y cómo calcular los dígitos verificadores, consulta el artículo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
La API de CNPJ.ws ya está preparada para el nuevo formato. Para ayudar a quienes están adaptando sus sistemas, creamos un **CNPJ alfanumérico de ejemplo** que puedes usar para probar tu validación de dígitos verificadores y tu integración con la API antes de que las inscripciones reales entren en circulación.
CNPJ de ejemplo [#cnpj-de-ejemplo]
```
UKPVME1E8HI996
```
Formateado, queda así:
```
UK.PVM.E1E/8HI9-96
```
Observa su estructura, que sigue el mismo patrón del CNPJ actual:
| Parte | Valor | Descripción |
| --------------------- | ---------- | ---------------------------------------------------------- |
| Raíz | `UKPVME1E` | Identifica a la empresa (8 caracteres alfanuméricos) |
| Orden | `8HI9` | Identifica al establecimiento (4 caracteres alfanuméricos) |
| Dígitos verificadores | `96` | Dígitos de verificación (2 caracteres, siempre numéricos) |
Los dígitos verificadores `96` se calcularon a partir de los doce primeros caracteres usando módulo 11, exactamente como se describe en el artículo [CNPJ Alfanumérico](https://docs.cnpj.ws/blog/cnpj-alfanumerico). Es decir: es un CNPJ válido desde el punto de vista del algoritmo, ideal para validar tu implementación.
Probar la validación de los dígitos verificadores [#probar-la-validación-de-los-dígitos-verificadores]
Si implementaste el cálculo de los dígitos verificadores en tu sistema, ejecuta el algoritmo sobre los doce primeros caracteres (`UKPVME1E8HI9`) y comprueba que el resultado sea `96`. Si coincide, tu validación es correcta.
Para comprobarlo manualmente, basta con sustituir cada carácter por su valor (ASCII − 48), aplicar los pesos de 2 a 9 de derecha a izquierda y obtener el resto de la división por 11 — el paso a paso completo está en el [artículo del cálculo](https://docs.cnpj.ws/blog/cnpj-alfanumerico).
Probar en la API de CNPJ.ws [#probar-en-la-api-de-cnpjws]
El CNPJ de ejemplo se puede enviar directamente a la API, **sin caracteres especiales** (sin puntos, barra ni guion).
**Método:** `GET`
**Endpoint:** `https://publica.cnpj.ws/cnpj/UKPVME1E8HI996`
**Ejemplo con cURL**
```shell
curl https://publica.cnpj.ws/cnpj/UKPVME1E8HI996
```
**Ejemplo con JavaScript / Node.js**
Usando `fetch`:
```js
async function consultarCNPJ(cnpj) {
const respuesta = await fetch(`https://publica.cnpj.ws/cnpj/${cnpj}`);
const datos = await respuesta.json();
console.log(datos);
}
consultarCNPJ("UKPVME1E8HI996");
```
**Ejemplo con el paquete `consultar-cnpj`**
También mantenemos el paquete oficial [`consultar-cnpj`](https://github.com/cnpj-ws/consultar-cnpj) ([npm](https://www.npmjs.com/package/consultar-cnpj)), que facilita la integración en Node.js. **A partir de la versión 1.0.21 ya acepta CNPJ alfanumérico**, así que basta con actualizar a la última versión:
```shell
yarn add consultar-cnpj
# o
npm i consultar-cnpj --save
```
```js
const consultarCNPJ = require("consultar-cnpj");
async function getCNPJ() {
// El token es opcional — sin él, se usa la API Pública (3 consultas/min)
const token = "INGRESA TU TOKEN DE ACCESO";
try {
const empresa = await consultarCNPJ("UKPVME1E8HI996", token);
console.log(empresa);
} catch (e) {
console.log(e);
}
}
getCNPJ();
```
> **Importante:** al tratarse de un CNPJ ficticio, creado únicamente para pruebas, **no devuelve datos registrales de una empresa real**. El objetivo es validar que tu aplicación acepta, procesa y envía el formato alfanumérico correctamente en toda la cadena — desde el formulario hasta la llamada a la API. Para recibir datos reales, utiliza un CNPJ existente.
# Cómo automatizar el registro de clientes con una API de consulta CNPJ
¿Cuántas veces su equipo ya digitó razón social, dirección, CNAE e inscripción estatal de un cliente nuevo — campo por campo — copiando de la tarjeta CNPJ de la Receita Federal? Además de lento, ese proceso es la principal puerta de entrada de errores de registro: un dígito equivocado en el CNPJ, una dirección desactualizada, una razón social abreviada de forma distinta en cada sistema.
La buena noticia es que nada de eso necesita ser manual. Con una **API de consulta CNPJ**, su sistema le pide al usuario un solo dato — el número del CNPJ — y completa todo lo demás por sí mismo, con información oficial y actualizada. En este post mostramos cómo funciona ese flujo, cómo implementarlo con la API de CNPJ.ws y cómo un ERP brasileño usa exactamente ese enfoque en producción.
El problema del registro manual [#el-problema-del-registro-manual]
Todo sistema que atiende empresas — ERP, CRM, plataforma de cobranza, e-commerce B2B — necesita registrar personas jurídicas. En el flujo manual, eso significa un formulario con 10 a 20 campos que alguien completa consultando documentos. Los costos aparecen en tres frentes:
* **Tiempo**: cada registro consume minutos de trabajo repetitivo, multiplicado por todos los clientes y proveedores de la base.
* **Errores**: la digitación manual genera divergencias que se propagan a facturas, boletos y contratos — y retrabajo para corregirlas.
* **Datos desactualizados**: la empresa cambia de dirección o de situación registral, y el registro en el sistema sigue con la información antigua.
Cómo funciona una API de consulta CNPJ [#cómo-funciona-una-api-de-consulta-cnpj]
Una API de consulta CNPJ expone los datos públicos de las empresas brasileñas en formato estructurado (JSON), listo para ser consumido por cualquier aplicación. En el caso de CNPJ.ws, una única solicitud HTTP devuelve razón social, nombre de fantasía, situación registral, naturaleza jurídica, tamaño, dirección completa, CNAEs, cuadro societario, inscripciones estatales y régimen tributario (Simples Nacional/MEI).
El flujo de automatización tiene tres pasos:
1\. El usuario informa solo el CNPJ [#1-el-usuario-informa-solo-el-cnpj]
En el formulario de registro, el único campo obligatorio pasa a ser el CNPJ. Conviene validar los dígitos verificadores en el front-end antes de consultar, evitando llamadas innecesarias.
2\. El sistema consulta la API [#2-el-sistema-consulta-la-api]
```bash
curl https://publica.cnpj.ws/cnpj/00000000000191
```
La respuesta trae el objeto completo de la empresa. La API pública de CNPJ.ws permite hasta 3 consultas por minuto — suficiente para probar y para volúmenes bajos. Para uso en producción, la API comercial ofrece límites mayores, datos adicionales y SLA.
3\. El formulario se completa solo [#3-el-formulario-se-completa-solo]
Con la respuesta en mano, el sistema completa todos los campos: razón social, dirección, CNAE principal, régimen tributario. El usuario solo revisa y confirma. Lo que antes llevaba minutos pasa a llevar segundos — y los datos llegan exactamente como constan en la base oficial.
Caso real: registro de clientes por IA en bitERP [#caso-real-registro-de-clientes-por-ia-en-biterp]
Un ejemplo de quien usa ese flujo en producción es [bitERP, un ERP con inteligencia artificial](https://www.biterp.ai), desarrollado en Brasil. En bitERP, el usuario puede pedir en el chat algo como *"registra el cliente CNPJ 00.000.000/0001-00"* — y el agente de IA consulta la API de CNPJ.ws, completa el registro entero en la pantalla y solo pide la confirmación final.
La combinación es interesante porque une dos automatizaciones: la IA elimina la navegación por menús y formularios, y la API de consulta CNPJ elimina la búsqueda y digitación de los datos. El resultado es un onboarding de cliente que se resuelve en una única frase, con datos oficiales de la Receita Federal — sin error de digitación y sin registro incompleto.
El mismo patrón se aplica a proveedores, transportistas y cualquier otra entidad jurídica del sistema.
Buenas prácticas al integrar [#buenas-prácticas-al-integrar]
Para sacar el máximo provecho de la integración, vale seguir algunas recomendaciones:
* **Valide el CNPJ antes de consultar** — el dígito verificador es un cálculo local, no gaste una solicitud con un número inválido.
* **Trate los límites de solicitudes** — implemente retry con backoff para el error 429 y considere la API comercial para volumen.
* **Guarde la fecha de la consulta** — los datos registrales cambian; saber cuándo se sincronizó el registro permite programar actualizaciones periódicas.
* **Alerta de situación registral** — si la empresa consta como baja, suspendida o inapta, señálelo antes de concluir el registro. Eso evita emitir factura para un CNPJ irregular.
* **Deje que el usuario revise** — la automatización completa, el humano confirma. Especialmente campos que el cliente puede querer sobrescribir, como el nombre de fantasía.
Comience ahora [#comience-ahora]
Puede probar la consulta en este momento, sin registro: basta llamar a `https://publica.cnpj.ws/cnpj/{número}` y ver el JSON devuelto. Para llevar la integración a producción, conozca los [planes de la API comercial de CNPJ.ws](https://www.cnpj.ws/es-ES#precos) — y si quiere ver el flujo de registro automatizado funcionando dentro de un ERP, el ejemplo de bitERP muestra hasta dónde puede llegar esa automatización.