# Prospecção de empresas (contagem e job)

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)
- Retorna quantidade total de registros (empresas e sócios) que correspondem aos filtros
- Não consome créditos

2. Modo Prospecção (export: true)
- Inicia processo de coleta de informações detalhadas das empresas
- Inclui dados de contato dos sócios
- Retorna job ID

Endpoint: POST /company/prospect
Version: 1.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `export` (boolean, required)
    false = contagem apenas, true = iniciar prospecção

  - `name` (string)
    Razão social ou nome fantasia (busca parcial)
    Example: "TECNOLOGIA"

  - `cities` (array)
    Cidades (formato "Cidade - UF")
    Example: ["Rio de Janeiro - RJ"]

  - `states` (array)
    Estados (sigla UF)
    Example: ["RJ"]

  - `cnae_codes` (array)
    Códigos CNAE
    Example: ["5231101","6201500"]

  - `headquarter_type` (string)
    Tipo de sede: H=Matriz, B=Filial
    Enum: "H", "B"

  - `estimated_employees` (array)
    Array de faixas de número estimado de funcionários
    Example: [{"upper":9},{"lower":10,"upper":49},{"lower":100},{"lower":"1","upper":"800"}]

  - `estimated_employees.lower` (string)
    Limite inferior (opcional)

  - `estimated_employees.upper` (string)
    Limite superior (opcional)

  - `estimated_created` (array)
    Array de períodos de data de fundação
    Example: [{"lower":"2023-11-18","upper":"2024-11-18"},{"upper":"2020-11-18"}]

  - `estimated_created.lower` (string)
    Data inferior (opcional)

  - `estimated_created.upper` (string)
    Data superior (opcional)

  - `revenues` (array)
    Array de faixas de receita anual
    Example: [{"lower":"10000.00","upper":"500000.00"}]

  - `revenues.lower` (string)
    Receita mínima (opcional)

  - `revenues.upper` (string)
    Receita máxima (opcional)

  - `company_type` (array)
    Porte da empresa
    Enum: "ME", "EPP", "DEMAIS"

  - `nature_codes` (array)
    Códigos de natureza jurídica
    Example: ["3999","1112","1104","1120"]

  - `mei_type` (string)
    Filtrar MEI
    Enum: "SIM", "NAO"

  - `sector_codes` (array)
    Setores de atividade econômica
    Example: ["ATIVIDADE FINANCEIRA SEGUROS","COMÉRCIO","INDUSTRIA"]

  - `simple_type` (string)
    Empresa optante pelo Simples Nacional
    Enum: "SIM", "NAO"

  - `capitals` (array)
    Array de faixas de capital social
    Example: [{"lower":"5000.00","upper":"5000000.00"}]

  - `capitals.lower` (string)
    Capital mínimo (opcional)

  - `capitals.upper` (string)
    Capital máximo (opcional)

  - `import_export` (string)
    Tipo de operação de comércio exterior
    Enum: "IMPORTA", "EXPORTA"

  - `vehicles` (array)
    Array de faixas de número de veículos
    Example: [{"lower":"1","upper":"50"}]

  - `vehicles.lower` (string)
    Quantidade mínima (opcional)

  - `vehicles.upper` (string)
    Quantidade máxima (opcional)

  - `quantity` (integer)
    Quantidade de registros a exportar (apenas quando export=true)
    Example: 500

  - `callback_email` (string)
    Email para notificação quando job concluir (apenas quando export=true)
    Example: "usuario@empresa.com"

  - `plan` (string)
    Plano de extração (sempre "3" para export=true)
    Enum: "3"

  - `file_formatting` (string)
    Formato do arquivo de exportação (apenas quando export=true)
    Enum: "excel", "csv"

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Example: "no credits"

  - `error.description` (string)
    Example: "Você não possui saldo suficiente, disponível 0"

## Response 403 fields (application/json):

  - `error` (string)
    Example: "Invalid token"