Guia de Filtros da API - Consulta de Empresas

Este documento descreve como filtrar dados empresariais utilizando a API. Todos os filtros seguem o padrão de query com objeto $filter.

Estrutura Básica

{
  "$filter": {
    "$and": [{ "campo": "valor" }, { "outro_campo": "outro_valor" }]
  }
}

Você também pode usar $or para filtros alternativos:

{
  "$filter": {
    "$or": [{ "campo": "valor1" }, { "campo": "valor2" }]
  }
}

1. Identificação (5 campos)

1.1 CNPJ Completo

{
  "$filter": {
    "cnpj": 630544000137
  }
}

1.2 Raiz do CNPJ (primeiros 8 dígitos)

{
  "$filter": {
    "raiz_cnpj": 630544
  }
}

Útil para encontrar todas as filiais de uma mesma empresa

1.3 Dígito Verificador do CNPJ

{
  "$filter": {
    "dv_cnpj": 37
  }
}

{
  "$filter": {
    "razao_social": "RAZAO SOCIAL LTDA"
  }
}

1.5 Nome Fantasia

{
  "$filter": {
    "nome_fantasia": "NOME FANTASIA"
  }
}

2. Situação (2 campos)

2.1 Situação Cadastral

{
  "$filter": {
    "situacao_cadastral": "ATIVA"
  }
}

Valores possíveis: ATIVA, BAIXADA, SUSPENSA, INAPTA, NULA

2.2 Data de Início de Atividade

{
  "$filter": {
    "$and": [
      { "data_inicio_atividade": { "$gte": "2020-01-01" } },
      { "data_inicio_atividade": { "$lte": "2023-12-31" } }
    ]
  }
}

Filtrar empresas abertas entre 2020 e 2023

3. Classificação (6 campos)

3.1 Natureza Jurídica

{
  "$filter": {
    "natureza_juridica": "SOCIEDADE EMPRESARIA LIMITADA"
  }
}

Valores possíveis incluem:

EMPRESARIO (INDIVIDUAL)

SOCIEDADE EMPRESARIA LIMITADA

SOCIEDADE ANONIMA ABERTA

SOCIEDADE ANONIMA FECHADA

SOCIEDADE DE ECONOMIA MISTA

SOCIEDADE EM CONTA DE PARTICIPACAO

SOCIEDADE EMPRESARIA EM COMANDITA POR ACOES

SOCIEDADE EMPRESARIA EM COMANDITA SIMPLES

SOCIEDADE EMPRESARIA EM NOME COLETIVO

ORGAO PUBLICO DO PODER EXECUTIVO MUNICIPAL

ORGAO PUBLICO DO PODER JUDICIARIO ESTADUAL

ORGAO PUBLICO DO PODER JUDICIARIO FEDERAL

ORGAO PUBLICO DO PODER LEGISLATIVO ESTADUAL OU DO DISTRITO FEDERAL

ORGAO PUBLICO DO PODER LEGISLATIVO FEDERAL

ORGAO PUBLICO DO PODER LEGISLATIVO MUNICIPAL

SERVICO NOTARIAL E REGISTRAL (CARTORIO)

SERVICO SOCIAL AUTONOMO

PRODUTOR RURAL (PESSOA FISICA)

REPRESENTACAO DIPLOMATICA ESTRANGEIRA

OUTRAS INSTITUICOES EXTRATERRITORIAIS

PLANO DE BENEFICIOS DE PREVIDENCIA COMPLEMENTAR FECHADA

Entre outros

3.2 Porte

{
  "$filter": {
    "porte": "MICRO EMPRESA"
  }
}

Valores: NAO INFORMADO, MICRO EMPRESA, PEQUENO PORTE, DEMAIS

3.3 Empresa Público/Privada

{
  "$filter": {
    "empresa_publico_privada": "PRIVADA"
  }
}

Valores: PRIVADA, PUBLICA ou MISTA

3.4 Matriz

{
  "$filter": {
    "matriz": "TRUE" // ou "FALSE"
  }
}

3.5 Quantidade de Filiais

