Pesquisa de Empresas

Como pesquisar empresas por filtros na API Comercial do CNPJ.ws (Plano Premium), com paginação baseada em cursor.

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

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
01	Não informado
02	Micro Empresa
03	Empresa de Pequeno Porte
05	Demais

Exemplos de Requisição

Authorization

x_api_token<token>

Token de autenticação no header

In: header

Query Parameters

cursor?string

Cursor para a próxima página (obtido em proximo_cursor da resposta anterior). Não enviar na primeira requisição.

limite?integer

Quantidade de itens por página (1 a 100)

Range1 <= value <= 100

Default20

limit?integer

Alias para limite

Range1 <= value <= 100

atividade_principal_id?string

Código CNAE da atividade principal

atividade_secundaria_id?string

Código CNAE da atividade secundária

atividade_id?string

Código CNAE (pesquisa na atividade principal e secundária)

natureza_juridica_id?string

Código da Natureza Jurídica

razao_social?string

Razão Social (mín. 3 caracteres)

Length3 <= length

nome_fantasia?string

Nome Fantasia

pais_id?string

Código do País do BACEN

estado_id?string

Código IBGE do estado

cidade_id?string

Código IBGE da Cidade

cep?string

CEP

situacao_cadastral?string

Situação cadastral na Receita Federal

data_situacao_cadastral_de?string

Data da Situação Cadastral (a partir de) YYYY-MM-DD

Formatdate

data_situacao_cadastral_ate?string

Data da Situação Cadastral (até) YYYY-MM-DD

Formatdate

porte_id?string

Id do porte da empresa

socio_nome?string

Nome do Sócio

socio_cpf_cnpj?string

CPF ou CNPJ do Sócio (apenas dígitos)

data_inicio_atividade_de?string

Data de Início de Atividade (a partir de) YYYY-MM-DD

Formatdate

data_inicio_atividade_ate?string

Data de Início de Atividade (até) YYYY-MM-DD

Formatdate

token?string

Token de autenticação (opcional)

Header Parameters

x_api_token?string

Token de autenticação (opcional)

Response Body

`application/json`

curl -X GET "https://example.com/v2/pesquisa"

{  "paginacao": {    "limite": 20,    "total": 1523,    "tem_proxima_pagina": true,    "tem_pagina_anterior": false,    "cursor_consulta_atual": null,    "cursor_pagina_atual": "eyJ2IjoiMDAwMDAwMDAwMDAwNDIiLCJkIjoiYXNjIiwibSI6ImluYyJ9",    "proximo_cursor": "eyJ2IjoiMDAwMDAwMDAwMDAwNjciLCJkIjoiYXNjIiwibSI6ImV4YyJ9",    "cursor_anterior": null  },  "filtros_disponiveis": [    "atividade_principal_id",    "estado_id",    "cidade_id"  ],  "filtros_aplicados": {    "atividade_principal_id": "0111",    "estado_id": 35  },  "data": [    "00000000000042",    "00000000000050"  ]}

{  "statusCode": 400,  "message": "Cursor inválido: formato incorreto",  "error": "Bad Request"}

{  "status": 0,  "titulo": "string",  "detalhes": "string",  "validacao": [    "string"  ],  "statusCode": 0,  "message": "string",  "error": "string"}

{  "statusCode": 403,  "message": "Recurso não disponível para plano gratuito",  "error": "Forbidden"}

Nós possuímos um pacote que pode te ajudar na integração com JavaScript:

yarn add consultar-cnpj

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

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.

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

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:

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:

curl -X GET https://comercial.cnpj.ws/v2/pesquisa?cursor=<cursor_anterior> -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:

curl -X GET https://comercial.cnpj.ws/v2/pesquisa?atividade_principal_id=6203100&limite=100 -H "x_api_token: SEU_TOKEN"

Exemplo de Retorno

Abaixo um exemplo do JSON retornado ao se pesquisar pelo CNAE 6203100:

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

Pesquisa de Empresas

200application/json

400application/json

401application/json

403application/json

Primeira página (sem cursor)

Próxima página (com cursor)

Última página

Cursor inválido

Nenhum filtro informado

Plano gratuito

Plano sem permissão de filtros

On this page

`application/json`

`application/json`

`application/json`

`application/json`