Skip to content

Prospecção de empresas (contagem e job)

Request

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)

  • Retorna a contagem que corresponde aos filtros
  • Não consome créditos
  • Resposta: {"count": [850, 120]} - uma lista de dois inteiros, na ordem [total_de_empresas, empresas_com_ao_menos_um_socio_com_celular_whatsapp]
  • O índice 1 NÃO é uma contagem de sócios. Ele conta empresas que possuem pelo menos um sócio com celular WhatsApp. Apenas o índice 0 é o total cobrável e é contra ele que o quantity é validado.

2. Modo Prospecção (export: true)

  • Inicia processo de coleta de informações detalhadas das empresas
  • Inclui dados de contato dos sócios
  • name e quantity passam a ser obrigatórios (name é o nome dado ao job; quantity é o volume a exportar). Faltando qualquer um dos dois a API responde the quantity, name and some location are required fields when export is True.
  • Resposta: {"id": 54321} - use esse id em /prospection/{job_id}/result/

Filtro de localização obrigatório em TODA chamada: vale também para a contagem (export=false), não só para o export. É preciso enviar pelo menos um entre cities, states, ddds, neighborhoodies ou geo_points. Sem nenhum deles a API responde You must select at least one locale filter.

Atenção ao geo_points: ele satisfaz essa exigência, mas não é aplicado ao resultado neste endpoint (ver a descrição do campo). Usá-lo sozinho retorna/exporta a base sem recorte geográfico — prefira cities, states, ddds ou neighborhoodies.

Arquivos entregues: o ZIP do resultado traz o arquivo principal, com as empresas, e - somente se a prospecção encontrar sócios - um arquivo socios_* com os sócios de cada empresa (CPF, cargo, % de participação, telefones e e-mails), sem custo adicional. Se nenhum sócio for retornado, o ZIP vem só com o arquivo principal.

  • A extensão dos arquivos segue file_formatting: excel (padrão deste endpoint) gera .xlsx; csv gera .csv.
  • Nomes: prospeccao_{AAAAMMDD_HHMM}_{batch_id} e socios_{AAAAMMDD_HHMM}_{batch_id}.
  • Se cbo_codes for usado, o ZIP ganha um terceiro arquivo, empregados_{AAAAMMDD_HHMM}_{batch_id}.
Security
ApiKeyAuth
Bodyapplication/jsonrequired
exportbooleanrequired

false = contagem apenas, true = iniciar prospecção

Example:false
namestring

Razão social ou nome fantasia (busca parcial). Obrigatório quando export=true (junto com quantity), pois é usado como nome do job de prospecção; opcional em export=false.

Example:"TECNOLOGIA"
citiesArray of strings

Cidades (formato "Cidade - UF")

Example:
[
  "Rio de Janeiro - RJ"
]
statesArray of strings

Estados (sigla UF)

Example:
[
  "RJ"
]
dddsArray of strings

DDDs de telefone (2 dígitos)

Example:
[
  "11",
  "21"
]
neighborhoodiesArray of strings

Bairros, no formato "BAIRRO - CIDADE - UF" (três partes separadas por -). Fora desse formato a API responde The format sent is not valid.. Ex.: CENTRO - SÃO PAULO - SP.

O nome do parâmetro tem mesmo esse typo (neighborhoodies) - é o que a API aceita e o que ela enumera na mensagem de erro dos filtros de localização. neighborhoods não é reconhecido.

Inconsistência conhecida: a exclusão de bairros usa a grafia correta (exclude_neighborhoods), enquanto a inclusão usa neighborhoodies.

Example:
[
  "CENTRO - SÃO PAULO - SP",
  "JARDINS - SÃO PAULO - SP"
]
geo_pointsobject

Recorte geográfico. É um objeto único (não um array), com type e data. Três formas são aceitas:

  • circle — {"type": "circle", "data": {"radius": 5000, "center": {"lat": -23.5, "lng": -46.6}}} (radius em metros)
  • rectangle — {"type": "rectangle", "data": {"north": -23.4, "south": -23.7, "east": -46.5, "west": -46.8}}
  • polygon — {"type": "polygon", "data": [{"lat": -23.5, "lng": -46.6}, {"lat": -23.6, "lng": -46.7}]}

A longitude é lng (não lon).

AVISO: atualmente geo_points satisfaz a exigência de filtro de localização mas NÃO é aplicado ao resultado nos endpoints de prospecção. Enviá-lo sozinho faz a contagem/exportação rodar sem nenhum recorte geográfico (ou seja, sobre a base inteira). Até que isso seja corrigido, use cities, states, ddds ou neighborhoodies.

Example:
{
  "type": "circle",
  "data": {
    "radius": 5000,
    "center": { … }
  }
}
cnae_codesArray of strings

Códigos CNAE

Example:
[
  "5231101",
  "6201500"
]
headquarter_typestring

Tipo de sede: H=Matriz, B=Filial

Enum:"H""B"
Example:"H"
estimated_employeesArray of objects