{
  "$filter": {
    "qtde_filiais": { "$gte": 10 }
  }
}

Empresas com 10 ou mais filiais

3.6 Segmento

{
  "$filter": {
    "segmento": "SERVICOS"
  }
}

Valores: COMERCIO, INDUSTRIA, SERVICOS, AGROPECUARIA, CONSTRUCAO CIVIL

4. CNAE (8 campos)

4.1 CNAE Principal - Classe (código)

{
  "$filter": {
    "cnae_principal_classe": 66193
  }
}

4.2 CNAE Principal - Subclasse (código)

{
  "$filter": {
    "cnae_principal_subclasse": 6619302
  }
}

4.3 CNAE Principal - Descrição Classe

{
  "$filter": {
    "cnae_principal_desc_classe": "66193 - ATIVIDADES AUXILIARES DOS SERVICOS FINANCEIROS NAO ESPECIFICADAS ANTERIORMENTE"
  }
}

4.4 CNAE Principal - Descrição Subclasse

{
  "$filter": {
    "cnae_principal_desc_subclasse": "6619302 - CORRESPONDENTES DE INSTITUICOES FINANCEIRAS"
  }
}

4.5 CNAE Principal - Descrição Divisão

{
  "$filter": {
    "cnae_principal_desc_divisao": "66 - ATIVIDADES AUXILIARES DOS SERVICOS FINANCEIROS, SEGUROS, PREVIDENCIA COMPLEMENTAR E PLANOS DE SAUDE"
  }
}

4.6 CNAE Principal - Descrição Grupo

{
  "$filter": {
    "cnae_principal_desc_grupo": "661 - ATIVIDADES AUXILIARES DOS SERVICOS FINANCEIROS"
  }
}

4.7 CNAE Principal - Descrição Seção

{
  "$filter": {
    "cnae_principal_desc_secao": "K - ATIVIDADES FINANCEIRAS, DE SEGUROS E SERVICOS RELACIONADOS"
  }
}

4.8 Atividades Secundárias (array)

{
  "$filter": {
    "atividades_secundarias.classe": 4711301
    }
  }
}

{
  "$filter": {
    "atividades_secundarias.ramo_de_atividade": "COMERCIO VAREJISTA"
    }
  }
}

Filtra empresas que têm determinada atividade secundária

Campos disponíveis em atividades_secundarias:

classe, desc_classe

divisao, grupo, secao, segmento

subclasse, ramo_de_atividade

5. Localização (8 campos)

5.1 Endereço

{
  "$filter": {
    "endereco": { "$fuzzy": "AVENIDA PAULISTA" }
  }
}

Exemplos de endereços:

"AVENIDA PAULISTA 1000"

"RUA DA CONSOLACAO 2000 - CONSOLACAO - 01302000"

"AVENIDA ALCANTARA MACHADO 1748 - BRAS - A - 03102002"

"RUA AUGUSTA 1500 - CERQUEIRA CESAR"

5.2 Bairro

{
  "$filter": {
    "bairro": "PINHEIROS"
  }
}

Exemplos de bairros:

"PINHEIROS"

"JARDINS"

"CENTRO"

"BRAS"

"MOEMA"

"VILA MARIANA"

"IPANEMA"

"COPACABANA"

5.3 CEP

{
  "$filter": {
    "cep": 1310100
  }
}

5.4 Município

{
  "$filter": {
    "municipio": "SAO PAULO"
  }
}

Exemplos de municípios:

"SAO PAULO"

"RIO DE JANEIRO"

"BELO HORIZONTE"

"CURITIBA"

"PORTO ALEGRE"

"BRASILIA"

"SALVADOR"

"FORTALEZA"

"CAMPINAS"

"FLORIANOPOLIS"

5.5 UF (sigla do estado)

{
  "$filter": {
    "sigla_uf": "SP"
  }
}

5.6 Macrorregião

{
  "$filter": {
    "macrorregiao": "SUDESTE"
  }
}

Valores: SUL, SUDESTE, NORDESTE, NORTE, CENTRO-OESTE

6. Financeiro (8 campos)

