Búsqueda de Empresas

Cómo buscar empresas por filtros en la API Comercial de CNPJ.ws (Plan Premium), con paginación basada en cursor.

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

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
01	No informado
02	Micro Empresa
03	Empresa de Pequeño Tamaño
05	Otros

Ejemplos de Solicitud

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

Nosotros tenemos un paquete que puede ayudarte en la integración con 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);
}

Más información del paquete

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:

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

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:

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

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

Ejemplo de Retorno

A continuación, un ejemplo del JSON retornado al buscar por el 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"
  ]
}

Búsqueda 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`