Array de faixas de número estimado de funcionários

Example:
[
  {
    "upper": 9
  },
  {
    "lower": 10,
    "upper": 49
  },
  {
    "lower": 100
  },
  {
    "lower": "1",
    "upper": "800"
  }
]
estimated_createdArray of objects

Array de períodos de data de fundação

Example:
[
  {
    "lower": "2023-11-18",
    "upper": "2024-11-18"
  },
  {
    "upper": "2020-11-18"
  }
]
revenuesArray of objects

Array de faixas de receita anual

Example:
[
  {
    "lower": "10000.00",
    "upper": "500000.00"
  }
]
company_typeArray of strings

Porte da empresa

Items Enum:"ME""EPP""DEMAIS"
Example:
[
  "ME",
  "EPP"
]
nature_codesArray of strings

Códigos de natureza jurídica

Example:
[
  "3999",
  "1112",
  "1104",
  "1120"
]
mei_typestring

Filtrar MEI

Enum:"SIM""NAO"
Example:"NAO"
sector_codesArray of strings

Setores de atividade econômica

Example:
[
  "ATIVIDADE FINANCEIRA SEGUROS",
  "COMÉRCIO",
  "INDUSTRIA"
]
simple_typestring

Empresa optante pelo Simples Nacional

Enum:"SIM""NAO"
Example:"SIM"
capitalsArray of objects

Array de faixas de capital social

Example:
[
  {
    "lower": "5000.00",
    "upper": "5000000.00"
  }
]
import_exportstring

Tipo de operação de comércio exterior

Enum:"IMPORTA""EXPORTA"
Example:"IMPORTA"
vehiclesArray of objects

Array de faixas de número de veículos

Example:
[
  {
    "lower": "1",
    "upper": "50"
  }
]
quantityinteger, >= 1

Quantidade de registros a exportar. Obrigatório quando export=true (junto com name); ignorado em export=false. É validado contra o índice 0 do count (total de empresas).

Example:500
callback_emailstring, (email)

Email para notificação quando job concluir (apenas quando export=true)

Example:"usuario@empresa.com"
planstring

Plano de extração (sempre "3" para export=true)

Value:"3"
Example:"3"
file_formattingstring

Formato do arquivo de exportação (apenas quando export=true)

Enum:"excel""csv"
Example:"excel"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/company/prospect/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "export": false,
    "name": "TECNOLOGIA",
    "cities": [
      "Rio de Janeiro - RJ"
    ],
    "states": [
      "RJ"
    ],
    "ddds": [
      "11",
      "21"
    ],
    "neighborhoodies": [
      "CENTRO - SÃO PAULO - SP",
      "JARDINS - SÃO PAULO - SP"
    ],
    "geo_points": {
      "type": "circle",
      "data": {
        "radius": 5000,
        "center": {
          "lat": -23.5,
          "lng": -46.6
        }
      }
    },
    "cnae_codes": [
      "5231101",
      "6201500"
    ],
    "headquarter_type": "H",
    "estimated_employees": [
      {
        "upper": 9
      },
      {
        "lower": 10,
        "upper": 49
      },
      {
        "lower": 100
      },
      {
        "lower": "1",
        "upper": "800"
      }
    ],
    "estimated_created": [
      {
        "lower": "2023-11-18",
        "upper": "2024-11-18"
      },
      {
        "upper": "2020-11-18"
      }
    ],
    "revenues": [
      {
        "lower": "10000.00",
        "upper": "500000.00"
      }
    ],
    "company_type": [
      "ME",
      "EPP"
    ],
    "nature_codes": [
      "3999",
      "1112",
      "1104",
      "1120"
    ],
    "mei_type": "NAO",
    "sector_codes": [
      "ATIVIDADE FINANCEIRA SEGUROS",
      "COMÉRCIO",
      "INDUSTRIA"
    ],
    "simple_type": "SIM",
    "capitals": [
      {
        "lower": "5000.00",
        "upper": "5000000.00"
      }
    ],
    "import_export": "IMPORTA",
    "vehicles": [
      {
        "lower": "1",
        "upper": "50"
      }
    ],
    "quantity": 500,
    "callback_email": "usuario@empresa.com",
    "plan": "3",
    "file_formatting": "excel"
  }'

Responses

Resposta de contagem ou job criado

Bodyapplication/json
One of:

Resposta de contagem (export=false)

countArray of integers, = 2 items

Lista de dois inteiros na ordem [total_de_empresas, empresas_com_ao_menos_um_socio_com_celular_whatsapp].

O índice 0 é o total de empresas que batem com os filtros - é o único número cobrável e é contra ele que o quantity do export é validado.

O índice 1 NÃO é uma contagem de sócios: é o número de empresas que possuem pelo menos um sócio com celular WhatsApp.

A chave é count - não existem total_companies nem total_partners na resposta.

Example:
[
  850,
  120
]
Response
{
  "count": [
    850,
    120
  ]
}