{
  "$filter": {
    "capital_social": { "$gte": 1000000 }
  }
}

Empresas com capital social >= R$ 1 milhão

6.2 Faturamento

{
  "$filter": {
    "$and": [
      { "faturamento": { "$gte": 5000000 } },
      { "faturamento": { "$lte": 50000000 } }
    ]
  }
}

Faturamento entre R $5 M e R$ 50M

6.3 Faturamento do Grupo

{
  "$filter": {
    "faturamento_grupo": { "$gte": 100000000 }
  }
}

6.4 Faixa de Faturamento do Grupo

{
  "$filter": {
    "faixa_faturamento_grupo": "10M A 20M"
  }
}

Valores possíveis:

0

0 A 81K

81K A 360K

360K A 1M

1M A 2M

2M A 4,8M

4,8M A 7M

7M A 10M

10M A 20M

20M A 30M

30M A 40M

40M A 50M

50M A 100M

100M A 300M

300M A 500M

500M A 700M

700M A 1B

1B OU SUPERIOR

6.5 Faixa de Funcionários do Grupo

{
  "$filter": {
    "faixa_funcionarios_grupo": "100 A 249"
  }
}

Valores possíveis:

0

1

02 A 05

06 A 09

10 A 19

20 A 49

50 A 99

100 A 249

250 A 499

500 A 999

1000 A 1999

2000 A 4999

5000 A 9999

10000 A 29999

30000 OU MAIS

6.6 Forma de Tributação

{
  "$filter": {
    "forma_de_tributacao": "LUCRO REAL"
  }
}

Valores possíveis:

LUCRO REAL

LUCRO PRESUMIDO

LUCRO ARBITRADO

LUCRO PRESUMIDO/REAL

LUCRO PRESUMIDO/ARBITRADO

LUCRO REAL/ARBITRADO

IMUNE DO IRPJ

ISENTA DO IRPJ

6.7 Forma de Tributação Ajustada

{
  "$filter": {
    "forma_de_tributacao_ajustada": "LUCRO PRESUMIDO"
  }
}

6.8 Opção pelo Simples Nacional

{
  "$filter": {
    "opcao_pelo_simples": "TRUE"
  }
}

6.9 Opção pelo MEI

{
  "$filter": {
    "opcao_pelo_mei": "FALSE"
  }
}

7. Presença Online (4 campos)

7.1 Sites (array)

{
  "$filter": {
    "sites.ecommerce": true
    }
  }
}

Campos em sites:

site (URL do site)

confiabilidade (entre 0 e 1)

ecommerce (boolean)

tecnologias (array de tecnologias detectadas)

7.2 Facebook (array)

{
  "$filter": {
    "facebook": { "$exists": true }
  }
}

Empresas com perfil no Facebook

7.3 Instagram (array)

{
  "$filter": {
    "instagram": { "$exists": true }
  }
}

7.4 LinkedIn URL

{
  "$filter": {
    "linkedin_url": { "$exists": true }
  }
}

8. Sócios (1 campo array)

8.1 Filtrar por Sócios

{
  "$filter": {
    "socios.qualificacao_socio": "SOCIO-ADMINISTRADOR"
  }
}

Campos disponíveis em sócios:

cpf (CPF do sócio)

nome_socio (nome completo)

qualificacao_socio (SOCIO, SOCIO-ADMINISTRADOR, ADMINISTRADOR, etc.)

data_nascimento (formato: YYYY-MM-DD)

faixa_etaria_socio (20 A 29 ANOS, 30 A 39 ANOS, etc.)

sexo (M, F)

data_entrada_sociedade (formato: YYYY-MM-DD)

identificador_socio (código único)

Exemplos Práticos Combinados

Exemplo 1: Restaurantes em SP, ativos, matriz

{
  "$filter": {
    "$and": [
      { "cnae_principal_desc_subclasse": { "$fuzzy": "RESTAURANTE" } },
      { "sigla_uf": "SP" },
      { "municipio": "SAO PAULO" },
      { "situacao_cadastral": "ATIVA" },
      { "matriz": "TRUE" }
    ]
  }
}

Exemplo 2: E-commerces com faturamento alto

