# 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**. {% hint style="warning" %} **Atenção:** O acesso a esse endpoint é exclusivo para assinantes do Plano Premium. {% endhint %} **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 ## Pesquisa avançada de CNPJs (v2 - paginação por cursor) > Pesquisa de empresas com \*\*paginação baseada em cursor\*\* (recomendada). Ordenação fixa por CNPJ ASC.\ > \ > \*\*Como usar a paginação por cursor\*\*\ > 1\. Primeira requisição: envie os filtros e \`limite\` (ex.: 20). Não envie \`cursor\`.\ > 2\. Use o campo \`proximo\_cursor\` da resposta para a próxima página.\ > 3\. Próxima requisição: repita os mesmos filtros e envie \`cursor\` com o valor de \`proximo\_cursor\`.\ > 4\. Quando \`tem\_proxima\_pagina\` for \`false\`, não há mais páginas.\ > \ > \*\*Estrutura do cursor\*\* \ > O cursor é um Base64URL de um JSON: \`{ "v": "CNPJ 14 dígitos", "d": "asc", "m": "inc" ou "exc" }\`.\ > Não é necessário decodificar; use o valor retornado em \`proximo\_cursor\` na próxima requisição.\ > \ > \*\*Exemplos\*\*\ > \- Primeira página: \`GET /v2/pesquisa?razao\_social=LTDA\&limite=20\`\ > \- Próxima página: \`GET /v2/pesquisa?razao\_social=LTDA\&limite=20\&cursor=eyJ2Ijoi...\`
```json {"openapi":"3.0.1","info":{"title":"API CNPJ WS Comercial","version":"0.0.1"},"tags":[{"name":"Pesquisa","description":"Pesquisa de empresas com filtros (v2 com paginação por cursor)"}],"servers":[{"url":"https://comercial.cnpj.ws","description":"API Comercial"}],"security":[{"x_api_token":[]},{"bearerAuth":[]},{"token":[]}],"components":{"securitySchemes":{"x_api_token":{"type":"apiKey","in":"header","name":"x_api_token","description":"Token de autenticação no header"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token de API (Bearer). Ex.: Authorization: Bearer "},"token":{"type":"apiKey","in":"query","name":"token","description":"Token de autenticação na query string"}},"schemas":{"RespostaPesquisaCursor":{"type":"object","description":"Resposta da pesquisa v2 (paginação por cursor)","required":["paginacao","filtros_disponiveis","filtros_aplicados","data"],"properties":{"paginacao":{"$ref":"#/components/schemas/PaginacaoCursor"},"filtros_disponiveis":{"type":"array","items":{"type":"string"},"description":"Lista de filtros disponíveis para pesquisa"},"filtros_aplicados":{"type":"object","additionalProperties":true,"description":"Filtros aplicados na consulta"},"data":{"type":"array","items":{"type":"string"},"description":"Lista de CNPJs encontrados (14 dígitos)"}}},"PaginacaoCursor":{"type":"object","description":"Paginação baseada em cursor (v2)","required":["limite","total","tem_proxima_pagina","tem_pagina_anterior"],"properties":{"limite":{"type":"integer","description":"Quantidade de itens por página"},"total":{"type":"integer","description":"Total de registros encontrados"},"tem_proxima_pagina":{"type":"boolean","description":"Indica se existem mais páginas à frente"},"tem_pagina_anterior":{"type":"boolean","description":"Indica se existem páginas anteriores"},"cursor_consulta_atual":{"type":"string","nullable":true,"description":"Cursor usado na requisição (para idempotência/replay)"},"cursor_pagina_atual":{"type":"string","nullable":true,"description":"Cursor do primeiro item da página (para bookmark/compartilhar)"},"proximo_cursor":{"type":"string","nullable":true,"description":"Cursor para avançar para a próxima página. Use este valor no parâmetro `cursor` da próxima requisição."},"cursor_anterior":{"type":"string","nullable":true,"description":"Cursor para voltar para a página anterior (navegação reversa não implementada inicialmente)"}}},"ErroResposta":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"titulo":{"type":"string"},"detalhes":{"type":"string"},"validacao":{"type":"array","items":{"type":"string"}},"statusCode":{"type":"integer","description":"Código HTTP (usado em respostas de erro da API)"},"message":{"type":"string","description":"Mensagem de erro"},"error":{"type":"string","description":"Nome do erro HTTP"}}}}},"paths":{"/v2/pesquisa":{"get":{"tags":["Pesquisa"],"summary":"Pesquisa avançada de CNPJs (v2 - paginação por cursor)","description":"Pesquisa de empresas com **paginação baseada em cursor** (recomendada). Ordenação fixa por CNPJ ASC.\n\n**Como usar a paginação por cursor**\n1. Primeira requisição: envie os filtros e `limite` (ex.: 20). Não envie `cursor`.\n2. Use o campo `proximo_cursor` da resposta para a próxima página.\n3. Próxima requisição: repita os mesmos filtros e envie `cursor` com o valor de `proximo_cursor`.\n4. Quando `tem_proxima_pagina` for `false`, não há mais páginas.\n\n**Estrutura do cursor** \nO cursor é um Base64URL de um JSON: `{ \"v\": \"CNPJ 14 dígitos\", \"d\": \"asc\", \"m\": \"inc\" ou \"exc\" }`.\nNão é necessário decodificar; use o valor retornado em `proximo_cursor` na próxima requisição.\n\n**Exemplos**\n- Primeira página: `GET /v2/pesquisa?razao_social=LTDA&limite=20`\n- Próxima página: `GET /v2/pesquisa?razao_social=LTDA&limite=20&cursor=eyJ2Ijoi...`\n","operationId":"pesquisarV2","parameters":[{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor para a próxima página (obtido em `proximo_cursor` da resposta anterior). Não enviar na primeira requisição."},{"name":"limite","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Quantidade de itens por página (1 a 100)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Alias para `limite`"},{"name":"atividade_principal_id","in":"query","schema":{"type":"string"},"description":"Código CNAE da atividade principal"},{"name":"atividade_secundaria_id","in":"query","schema":{"type":"string"},"description":"Código CNAE da atividade secundária"},{"name":"atividade_id","in":"query","schema":{"type":"string"},"description":"Código CNAE (pesquisa na atividade principal e secundária)"},{"name":"natureza_juridica_id","in":"query","schema":{"type":"string"},"description":"Código da Natureza Jurídica"},{"name":"razao_social","in":"query","schema":{"type":"string","minLength":3},"description":"Razão Social (mín. 3 caracteres)"},{"name":"nome_fantasia","in":"query","schema":{"type":"string"},"description":"Nome Fantasia"},{"name":"pais_id","in":"query","schema":{"type":"string"},"description":"Código do País do BACEN"},{"name":"estado_id","in":"query","schema":{"type":"string"},"description":"Código IBGE do estado"},{"name":"cidade_id","in":"query","schema":{"type":"string"},"description":"Código IBGE da Cidade"},{"name":"cep","in":"query","schema":{"type":"string"},"description":"CEP"},{"name":"situacao_cadastral","in":"query","schema":{"type":"string"},"description":"Situação cadastral na Receita Federal"},{"name":"data_situacao_cadastral_de","in":"query","schema":{"type":"string","format":"date"},"description":"Data da Situação Cadastral (a partir de) YYYY-MM-DD"},{"name":"data_situacao_cadastral_ate","in":"query","schema":{"type":"string","format":"date"},"description":"Data da Situação Cadastral (até) YYYY-MM-DD"},{"name":"porte_id","in":"query","schema":{"type":"string"},"description":"Id do porte da empresa"},{"name":"socio_nome","in":"query","schema":{"type":"string"},"description":"Nome do Sócio"},{"name":"socio_cpf_cnpj","in":"query","schema":{"type":"string"},"description":"CPF ou CNPJ do Sócio (apenas dígitos)"},{"name":"data_inicio_atividade_de","in":"query","schema":{"type":"string","format":"date"},"description":"Data de Início de Atividade (a partir de) YYYY-MM-DD"},{"name":"data_inicio_atividade_ate","in":"query","schema":{"type":"string","format":"date"},"description":"Data de Início de Atividade (até) YYYY-MM-DD"},{"name":"token","in":"query","schema":{"type":"string"},"description":"Token de autenticação (opcional)","required":false},{"name":"x_api_token","in":"header","schema":{"type":"string"},"description":"Token de autenticação (opcional)","required":false}],"responses":{"200":{"description":"Lista de CNPJs encontrados com paginação por cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespostaPesquisaCursor"}}}},"400":{"description":"Parâmetros inválidos ou cursor inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroResposta"}}}},"401":{"description":"Token de API inválido ou não fornecido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroResposta"}}}},"403":{"description":"Plano não permite pesquisa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroResposta"}}}}}}}}} ``` 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 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 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" ``` {% hint style="warning" %} A próxima página só estará disponível quando `tem_proxima_pagina` for `true`. {% endhint %} 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" ``` {% hint style="warning" %} A página anterior só estará disponível quando `tem_pagina_anterior` for `true`. {% endhint %} 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 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" ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cnpj.ws/referencia-de-api/api-comercial/pesquisa-de-empresas.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.