openapi: 3.0.0
info:
  title: Data Stone API
  version: '1.0'
  description: >
    A API da Data Stone fornece acesso a dados enriquecidos de pessoas físicas e
    jurídicas do Brasil.


    **Funcionalidades principais:**

    - Consulta de informações de pessoas e empresas

    - Prospecção e busca avançada com filtros personalizados

    - Enriquecimento de dados B2B em lote

    - Dados auxiliares (CNAE, CBO, geolocalização)

    - Validação de contatos WhatsApp


    **Autenticação:** Todas as requisições requerem uma API Key no header
    `Authorization`.


    **Base URL:** `https://api.datastone.com.br/v1`


    ## Webhooks


    Sistema de notificação automática via POST ao final de processos de
    enriquecimento ou prospecção.


    - **Cadastro:** Via perfil do administrador com teste automático de
    disponibilidade da URL

    - **Método:** POST (enviado pela API para o cliente)

    - **Retry Policy:** 3 tentativas com intervalo de 1 minuto entre cada

    - **Timeout:** 30 segundos por requisição

    - **Resposta requerida:** HTTP 200 imediato


    **Payload do Webhook:**

    ```json

    {
      "job_id": 123,
      "job_type": "enrichment",
      "status": "done"
    }

    ```


    Valores possíveis para `job_type`: `enrichment`, `prospecting`


    Valores possíveis para `status`: `requested`, `done`, `error`


    ## Rate Limiting


    **Limite Padrão:** 100 requisições por dia (compartilhado entre API e
    painel)


    - **Personalização:** Limites podem ser customizados por conta/empresa

    - **Whitelist de IPs:** Administradores podem adicionar IPs que ficam
    isentos do rate limit

    - **Resposta quando excedido:** Status Code `429 Too Many Requests` com
    bloqueio de 24 horas


    ## Limite de Produto


    Controle de uso por tipo de produto (gerenciado por administradores):


    - **B2C** (Consulta, Enriquecimento, Prospecção): 100.000 requisições/mês

    - **B2B** (Prospecção B2B, Consulta B2B): 50.000 requisições/mês


    **Resposta quando excedido:** Status Code `429 Too Many Requests` até início
    do próximo período
  x-logo:
    url: https://datastone.com.br/wp-content/uploads/2018/03/data-stone.png
    altText: Data Stone Logo
servers:
  - url: https://api.datastone.com.br/v1
    description: Servidor de Produção
tags:
  - name: Consulta
    description: >
      Operações de consulta direta para pessoas físicas (CPF), empresas (CNPJ),
      validação de WhatsApp e verificação de saldo.
  - name: Prospecção B2B
    description: >
      Operações de prospecção e enriquecimento B2B para pessoas e empresas,
      incluindo filtros avançados, busca com autocomplete e enriquecimento em
      lote.
  - name: Enriquecimento
    description: >
      Operações de enriquecimento de dados em lote com layouts personalizáveis e
      processamento assíncrono.
  - name: Prospecção
    description: >
      Operações de prospecção com filtros geográficos e profissionais, incluindo
      contagem e geração de jobs de prospecção.
  - name: Auxiliares
    description: >
      Dados auxiliares como CNAE, CBO, geolocalização (estados, cidades,
      bairros) e setores empresariais.
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API Key de autenticação. Formato: `Authorization: <sua-api-key>`'
  schemas:
    WebhookPayload:
      type: object
      properties:
        job_id:
          type: integer
          description: Identificador do job de processamento
          example: 12345
        job_type:
          type: string
          enum:
            - enrichment
            - prospecting
          description: Tipo de job executado
          example: enrichment
        status:
          type: string
          enum:
            - requested
            - done
            - error
          description: Status atual do job
          example: done
    PaginacaoB2B:
      type: object
      required:
        - pagina
        - por_pagina
      properties:
        pagina:
          type: integer
          minimum: 1
          description: Número da página a ser retornada
          example: 1
        por_pagina:
          type: integer
          minimum: 1
          maximum: 50
          description: Quantidade de itens por página (máximo 50)
          example: 20
        chave_cache:
          type: string
          description: >
            Chave de cache retornada na primeira requisição.

            Usar em requisições subsequentes economiza créditos (0 créditos vs 1
            crédito).

            Cache expira em 7 dias.
          example: abc123xyz789
    FiltrosEmpresa:
      type: object
      properties:
        nome_empresa:
          type: array
          items:
            type: string
          description: Nomes específicos de empresas
          example:
            - Google Brasil Internet Ltda
        localizacoes:
          type: array
          items:
            type: string
          description: Cidades (formato "Cidade, UF")
          example:
            - São Paulo, SP
            - Rio de Janeiro, RJ
        estados:
          type: array
          items:
            type: string
          description: Estados (sigla UF)
          example:
            - SP
            - RJ
        setores:
          type: array
          items:
            type: string
          description: Setores empresariais
          example:
            - Tecnologia
            - Educação
        atividades_cnae:
          type: array
          items:
            type: string
          description: Códigos CNAE
          example:
            - '6201500'
        especialidades:
          type: array
          items:
            type: string
          description: Especialidades ou nichos de mercado
          example:
            - Software
        tamanhos_empresa:
          type: array
          items:
            type: string
          description: Faixas de número de funcionários
          example:
            - 11-50
            - 51-200
        naturezas_juridicas:
          type: array
          items:
            type: integer
          description: IDs de natureza jurídica
          example:
            - 1
            - 2
            - 3
        tipos_trabalho:
          type: array
          items:
            type: string
          description: Tipos de organização
          example:
            - Empresa Privada
        data_fundacao:
          type: object
          properties:
            data_inicio:
              type: string
              format: date
              example: '2010-01-01'
            data_fim:
              type: string
              format: date
              example: '2023-12-31'
          description: Período de fundação da empresa
        faixa_receita:
          type: object
          properties:
            receita_minima:
              type: number
              example: 100000
            receita_maxima:
              type: number
              example: 5000000
          description: Faixa de receita anual em reais
        incluir_mei:
          type: boolean
          description: Incluir microempreendedores individuais
          example: true
        tem_cnpj:
          type: boolean
          description: Apenas empresas com CNPJ
          example: true
        tem_email:
          type: boolean
          description: Apenas empresas com email disponível
          example: true
        tem_telefone:
          type: boolean
          description: Apenas empresas com telefone disponível
          example: true
        tem_linkedin:
          type: boolean
          description: Apenas empresas com perfil LinkedIn
          example: true
    FiltrosPessoa:
      type: object
      properties:
        departamentos:
          type: array
          items:
            type: string
          description: Departamentos profissionais
          example:
            - Tecnologia
            - Marketing
        niveis_senioridade:
          type: array
          items:
            type: string
          description: Níveis de senioridade
          example:
            - Sênior
            - Pleno
        cargos:
          type: array
          items:
            type: string
          description: Cargos profissionais
          example:
            - Desenvolvedor
            - Gerente
        habilidades:
          type: array
          items:
            type: string
          description: Habilidades técnicas ou profissionais
          example:
            - Python
            - JavaScript
        periodos_trabalho:
          type: array
          items:
            type: object
          description: Períodos de trabalho em empresas
        localizacoes:
          type: array
          items:
            type: string
          description: Cidades (formato "Cidade, UF")
          example:
            - São Paulo, SP
        estados:
          type: array
          items:
            type: string
          description: Estados (sigla UF)
          example:
            - SP
            - RJ
        has_email:
          type: boolean
          description: Possui email disponível
          example: true
        has_phone:
          type: boolean
          description: Possui telefone disponível
          example: true
        has_cnpj:
          type: boolean
          description: Possui vínculo com CNPJ
          example: true
        has_linkedin:
          type: boolean
          description: Possui perfil LinkedIn
          example: true
    ResponseSaldo:
      type: object
      properties:
        balance:
          type: object
          properties:
            wallet:
              type: object
              properties:
                value:
                  type: number
                  format: float
                  description: Valor total disponível na carteira principal
                  example: 0
            credits:
              type: array
              items:
                type: object
                properties:
                  product_id:
                    type: integer
                    description: Identificador interno do produto
                    example: 6
                  product_name:
                    type: string
                    description: Nome do produto
                    example: Plataforma B2B
                  value:
                    type: integer
                    description: Quantidade de crédito disponível
                    example: 3161
        is_pos:
          type: boolean
          description: Indica se a conta é pós-paga
          example: false
    Error400:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: no credits
            description:
              type: string
              example: Você não possui saldo suficiente, disponível 0
    Error403:
      type: object
      properties:
        error:
          type: string
          example: Invalid token
    Error429:
      type: object
      properties:
        error:
          type: string
          example: Too Many Requests