{
  "$filter": {
    "$and": [
      { "sites.ecommerce": true },
      { "faturamento": { "$gte": 10000000 } },
      { "opcao_pelo_simples": "FALSE" }
    ]
  }
}

Exemplo 3: Empresas de tecnologia na região Sul

{
  "$filter": {
    "$and": [
      { "cnae_principal_desc_secao": { "$fuzzy": "INFORMACAO E COMUNICACAO" } },
      { "macrorregiao": "SUL" },
      { "situacao_cadastral": "ATIVA" },
      { "faixa_funcionarios_grupo": "50 A 99" }
    ]
  }
}

Exemplo 4: Indústrias com presença online

{
  "$filter": {
    "$and": [
      { "segmento": "INDUSTRIA" },
      { "situacao_cadastral": "ATIVA" },
      { "sites": { "$exists": true, "$ne": [] } },
      {
        "$or": [
          { "instagram": { "$exists": true, "$ne": [] } },
          { "facebook": { "$exists": true, "$ne": [] } }
        ]
      }
    ]
  }
}

Exemplo 5: Empresas abertas recentemente com capital alto

{
  "$filter": {
    "$and": [
      { "data_inicio_atividade": { "$gte": "2023-01-01" } },
      { "capital_social": { "$gte": 500000 } },
      { "matriz": "TRUE" },
      { "situacao_cadastral": "ATIVA" }
    ]
  }
}

Operadores de Comparação

Operadores Gerais

$in: está contido em array de valores

$nin: não está contido em array de valores

$not: negação (inverte a condição)

$exists: campo existe (true/false)

Operadores Numéricos

Use para campos como faturamento, capital_social, qtde_filiais, qtde_funcionarios_grupo, etc.

$gte: maior ou igual

$lte: menor ou igual

Exemplo com $g t ee$ lte:

{
  "$filter": {
    "qtde_funcionarios_grupo": { "$gte": 10, "$lte": 50 }
  }
}

Operadores de Texto

$fuzzy - Busca Aproximada (Fuzzy Search)

Ideal para nomes com variações ortográficas ou erros de digitação. Funciona em campos de texto como razao_social, nome_fantasia, etc.

{
  "$filter": {
    "$or": [{ "razao_social": { "$fuzzy": "DRIVA" } }]
  }
}

Este operador encontrará variações como:

"DRIVA TECNOLOGIA"

"DRIVAN SISTEMAS"

"DRIVAS COMERCIO"

Exemplo com $in

{
  "$filter": {
    "uf": { "$in": ["SP", "RJ", "MG"] }
  }
}

Exemplo com $nin (not in)

{
  "$filter": {
    "situacao_cadastral": { "$nin": ["BAIXADA", "SUSPENSA"] }
  }
}

Exemplo com $not

{
  "$filter": {
    "porte": { "$not": "MEI" }
  }
}

Empresas que NÃO são MEI

Paginação e Ordenação

Além de filtros, você pode usar:

{
  "$filter": { /* seus filtros */ },
  "$page": 0,
  "$size": 3,
}



5. **Campos Nulos**: Alguns campos podem ser null. Use `$exists` para verificar existência

Guia de Filtros da API - Consulta de Empresas

Estrutura Básica#

1. Identificação (5 campos)#

1.1 CNPJ Completo#

1.2 Raiz do CNPJ (primeiros 8 dígitos)#

1.3 Dígito Verificador do CNPJ#

1.4 Razão Social#

1.5 Nome Fantasia#

2. Situação (2 campos)#

2.1 Situação Cadastral#

2.2 Data de Início de Atividade#

3. Classificação (6 campos)#

3.1 Natureza Jurídica#

3.2 Porte#

3.3 Empresa Público/Privada#

3.4 Matriz#

3.5 Quantidade de Filiais#

3.6 Segmento#

4. CNAE (8 campos)#

4.1 CNAE Principal - Classe (código)#

4.2 CNAE Principal - Subclasse (código)#

4.3 CNAE Principal - Descrição Classe#

4.4 CNAE Principal - Descrição Subclasse#