paths:
  /balance:
    get:
      summary: Consultar saldo da conta
      description: Retorna informações de saldo e créditos disponíveis na conta por produto
      operationId: get_balance
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Saldo retornado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseSaldo'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /persons:
    get:
      summary: Consultar informações de pessoas físicas
      description: Busca informações detalhadas de pessoa física por CPF
      operationId: get_persons
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cpf
          in: query
          required: true
          description: CPF da pessoa (apenas números)
          schema:
            type: string
            pattern: ^\d{11}$
          example: '12345678901'
        - name: fields
          in: query
          required: false
          description: Campos específicos a retornar (separados por vírgula)
          schema:
            type: string
          example: name,cpf,emails,addresses
      responses:
        '200':
          description: Informações da pessoa retornadas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cpf:
                      type: string
                      example: '11111111111'
                    name:
                      type: string
                      example: FULANO DE TAL EXEMPLO
                    mother_name:
                      type: string
                      example: MARIA EXEMPLO
                    birthday:
                      type: string
                      format: date
                      example: '1993-01-01'
                    age:
                      type: string
                      example: '30'
                    gender:
                      type: string
                      enum:
                        - M
                        - F
                      example: M
                    sign:
                      type: string
                      example: Capricórnio
                    registry_situation:
                      type: string
                      example: REGULAR
                    pep:
                      type: boolean
                      example: false
                    pep_type:
                      type: string
                      example: ''
                    possibly_dead:
                      type: boolean
                      example: false
                    retired:
                      type: boolean
                      example: false
                    bolsa_familia:
                      type: boolean
                      example: false
                    estimated_income:
                      type: string
                      example: ATÉ R$ 1.000,00
                    cbo_code:
                      type: string
                      example: '999999'
                    cbo_description:
                      type: string
                      example: EMPRESÁRIO
                    rg:
                      type: string
                      nullable: true
                    addresses:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            example: AVENIDA
                          street:
                            type: string
                            example: LOREM IPSUM
                          number:
                            type: string
                            example: '1234'
                          complement:
                            type: string
                            example: ''
                          neighborhood:
                            type: string
                            example: BAIRRO EXEMPLO
                          city:
                            type: string
                            example: CIDADE EXEMPLO
                          district:
                            type: string
                            example: XX
                          postal_code:
                            type: string
                            example: '12345000'
                          priority:
                            type: integer
                            example: 1
                    emails:
                      type: array
                      items:
                        type: object
                        properties:
                          email:
                            type: string
                            example: exemplo@gmail.com
                          priority:
                            type: integer
                            example: 1
                    mobile_phones:
                      type: array
                      items:
                        type: object
                    land_lines:
                      type: array
                      items:
                        type: object
                    family_persons:
                      type: array
                      items:
                        type: object
                        properties:
                          cpf:
                            type: string
                            example: '22222222222'
                          name:
                            type: string
                            example: JOAO EXEMPLO
                          description:
                            type: string
                            example: IRMAO
                    related_companies:
                      type: array
                      items:
                        type: object
                        properties:
                          cnpj:
                            type: string
                            example: '55555555000101'
                          trading_name:
                            type: string
                            example: EMPRESA EXEMPLO
                          company_name:
                            type: string
                            example: FULANO DE TAL EXEMPLO 11111111111
                          registry_situation:
                            type: string
                            example: ATIVA
                          description:
                            type: string
                            example: Empresário
                          ownership:
                            type: number
                            example: 100
                    employer:
                      type: array
                      items:
                        type: object
                    ip:
                      type: string
                      example: 127.0.0.1
                    plan:
                      type: string
                      example: Consulta Premium
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Error400'
                  - type: object
                    properties:
                      cpf:
                        type: array
                        items:
                          type: string
                        example:
                          - Este campo é obrigatório.
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /persons/search:
    get:
      summary: Busca avançada de pessoas
      description: |
        Buscar pessoas por nome, email, telefone, nome da mãe ou endereço.

        Permite buscas mais flexíveis sem necessidade de CPF.
      operationId: get_persons_search
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: name
          in: query
          required: false
          description: Nome da pessoa
          schema:
            type: string
          example: JOAO SILVA
        - name: email
          in: query
          required: false
          description: Email da pessoa
          schema:
            type: string
          example: joao@exemplo.com
        - name: phone
          in: query
          required: false
          description: Telefone da pessoa
          schema:
            type: string
          example: '11987654321'
        - name: mother
          in: query
          required: false
          description: Nome da mãe
          schema:
            type: string
          example: MARIA SILVA
        - name: zip_code
          in: query
          required: false
          description: CEP
          schema:
            type: string
          example: '01310100'
        - name: address
          in: query
          required: false
          description: Nome da rua/avenida
          schema:
            type: string
          example: AVENIDA PAULISTA
        - name: address_number
          in: query
          required: false
          description: Número do endereço
          schema:
            type: string
          example: '1000'
        - name: uf
          in: query
          required: false
          description: Estado (sigla UF)
          schema:
            type: string
            pattern: ^[A-Z]{2}$
          example: SP
      responses:
        '200':
          description: Pessoas encontradas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Dados da pessoa (mesmo schema do /persons)
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /persons/advanced-search:
    get:
      summary: Busca de pessoas com wildcard
      description: >
        Busca por nome com suporte a caractere curinga (*).


        Use o asterisco (*) para representar qualquer sequência de caracteres.


        **Exemplo:** `name=JOAO*SILVA` encontra "JOAO DA SILVA", "JOAO PEDRO
        SILVA", etc.
      operationId: get_persons_advanced_search
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: name
          in: query
          required: true
          description: Nome da pessoa (use * como wildcard)
          schema:
            type: string
          example: MARIA*
        - name: state
          in: query
          required: false
          description: Estado (sigla UF)
          schema:
            type: string
            pattern: ^[A-Z]{2}$
          example: SP
        - name: city
          in: query
          required: false
          description: Cidade
          schema:
            type: string
          example: SAO PAULO
      responses:
        '200':
          description: Pessoas encontradas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Dados da pessoa
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /companies:
    get:
      summary: Consultar informações de empresas
      description: Busca informações detalhadas de empresa por CNPJ
      operationId: get_companies
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cnpj
          in: query
          required: true
          description: CNPJ da empresa (apenas números)
          schema:
            type: string
            pattern: ^\d{14}$
          example: '12345678000199'
        - name: fields
          in: query
          required: false
          description: Campos específicos a retornar (separados por vírgula)
          schema:
            type: string
          example: company_name,cnpj,emails,partners
      responses:
        '200':
          description: Informações da empresa retornadas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cnpj:
                      type: string
                      example: '12345678000199'
                    company_name:
                      type: string
                      example: FULANO DE TAL EXEMPLO
                    trading_name:
                      type: string
                      example: EMPRESA EXEMPLO
                    creation_date:
                      type: string
                      format: date
                      example: '2022-01-01'
                    age:
                      type: string
                      example: 3 anos 3 meses
                    business_size:
                      type: string
                      example: ME
                    city_uf:
                      type: string
                      example: CIDADE EXEMPLO, EX
                    cnae_code:
                      type: integer
                      example: 9511800
                    cnae_description:
                      type: string
                      example: >-
                        Reparação e manutenção de computadores e de equipamentos
                        periféricos
                    registry_situation:
                      type: string
                      example: ATIVA
                    addresses:
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            example: Avenida
                          street:
                            type: string
                            example: Lorem Ipsum
                          number:
                            type: string
                            example: '9999'
                          complement:
                            type: string
                            nullable: true
                          neighborhood:
                            type: string
                            example: Bairro Exemplo
                          city:
                            type: string
                            example: Cidade Exemplo
                          district:
                            type: string
                            example: EX
                          postal_code:
                            type: string
                            example: '00000000'
                          priority:
                            type: integer
                            example: 1
                    branch_offices:
                      type: array
                      items:
                        type: object
                    partners:
                      type: array
                      items:
                        type: object
                    emails:
                      type: array
                      items:
                        type: object
                    land_lines:
                      type: array
                      items:
                        type: object
                    mobile_phones:
                      type: array
                      items:
                        type: object
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /company/list:
    get:
      summary: Buscar empresas
      description: |
        Buscar empresas por razão social, email, domínio, CEP ou telefone.

        Permite buscas sem necessidade de CNPJ.
      operationId: get_company_list
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: razao_social
          in: query
          required: false
          description: Razão social da empresa
          schema:
            type: string
          example: EMPRESA EXEMPLO LTDA
        - name: email
          in: query
          required: false
          description: Email da empresa
          schema:
            type: string
          example: contato@empresa.com
        - name: domain
          in: query
          required: false
          description: Domínio do site da empresa
          schema:
            type: string
          example: empresa.com.br
        - name: cep
          in: query
          required: false
          description: CEP da empresa
          schema:
            type: string
          example: '01310100'
        - name: phone
          in: query
          required: false
          description: Telefone da empresa
          schema:
            type: string
          example: '1133334444'
        - name: uf
          in: query
          required: false
          description: Estado (sigla UF)
          schema:
            type: string
            pattern: ^[A-Z]{2}$
          example: SP
      responses:
        '200':
          description: Empresas encontradas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Dados da empresa (mesmo schema do /companies)
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /company/search/filial:
    get:
      summary: Buscar matriz e filiais
      description: >
        Localizar matriz e todas as filiais de uma empresa a partir de qualquer
        CNPJ do grupo.


        Retorna informações de todas as unidades (matriz + filiais).
      operationId: get_company_filial
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: cnpj
          in: query
          required: true
          description: CNPJ da empresa (matriz ou filial)
          schema:
            type: string
            pattern: ^\d{14}$
          example: '12345678000199'
      responses:
        '200':
          description: Matriz e filiais encontradas com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  matriz:
                    type: object
                    description: Dados da matriz
                  filiais:
                    type: array
                    items:
                      type: object
                    description: Lista de filiais
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /whatsapp/search:
    get:
      summary: Validar status de contato WhatsApp
      description: >
        Verifica se um número de telefone está ativo no WhatsApp.


        **IMPORTANTE:** Os campos `ddd` e `phone` devem ser enviados
        separadamente, sem formatação (sem traços ou espaços).
      operationId: get_whatsapp_status
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      parameters:
        - name: ddd
          in: query
          required: true
          description: DDD do telefone (exatamente 2 dígitos)
          schema:
            type: string
            pattern: ^\d{2}$
          example: '11'
        - name: phone
          in: query
          required: true
          description: Número do telefone (até 9 dígitos, apenas números)
          schema:
            type: string
            pattern: ^\d{1,9}$
          example: '987654321'
      responses:
        '200':
          description: Status do WhatsApp retornado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - ATIVO
                      - INATIVO
                    example: ATIVO
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /whatsapp/batch:
    post:
      summary: Validar múltiplos números WhatsApp
      description: >
        Verifica o status de múltiplos números de telefone no WhatsApp em uma
        única requisição.


        Processamento assíncrono com callback.


        **Limite:** Até 1000 números por requisição
      operationId: post_whatsapp_batch
      tags:
        - Consulta
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phones
              properties:
                phones:
                  type: array
                  description: Array de números completos (até 11 dígitos cada)
                  items:
                    type: string
                    pattern: ^\d{10,11}$
                  example:
                    - '11987654321'
                    - '21987654321'
                  maxItems: 1000
                callback_url:
                  type: string
                  description: URL para receber callback com resultados
                  example: https://seusite.com/callback
      responses:
        '200':
          description: Job de validação criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    description: ID do job de processamento
                    example: 12345
                  status:
                    type: string
                    example: requested
                  total_numbers:
                    type: integer
                    description: Total de números a serem validados
                    example: 100
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/filter-structure:
    get:
      summary: Obter estrutura de filtros B2B
      description: >
        Retorna documentação completa sobre filtros disponíveis para buscas de
        Pessoas e Empresas.

        Inclui nomes de campos, tipos de dados, descrições e indicadores de
        obrigatoriedade.
      operationId: get_filter_structure
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Estrutura de filtros retornada com sucesso
          content:
            application/json:
              schema:
                type: object
                description: Documentação de filtros disponíveis
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/filter-options:
    get:
      summary: Obter opções de filtros B2B
      description: >
        Retorna todas as opções pré-definidas para filtros categóricos da API
        B2B.


        **REGRA IMPORTANTE:** Para filtros com texto e valor, SEMPRE enviar o
        valor.

        - ✅ Válido: `{"estado": "SP"}`

        - ❌ Inválido: `{"estado": "São Paulo"}`
      operationId: get_filter_options
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Opções de filtros retornadas com sucesso
          content:
            application/json:
              schema:
                type: object
                description: Opções disponíveis para cada filtro categórico
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/search:
    get:
      summary: Busca com autocomplete
      description: >
        Busca em tempo real por diferentes tipos de dados com autocomplete.


        **Parâmetros de busca disponíveis:**

        - `nome_empresa` - Nomes de empresas (LinkedIn, razão social, nome
        fantasia) - Limite: 50

        - `localizacao` - Cidades (passar UF do estado) - Sem limite

        - `setor` - Setor empresarial - Limite: 50

        - `cargo` - Cargos/funções - Limite: 50

        - `atividade_cnae` - Atividades CNAE - Limite: 50

        - `natureza_juridica` - Natureza jurídica - Limite: 50

        - `especialidade` - Especialidades - Limite: 50
      operationId: get_autocomplete_search
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      parameters:
        - name: term
          in: query
          required: true
          description: Termo de busca
          schema:
            type: string
          example: Google
        - name: field
          in: query
          required: true
          description: Campo utilizado na busca
          schema:
            type: string
            enum:
              - nome_empresa
              - localizacao
              - setor
              - cargo
              - atividade_cnae
              - natureza_juridica
              - especialidade
          example: nome_empresa
      responses:
        '200':
          description: Resultados da busca autocomplete
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/persons:
    post:
      summary: Buscar pessoas B2B
      description: >
        Prospecção B2B de pessoas físicas com filtros avançados de perfil
        profissional e empresa.


        **Modelo de cobrança:**

        - Primeira requisição (sem chave de cache): 1 crédito B2B

        - Paginação (com chave de cache): 0 créditos

        - Expiração do cache: 7 dias


        O campo `id_pessoa` retornado pode ser usado no endpoint de
        Enriquecimento de Pessoas.
      operationId: post_b2b_persons
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pagina:
                  type: integer
                  minimum: 1
                  description: Número da página
                  example: 1
                por_pagina:
                  type: integer
                  minimum: 1
                  maximum: 50
                  description: Itens por página (máximo 50)
                  example: 20
                chave_cache:
                  type: string
                  description: >-
                    Chave de cache (economiza créditos em requisições
                    subsequentes)
                  example: abc123xyz
                filtros_pessoa:
                  $ref: '#/components/schemas/FiltrosPessoa'
                filtros_empresa:
                  $ref: '#/components/schemas/FiltrosEmpresa'
                url_webhook:
                  type: string
                  description: URL para callback assíncrono
                  example: https://seusite.com/webhook
      responses:
        '200':
          description: Pessoas encontradas com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  chave_cache:
                    type: string
                    description: Chave para usar em paginação (evita custos adicionais)
                    example: abc123xyz
                  total:
                    type: integer
                    description: Total de resultados encontrados
                    example: 150
                  resultados:
                    type: array
                    items:
                      type: object
                      properties:
                        id_pessoa:
                          type: integer
                          example: 12345
                        nome:
                          type: string
                          example: João Silva
                        cargo:
                          type: string
                          example: Desenvolvedor Sênior
                        empresa:
                          type: string
                          example: Tech Company
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '429':
          description: Limite de requisições excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
  /b2b/persons/enrich:
    post:
      summary: Enriquecer pessoa (individual)
      description: >
        Enriquece perfil de pessoa física individualmente com processamento
        assíncrono.


        **Custo:** 1 crédito por registro enriquecido com sucesso


        **Dados retornados:**

        - **Básicos:** nome completo, CPF (quando disponível), idade, gênero,
        localização

        - **Contatos:** telefones, emails, perfis públicos

        - **Vínculos empresariais:** participações, cargos corporativos, CNPJs

        - **Histórico profissional:** cargos, empresas, períodos

        - **Educação:** cursos, instituições, níveis de escolaridade


        A notificação de conclusão é enviada via webhook (se configurado).
      operationId: post_b2b_person_enrich
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contato:
                  type: object
                  properties:
                    url_linkedin:
                      type: string
                      description: URL do perfil LinkedIn
                      example: https://www.linkedin.com/in/exemplo
                    email:
                      type: string
                      description: Email do contato
                      example: exemplo@empresa.com
                    id_pessoa:
                      type: integer
                      description: ID da pessoa (do endpoint de prospecção)
                      example: 12345
                url_webhook:
                  type: string
                  description: URL para notificação de conclusão
                  example: https://seusite.com/webhook
      responses:
        '200':
          description: Enriquecimento concluído com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id_processamento:
                    type: string
                    description: ID único do processamento
                    example: 4cb319e3bd9544019b45fd56911fa160
                  status:
                    type: string
                    enum:
                      - completed
                      - processing
                      - failed
                    example: completed
                  total:
                    type: integer
                    description: Total de contatos processados
                    example: 1
                  sucesso:
                    type: integer
                    description: Quantidade de enriquecimentos bem-sucedidos
                    example: 1
                  falhou:
                    type: integer
                    description: Quantidade de enriquecimentos que falharam
                    example: 0
                  contatos:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: completed
                        tipo_entrada:
                          type: string
                          example: linkedin_url
                        valor_entrada:
                          type: string
                          example: https://www.linkedin.com/in/barboza-victor/
                        detalhes_contato:
                          type: object
                          properties:
                            informacoes_basicas:
                              type: object
                            contatos:
                              type: object
                            experiencia_profissional:
                              type: object
                            educacao:
                              type: object
                  timestamp:
                    type: number
                    format: float
                    example: 1760542724.0121257
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/persons/enrich/bulk:
    post:
      summary: Enriquecer pessoas em lote
      description: >
        Enriquecimento em massa de pessoas físicas com processamento assíncrono
        e entrega via webhook.


        **Custo:** 1 crédito por registro enriquecido com sucesso


        **Dados retornados:** Mesmos do enriquecimento individual
      operationId: post_b2b_persons_enrich_bulk
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contatos
              properties:
                contatos:
                  type: array
                  description: Array de contatos para enriquecer
                  items:
                    type: object
                    properties:
                      url_linkedin:
                        type: string
                        example: https://www.linkedin.com/in/exemplo
                      email:
                        type: string
                        example: exemplo@empresa.com
                      id_pessoa:
                        type: integer
                        example: 12345
                url_webhook:
                  type: string
                  description: URL para notificação de conclusão
                  example: https://seusite.com/webhook
      responses:
        '200':
          description: Job de enriquecimento em lote criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    example: 12345
                  status:
                    type: string
                    example: requested
                  total_contacts:
                    type: integer
                    example: 100
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/companies:
    post:
      summary: Buscar empresas B2B
      description: >
        Prospecção B2B de empresas usando dados públicos, registros oficiais e
        LinkedIn.


        **Modelo de cobrança:**

        - Primeira requisição (sem chave de cache): 1 crédito B2B

        - Paginação (com chave de cache): 0 créditos

        - Expiração do cache: 7 dias


        **REGRA IMPORTANTE:** Ao preencher `localizacoes`, deixe `estados`
        vazio, e vice-versa.
      operationId: post_b2b_companies
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pagina:
                  type: integer
                  minimum: 1
                  example: 1
                por_pagina:
                  type: integer
                  minimum: 1
                  maximum: 50
                  example: 20
                chave_cache:
                  type: string
                  description: Chave de cache (economiza créditos)
                  example: abc123xyz
                filtros_empresa:
                  $ref: '#/components/schemas/FiltrosEmpresa'
      responses:
        '200':
          description: Empresas encontradas com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  chave_cache:
                    type: string
                    example: abc123xyz
                  total:
                    type: integer
                    example: 250
                  resultados:
                    type: array
                    items:
                      type: object
                      properties:
                        empresa_id:
                          type: integer
                          example: 98765
                        cnpj:
                          type: string
                          example: '12345678000199'
                        razao_social:
                          type: string
                          example: Tech Company LTDA
                        nome_fantasia:
                          type: string
                          example: Tech Company
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '429':
          description: Limite de requisições excedido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
  /b2b/companies/enrich:
    post:
      summary: Enriquecer empresa (individual)
      description: >
        Enriquece perfil de empresa individualmente com processamento
        assíncrono.


        **Custo:** 1 crédito por registro enriquecido


        **Dados retornados:**

        - **Cadastro:** razão social, nome fantasia, data de fundação, CNAEs

        - **Localização:** endereço completo, cidade, estado, CEP,
        geolocalização

        - **Contatos:** telefones, emails, website oficial

        - **Informações:** setor, descrição, número de funcionários, links
        públicos

        - **Estrutura corporativa:** sócios, administradores, percentuais de
        participação

        - **Histórico:** ex-sócios e ex-funcionários

        - **Filiais e equipe atual**
      operationId: post_b2b_company_enrich
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contato:
                  type: object
                  properties:
                    url_linkedin:
                      type: string
                      description: URL do perfil LinkedIn da empresa
                      example: https://www.linkedin.com/company/exemplo
                    cnpj:
                      type: string
                      description: CNPJ da empresa (apenas números)
                      example: '12345678000199'
                    empresa_id:
                      type: integer
                      description: ID da empresa (do endpoint de prospecção)
                      example: 98765
                url_webhook:
                  type: string
                  description: URL para notificação de conclusão
                  example: https://seusite.com/webhook
      responses:
        '200':
          description: Enriquecimento concluído com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id_processamento:
                    type: string
                    description: ID único do processamento
                    example: '00000000000000000000000000000000'
                  status:
                    type: string
                    enum:
                      - completed
                      - processing
                      - failed
                    example: completed
                  total:
                    type: integer
                    description: Total de contatos processados
                    example: 1
                  sucesso:
                    type: integer
                    description: Quantidade de enriquecimentos bem-sucedidos
                    example: 1
                  falhou:
                    type: integer
                    description: Quantidade de enriquecimentos que falharam
                    example: 0
                  contatos:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: completed
                        tipo_entrada:
                          type: string
                          example: linkedin_url
                        valor_entrada:
                          type: string
                          example: https://www.linkedin.com/company/exemplo-inc/
                        detalhes_contato:
                          type: object
                          properties:
                            sobre:
                              type: object
                            cadastro:
                              type: object
                            localizacao:
                              type: object
                            contatos:
                              type: object
                            socios:
                              type: object
                            diretores:
                              type: object
                            gerentes:
                              type: object
                            funcionarios:
                              type: object
                            ex_funcionarios:
                              type: object
                            socios_antigos:
                              type: object
                            filiais:
                              type: object
                            representantes_legais:
                              type: object
                            participacoes_empresariais:
                              type: object
                  timestamp:
                    type: number
                    format: float
                    example: 1760632949
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /b2b/companies/enrich/bulk:
    post:
      summary: Enriquecer empresas em lote
      description: |
        Enriquecimento em massa de empresas com processamento assíncrono.

        **Custo:** 1 crédito por registro enriquecido

        **Dados retornados:** Mesmos do enriquecimento individual
      operationId: post_b2b_companies_enrich_bulk
      tags:
        - Prospecção B2B
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contatos
              properties:
                contatos:
                  type: array
                  description: Array de empresas para enriquecer
                  items:
                    type: object
                    properties:
                      url_linkedin:
                        type: string
                        example: https://www.linkedin.com/company/exemplo
                      cnpj:
                        type: string
                        example: '12345678000199'
                      empresa_id:
                        type: integer
                        example: 98765
                url_webhook:
                  type: string
                  description: URL para notificação de conclusão
                  example: https://seusite.com/webhook
      responses:
        '200':
          description: Job de enriquecimento em lote criado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    example: 12345
                  status:
                    type: string
                    example: requested
                  total_companies:
                    type: integer
                    example: 50
        '400':
          description: Requisição inválida ou saldo insuficiente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /enrichment/layouts:
    get:
      summary: Listar layouts de enriquecimento
      description: |
        Retorna lista de layouts disponíveis para o processo de enriquecimento.
        Permite visualizar opções de formatação ao criar requisições.
      operationId: get_enrichment_layouts
      tags:
        - Enriquecimento
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Layouts retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 3
                    name:
                      type: string
                      example: Standard - Email PF
                    description:
                      type: string
                      example: Layout padrão com emails de pessoa física
                    requires_parameters:
                      type: boolean
                      example: true
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /enrichment:
    post:
      summary: Solicitar enriquecimento
      description: >
        Cria uma requisição de enriquecimento de dados com layout específico.


        **Campo parameters:**

        Alguns layouts exigem configuração adicional.


        **Exemplo - Layout 3 (Standard - Email PF):**

        - Define quantos emails por pessoa serão retornados

        - Limite máximo: 5 emails por pessoa

        - Formato: Array JSON, ex: `["2"]` para 2 emails


        **Múltiplos Parâmetros:** Devem ser enviados como array ordenado, ex:
        `["1", "1"]`
      operationId: post_enrichment
      tags:
        - Enriquecimento
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - layout_id
                - file
              properties:
                name:
                  type: string
                  description: Nome identificador do job de enriquecimento
                  example: Enriquecimento Base Clientes Janeiro
                layout_id:
                  type: integer
                  description: ID do layout a ser utilizado
                  example: 3
                parameters:
                  type: array
                  description: Parâmetros adicionais exigidos pelo layout
                  items:
                    type: string
                  example:
                    - '2'
                file:
                  type: string
                  format: byte
                  description: Arquivo em base64 contendo CPF/CNPJ para enriquecer
                  example: UEsDBBQABgAIAAAAIQ...
                callback_email:
                  type: string
                  format: email
                  description: Email para notificação quando processamento concluir
                  example: usuario@empresa.com
      responses:
        '200':
          description: Enriquecimento solicitado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: ID da requisição de enriquecimento
                    example: 98765
                  status:
                    type: string
                    example: requested
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /enrichment/{id}/result:
    get:
      summary: Obter resultado do enriquecimento
      description: >
        Recupera o resultado de uma requisição de enriquecimento.


        Se webhook foi configurado, o status do processo será enviado
        automaticamente.
      operationId: get_enrichment_result
      tags:
        - Enriquecimento
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: ID da requisição de enriquecimento
          schema:
            type: integer
          example: 98765
      responses:
        '200':
          description: Resultado retornado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 98765
                  status:
                    type: string
                    enum:
                      - requested
                      - done
                      - error
                    example: done
                  result:
                    type: object
                    description: Dados enriquecidos
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Enriquecimento não encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Enrichment not found
  /persons/prospect:
    post:
      summary: Prospecção de pessoas (contagem e job)
      description: |
        Duas funcionalidades em um endpoint:

        **1. Modo Contagem** (`export: false`)
        - Retorna quantidade total de pessoas que correspondem aos filtros
        - Não consome créditos

        **2. Modo Prospecção** (`export: true`)
        - Cria job de prospecção com filtros especificados
        - Retorna job ID
      operationId: post_persons_prospect
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - export
              properties:
                export:
                  type: boolean
                  description: false = contagem apenas, true = iniciar prospecção
                  example: false
                name:
                  type: string
                  description: Nome da pessoa (aceita busca parcial)
                  example: MARIA
                cities:
                  type: array
                  items:
                    type: string
                  description: Cidades (formato "Cidade - UF")
                  example:
                    - São Paulo - SP
                states:
                  type: array
                  items:
                    type: string
                  description: Estados (sigla UF)
                  example:
                    - SP
                neighborhoods:
                  type: array
                  items:
                    type: string
                  description: Bairros
                  example:
                    - Centro
                    - Jardins
                cbo_codes:
                  type: array
                  items:
                    type: string
                  description: Códigos CBO de profissões
                  example:
                    - '252105'
                    - '212305'
                gender:
                  type: string
                  enum:
                    - M
                    - F
                  description: Gênero (M=Masculino, F=Feminino)
                  example: M
                estimated_income:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        description: Valor mínimo da faixa
                        example: '1000.00'
                      upper:
                        type: string
                        description: Valor máximo da faixa
                        example: '500000.00'
                  description: Faixas de renda estimada
                  example:
                    - lower: '1000.00'
                      upper: '500000.00'
                birthday:
                  type: object
                  properties:
                    start_date:
                      type: string
                      format: date
                      example: '1980-01-01'
                    end_date:
                      type: string
                      format: date
                      example: '1990-12-31'
                  description: Período de data de nascimento
                age:
                  type: object
                  properties:
                    lower:
                      type: string
                      example: '18'
                    upper:
                      type: string
                      example: '90'
                  description: Faixa etária
                contact_channels:
                  type: array
                  items:
                    type: string
                    enum:
                      - whatsapp
                      - sms
                      - phone
                      - email
                      - address
                  description: Canais de contato disponíveis
                  example:
                    - email
                    - whatsapp
                match_profile:
                  type: array
                  items:
                    type: string
                  description: >-
                    Códigos dos perfis predefinidos - usar campo "code" do
                    endpoint /persons/prospect/profile
                  example:
                    - PF1
                quantity:
                  type: integer
                  description: >-
                    Quantidade de registros a exportar (apenas quando
                    export=true)
                  minimum: 1
                  example: 1000
                callback_email:
                  type: string
                  format: email
                  description: >-
                    Email para notificação quando job concluir (apenas quando
                    export=true)
                  example: usuario@empresa.com
                plan:
                  type: string
                  enum:
                    - '3'
                  description: Plano de extração (sempre "3" para export=true)
                  example: '3'
                file_formatting:
                  type: string
                  enum:
                    - excel
                    - csv
                  description: Formato do arquivo de exportação (apenas quando export=true)
                  example: excel
      responses:
        '200':
          description: Resposta de contagem ou job criado
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Resposta de contagem (export=false)
                    properties:
                      total:
                        type: integer
                        example: 1500
                  - type: object
                    description: Job criado (export=true)
                    properties:
                      job_id:
                        type: integer
                        example: 12345
                      status:
                        type: string
                        example: requested
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /company/prospect:
    post:
      summary: Prospecção de empresas (contagem e job)
      description: >
        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
      operationId: post_company_prospect
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - export
              properties:
                export:
                  type: boolean
                  description: false = contagem apenas, true = iniciar prospecção
                  example: false
                name:
                  type: string
                  description: Razão social ou nome fantasia (busca parcial)
                  example: TECNOLOGIA
                cities:
                  type: array
                  items:
                    type: string
                  description: Cidades (formato "Cidade - UF")
                  example:
                    - Rio de Janeiro - RJ
                states:
                  type: array
                  items:
                    type: string
                  description: Estados (sigla UF)
                  example:
                    - RJ
                cnae_codes:
                  type: array
                  items:
                    type: string
                  description: Códigos CNAE
                  example:
                    - '5231101'
                    - '6201500'
                headquarter_type:
                  type: string
                  enum:
                    - H
                    - B
                  description: 'Tipo de sede: H=Matriz, B=Filial'
                  example: H
                estimated_employees:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        description: Limite inferior (opcional)
                      upper:
                        type: string
                        description: Limite superior (opcional)
                  description: Array de faixas de número estimado de funcionários
                  example:
                    - upper: 9
                    - lower: 10
                      upper: 49
                    - lower: 100
                    - lower: '1'
                      upper: '800'
                estimated_created:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        format: date
                        description: Data inferior (opcional)
                      upper:
                        type: string
                        format: date
                        description: Data superior (opcional)
                  description: Array de períodos de data de fundação
                  example:
                    - lower: '2023-11-18'
                      upper: '2024-11-18'
                    - upper: '2020-11-18'
                revenues:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        description: Receita mínima (opcional)
                      upper:
                        type: string
                        description: Receita máxima (opcional)
                  description: Array de faixas de receita anual
                  example:
                    - lower: '10000.00'
                      upper: '500000.00'
                company_type:
                  type: array
                  items:
                    type: string
                    enum:
                      - ME
                      - EPP
                      - DEMAIS
                  description: Porte da empresa
                  example:
                    - ME
                    - EPP
                nature_codes:
                  type: array
                  items:
                    type: string
                  description: Códigos de natureza jurídica
                  example:
                    - '3999'
                    - '1112'
                    - '1104'
                    - '1120'
                mei_type:
                  type: string
                  enum:
                    - SIM
                    - NAO
                  description: Filtrar MEI
                  example: NAO
                sector_codes:
                  type: array
                  items:
                    type: string
                  description: Setores de atividade econômica
                  example:
                    - ATIVIDADE FINANCEIRA SEGUROS
                    - COMÉRCIO
                    - INDUSTRIA
                simple_type:
                  type: string
                  enum:
                    - SIM
                    - NAO
                  description: Empresa optante pelo Simples Nacional
                  example: SIM
                capitals:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        description: Capital mínimo (opcional)
                      upper:
                        type: string
                        description: Capital máximo (opcional)
                  description: Array de faixas de capital social
                  example:
                    - lower: '5000.00'
                      upper: '5000000.00'
                import_export:
                  type: string
                  enum:
                    - IMPORTA
                    - EXPORTA
                  description: Tipo de operação de comércio exterior
                  example: IMPORTA
                vehicles:
                  type: array
                  items:
                    type: object
                    properties:
                      lower:
                        type: string
                        description: Quantidade mínima (opcional)
                      upper:
                        type: string
                        description: Quantidade máxima (opcional)
                  description: Array de faixas de número de veículos
                  example:
                    - lower: '1'
                      upper: '50'
                quantity:
                  type: integer
                  description: >-
                    Quantidade de registros a exportar (apenas quando
                    export=true)
                  minimum: 1
                  example: 500
                callback_email:
                  type: string
                  format: email
                  description: >-
                    Email para notificação quando job concluir (apenas quando
                    export=true)
                  example: usuario@empresa.com
                plan:
                  type: string
                  enum:
                    - '3'
                  description: Plano de extração (sempre "3" para export=true)
                  example: '3'
                file_formatting:
                  type: string
                  enum:
                    - excel
                    - csv
                  description: Formato do arquivo de exportação (apenas quando export=true)
                  example: excel
      responses:
        '200':
          description: Resposta de contagem ou job criado
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Resposta de contagem (export=false)
                    properties:
                      total_companies:
                        type: integer
                        example: 850
                      total_partners:
                        type: integer
                        example: 2100
                  - type: object
                    description: Job criado (export=true)
                    properties:
                      job_id:
                        type: integer
                        example: 54321
                      status:
                        type: string
                        example: requested
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /prospection/{job_id}/result:
    get:
      summary: Obter resultado da prospecção
      description: >
        Recupera o resultado de um job de prospecção.


        Se webhook foi configurado, o status do processo será enviado
        automaticamente.
      operationId: get_prospection_result
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          description: ID do job de prospecção
          schema:
            type: integer
          example: 12345
      responses:
        '200':
          description: Resultado retornado com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    example: 12345
                  status:
                    type: string
                    enum:
                      - requested
                      - done
                      - error
                    example: done
                  result:
                    type: object
                    description: Dados prospectados
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Job não encontrado
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Job not found
  /prospection/filters:
    post:
      summary: Salvar filtro de prospecção
      description: >
        Salva um conjunto de filtros para reutilização posterior.


        Permite armazenar filtros complexos de pessoas ou empresas para uso
        recorrente.
      operationId: post_prospection_filters
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - filter_name
                - filter_type
                - data
              properties:
                filter_name:
                  type: string
                  description: Nome do filtro
                  example: Executivos SP
                filter_type:
                  type: integer
                  enum:
                    - 1
                    - 2
                  description: Tipo de filtro (1=pessoas, 2=empresas)
                  example: 1
                data:
                  type: object
                  description: >-
                    Objeto contendo os filtros (mesma estrutura usada em
                    /persons/prospect ou /company/prospect)
                  example:
                    cities:
                      - São Paulo - SP
                    professions:
                      - '999999'
                    age:
                      min_age: 30
                      max_age: 50
      responses:
        '200':
          description: Filtro salvo com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  filter_id:
                    type: integer
                    example: 123
                  message:
                    type: string
                    example: Filtro salvo com sucesso
        '400':
          description: Requisição inválida
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /prospection/filters/list_person:
    get:
      summary: Listar filtros salvos de pessoas
      description: Recupera todos os filtros salvos para prospecção de pessoas
      operationId: get_prospection_filters_person
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Filtros retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    filter_id:
                      type: integer
                      example: 123
                    filter_name:
                      type: string
                      example: Executivos SP
                    data:
                      type: object
                      description: Filtros salvos
                    created_at:
                      type: string
                      format: date-time
                      example: '2023-01-15T10:30:00Z'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /prospection/filters/list_company:
    get:
      summary: Listar filtros salvos de empresas
      description: Recupera todos os filtros salvos para prospecção de empresas
      operationId: get_prospection_filters_company
      tags:
        - Prospecção
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Filtros retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    filter_id:
                      type: integer
                      example: 456
                    filter_name:
                      type: string
                      example: Empresas Tech RJ
                    data:
                      type: object
                      description: Filtros salvos
                    created_at:
                      type: string
                      format: date-time
                      example: '2023-01-15T10:30:00Z'
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /persons/prospect/profile:
    get:
      summary: Listar perfis de prospecção
      description: >
        Retorna lista de perfis disponíveis para prospecção de pessoas.


        Perfis são conjuntos predefinidos de características demográficas e
        comportamentais.
      operationId: get_persons_prospect_profile
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Perfis retornados com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: URL da próxima página (null se não houver)
                    example: null
                  previous:
                    type: string
                    nullable: true
                    description: URL da página anterior (null se não houver)
                    example: null
                  count:
                    type: integer
                    description: Total de perfis disponíveis
                    example: 14
                  page_size:
                    type: integer
                    description: Tamanho da página
                    example: 20
                  results:
                    type: array
                    description: Lista de perfis
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Código identificador do perfil
                          example: PF1
                        description:
                          type: string
                          description: Descrição do perfil
                          example: Comprador(A) De Supermercado Premium
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /geo/city:
    get:
      summary: Obter cidades
      description: >
        Retorna cidades com base em critérios de pesquisa.


        **Formato de resposta:** "Cidade - UF" (ex: "São Paulo - SP")


        **IMPORTANTE:** O valor `name` retornado é o que deve ser enviado para
        prospecção.
      operationId: get_cities
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      parameters:
        - name: name
          in: query
          required: false
          description: Filtro por nome da cidade
          schema:
            type: string
          example: São Paulo
        - name: state
          in: query
          required: false
          description: Filtro por estado (sigla UF)
          schema:
            type: string
          example: SP
      responses:
        '200':
          description: Cidades retornadas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Nome da cidade no formato "Cidade - UF"
                      example: São Paulo - SP
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /geo/neighborhood:
    get:
      summary: Obter bairros
      description: |
        Retorna bairros com base em critérios de pesquisa.

        **Formato de resposta:** "Bairro - Cidade - UF"
      operationId: get_neighborhoods
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      parameters:
        - name: name
          in: query
          required: false
          description: Filtro por nome do bairro
          schema:
            type: string
        - name: city
          in: query
          required: false
          description: Filtro por cidade
          schema:
            type: string
        - name: state
          in: query
          required: false
          description: Filtro por estado (sigla UF)
          schema:
            type: string
      responses:
        '200':
          description: Bairros retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Nome no formato "Bairro - Cidade - UF"
                      example: Distrito de Roselândia - Bela Vista de Goiás - GO
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /cbo:
    get:
      summary: Obter profissões (CBO)
      description: >
        Retorna ocupações baseadas na Classificação Brasileira de Ocupações
        (CBO).


        Suporta busca por código CBO ou descrição da profissão.


        **IMPORTANTE:** O `code` retornado é o que deve ser usado em requisições
        de prospecção.
      operationId: get_cbo
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      parameters:
        - name: code
          in: query
          required: false
          description: Código CBO
          schema:
            type: string
          example: '999999'
        - name: description
          in: query
          required: false
          description: Descrição da profissão
          schema:
            type: string
          example: EMPRESÁRIO
      responses:
        '200':
          description: Profissões retornadas com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: Código CBO a ser usado em prospecção
                      example: '999999'
                    description:
                      type: string
                      description: Descrição da profissão
                      example: EMPRESÁRIO
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /cnae:
    get:
      summary: Obter CNAEs
      description: >
        Retorna classificações CNAE (Classificação Nacional de Atividades
        Econômicas).


        Aceita código CNAE ou descrição.


        **IMPORTANTE:** O `code` retornado é o que deve ser enviado para
        prospecção.
      operationId: get_cnae
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      parameters:
        - name: code
          in: query
          required: false
          description: Código CNAE
          schema:
            type: string
          example: '6201500'
        - name: description
          in: query
          required: false
          description: Descrição do CNAE
          schema:
            type: string
          example: Desenvolvimento de software
      responses:
        '200':
          description: CNAEs retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: Código CNAE para usar em prospecção
                      example: '6201500'
                    description:
                      type: string
                      description: Descrição detalhada do CNAE
                      example: Desenvolvimento de programas de computador sob encomenda
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
  /sector/cnae:
    get:
      summary: Obter setores CNAE
      description: >
        Retorna informações de setor CNAE.


        Suporta filtro por código ou descrição do setor.


        **IMPORTANTE:** A `description` retornada é o que deve ser enviada para
        prospecção.
      operationId: get_sector_cnae
      tags:
        - Auxiliares
      security:
        - ApiKeyAuth: []
      parameters:
        - name: code
          in: query
          required: false
          description: Código do setor CNAE
          schema:
            type: string
        - name: description
          in: query
          required: false
          description: Descrição do setor
          schema:
            type: string
          example: Tecnologia
      responses:
        '200':
          description: Setores retornados com sucesso
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: Código do setor CNAE
                      example: '62'
                    description:
                      type: string
                      description: Descrição a ser usada em prospecção
                      example: Tecnologia da Informação
        '403':
          description: Token de autenticação inválido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