4.5 CNAE Principal - Descrição Divisão#

4.6 CNAE Principal - Descrição Grupo#

4.7 CNAE Principal - Descrição Seção#

4.8 Atividades Secundárias (array)#

5. Localização (8 campos)#

5.1 Endereço#

5.2 Bairro#

5.3 CEP#

5.4 Município#

5.5 UF (sigla do estado)#

5.6 Macrorregião#

6. Financeiro (8 campos)#

6.1 Capital Social#

6.2 Faturamento#

6.3 Faturamento do Grupo#

6.4 Faixa de Faturamento do Grupo#

6.5 Faixa de Funcionários do Grupo#

6.6 Forma de Tributação#

6.7 Forma de Tributação Ajustada#

6.8 Opção pelo Simples Nacional#

6.9 Opção pelo MEI#

7. Presença Online (4 campos)#

7.1 Sites (array)#

7.2 Facebook (array)#

7.3 Instagram (array)#

7.4 LinkedIn URL#

8. Sócios (1 campo array)#

8.1 Filtrar por Sócios#

Exemplos Práticos Combinados#

Exemplo 1: Restaurantes em SP, ativos, matriz#

Exemplo 2: E-commerces com faturamento alto#

Exemplo 3: Empresas de tecnologia na região Sul#

Exemplo 4: Indústrias com presença online#

Exemplo 5: Empresas abertas recentemente com capital alto#

Operadores de Comparação#

Operadores Gerais#

Operadores Numéricos#

Operadores de Texto#

$fuzzy - Busca Aproximada (Fuzzy Search)#

Exemplo com $in#

Exemplo com $nin (not in)#

Exemplo com $not#

Paginação e Ordenação#

Estrutura Básica

1. Identificação (5 campos)

1.1 CNPJ Completo

1.2 Raiz do CNPJ (primeiros 8 dígitos)

1.3 Dígito Verificador do CNPJ

1.4 Razão Social

1.5 Nome Fantasia

2. Situação (2 campos)

2.1 Situação Cadastral

2.2 Data de Início de Atividade

3. Classificação (6 campos)

3.1 Natureza Jurídica

3.2 Porte

3.3 Empresa Público/Privada

3.4 Matriz

3.5 Quantidade de Filiais

3.6 Segmento

4. CNAE (8 campos)

4.1 CNAE Principal - Classe (código)

4.2 CNAE Principal - Subclasse (código)

4.3 CNAE Principal - Descrição Classe

4.4 CNAE Principal - Descrição Subclasse

4.5 CNAE Principal - Descrição Divisão

4.6 CNAE Principal - Descrição Grupo

4.7 CNAE Principal - Descrição Seção

4.8 Atividades Secundárias (array)

5. Localização (8 campos)

5.1 Endereço

5.2 Bairro

5.3 CEP

5.4 Município

5.5 UF (sigla do estado)

5.6 Macrorregião

6. Financeiro (8 campos)

6.1 Capital Social

6.2 Faturamento

6.3 Faturamento do Grupo

6.4 Faixa de Faturamento do Grupo

6.5 Faixa de Funcionários do Grupo

6.6 Forma de Tributação

6.7 Forma de Tributação Ajustada

6.8 Opção pelo Simples Nacional

6.9 Opção pelo MEI

7. Presença Online (4 campos)

7.1 Sites (array)

7.2 Facebook (array)

7.3 Instagram (array)

7.4 LinkedIn URL

8. Sócios (1 campo array)

8.1 Filtrar por Sócios

Exemplos Práticos Combinados

Exemplo 1: Restaurantes em SP, ativos, matriz

Exemplo 2: E-commerces com faturamento alto

Exemplo 3: Empresas de tecnologia na região Sul

Exemplo 4: Indústrias com presença online

Exemplo 5: Empresas abertas recentemente com capital alto

Operadores de Comparação

Operadores Gerais

Operadores Numéricos

Operadores de Texto

$fuzzy - Busca Aproximada (Fuzzy Search)

Exemplo com $in

Exemplo com $nin (not in)

Exemplo com $not

Paginação e Ordenação