Pesquisa Avançada

Manual de Integração — API Direct Data

---

Produto: Pesquisa Avançada — Busca Filtrada de Pessoas Físicas e Jurídicas

Base URL: /api/AdvancedSearch

Autenticação: Header Token (Guid)

Versão: 2.1

1. Visão Geral

1.1 Descrição do Produto

A Pesquisa Avançada é o produto Direct Data que permite ao cliente realizar buscas filtradas de Pessoas Jurídicas (PJ) e Pessoas Físicas (PF). O fluxo é dividido em duas etapas:

1. Filtro: o cliente envia critérios de busca (razão social, CNAE, UF, endereço, nome, data de nascimento etc.) e recebe uma lista de candidatos contendo identificadores internos (Id) e dados básicos. Essa etapa não consome saldo.
2. Processamento: o cliente seleciona os Ids desejados e dispara o processamento. O backend faz o enriquecimento completo dos registros e retorna um SearchUid que identifica a pesquisa concluída. Os resultados detalhados são obtidos via ViewSearch. Essa etapa consome saldo conforme a quantidade de itens processados.

1.2 Autenticação

Todos os endpoints exigem autenticação via header Token contendo o GUID de API emitido pela Direct Data para a sua empresa. Esse token é único por empresa e deve ser tratado como credencial sensível.

1.3 Estrutura de Resposta Padrão

Todas as respostas estendem o envelope ResponseMetaDataDTO. Independente de sucesso ou falha, o cliente sempre receberá os campos abaixo no corpo da resposta:

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 124,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null
}

1.4 Enumeradores

Status do Item Pesquisado (campo resultId)

Após chamar ProcessingIds, cada item da pesquisa passa por um ciclo de processamento. O campo resultId retornado em ViewSearch.searchItems[] indica o estado atual do item, e o campo result traz a descrição textual correspondente. Os valores possíveis retornados pela API são:

1.5 Fluxo de Integração Recomendado

O fluxo padrão de uso da API combina os endpoints de Filtro, Processamento e Visualização, conforme o diagrama abaixo:

2. Endpoints POST

2.1 FilterLegalPerson

Realiza a busca filtrada de Pessoas Jurídicas. Retorna a lista de empresas que atendem aos critérios e a quantidade total de registros encontrados. Esta operação não consome saldo — ela serve para o cliente avaliar o resultado antes de disparar o processamento.

Body da Requisição

Exemplo de Requisição

POST /api/AdvancedSearch/FilterLegalPerson HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "companyName": "",
  "openingDateStart": "2020-01-01",
  "openingDateEnd": "2024-12-31",
  "companySize": "",
  "cnae": "6201500",
  "city": "",
  "state": "SP",
  "legalNature": ""
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 845,
  "dateTimeExecution": "08/05/2026 14:32:15",
  "error": null,
  "listFilters": [
    {
      "id": "9c4b1e02-...",
      "cnpj": "12345678000190",
      "companyName": "EXEMPLO TECNOLOGIA LTDA",
      "tradeName": "EXEMPLO TECH",
      "openingDate": "2021-04-12"
    }
  ],
  "numberOfCompanies": 1
}

Campos da Resposta

2.2 FilterNaturalPerson

Realiza a busca filtrada de Pessoas Físicas. Retorna a lista de pessoas que atendem aos critérios e a quantidade total de registros encontrados. Esta operação não consome saldo.

Body da Requisição

Exemplo de Requisição — filtro padrão

POST /api/AdvancedSearch/FilterNaturalPerson HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "fullName": "JOAO DA SILVA",
  "state": "RJ",
  "dateOfBirthStart": "1980-01-01",
  "dateOfBirthEnd": "1990-12-31"
}

Exemplo de Requisição — com filtros Premium

POST /api/AdvancedSearch/FilterNaturalPerson HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "state": "SP",
  "receiveBolsaFamilia": true,
  "receiveBPC": false
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 612,
  "dateTimeExecution": "08/05/2026 14:33:02",
  "error": null,
  "listFilters": [
    {
      "id": "0a5d7b22-...",
      "cpf": "12345678901",
      "fullName": "JOAO DA SILVA",
      "motherName": "MARIA DA SILVA",
      "dateOfBirth": "1985-07-22"
    }
  ],
  "numberOfPeople": 1
}

Campos da Resposta

2.3 ProcessingIds

Dispara o processamento dos registros selecionados a partir do resultado de FilterLegalPerson ou FilterNaturalPerson. O backend cria uma pesquisa, retorna imediatamente o SearchUid e o enriquecimento ocorre de forma assíncrona. O cliente deve aguardar e consultar os resultados via ViewSearch.

Body da Requisição

{
  "metaDados": { ... },
  "retorno": {
    "cadastroPessoaFisicaPlus": { ... },
    "beneficiosSociais": { ... }
  }
}

Exemplo de Requisição — padrão

POST /api/AdvancedSearch/ProcessingIds HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "listIds": [
    "9c4b1e02-...",
    "0a5d7b22-..."
  ],
  "searchName": "Prospecção SP — Tecnologia (Maio/2026)"
}

Exemplo de Requisição — modo Premium

POST /api/AdvancedSearch/ProcessingIds HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "listIds": [
    "9c4b1e02-...",
    "0a5d7b22-..."
  ],
  "searchName": "Beneficiários SP (Maio/2026)",
  "premium": true
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 215,
  "dateTimeExecution": "08/05/2026 14:34:18",
  "error": null,
  "searchUid": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}

Campos da Resposta

2.4 ViewSearch

Retorna o detalhamento completo de uma pesquisa previamente criada via ProcessingIds. Inclui o consumo total da pesquisa e a lista de itens processados — cada item com seu status individual e o JSON enriquecido devolvido pelas fontes de dados.

Body da Requisição

Exemplo de Requisição

POST /api/AdvancedSearch/ViewSearch HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "searchUid": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 380,
  "dateTimeExecution": "08/05/2026 14:36:45",
  "error": null,
  "viewSearch": {
    "consumptionTotal": 4.50,
    "errors": [],
    "warnings": [
      {
        "title": "Documento não localizado",
        "description": "1 item retornou sem dados na fonte externa."
      }
    ],
    "searchItems": [
      {
        "name": "EXEMPLO TECNOLOGIA LTDA",
        "document": "12345678000190",
        "resultId": 4,
        "result": "Pesquisado com Sucesso",
        "returnJson": { "...": "payload completo do enriquecimento" }
      },
      {
        "name": "OUTRA EMPRESA EXEMPLO LTDA",
        "document": "98765432000110",
        "resultId": 6,
        "result": "Falha na Pesquisa",
        "returnJson": null
      }
    ]
  }
}

Campos da Resposta

2.5 Reprocessing

Solicita o reprocessamento de uma pesquisa existente. Útil quando a pesquisa terminou com itens em status terminal de falha — tipicamente 6 — Falha na Pesquisa — e o cliente quer tentar novamente sem precisar refazer a etapa de filtragem. Também pode ser usado para itens em 5 — Parcialmente Pequisado caso se queira tentar uma nova consulta nas fontes que não responderam.

Body da Requisição

Exemplo de Requisição

POST /api/AdvancedSearch/Reprocessing HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000
Content-Type: application/json

{
  "guid": "f1e2d3c4-b5a6-7890-1234-567890abcdef"
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 142,
  "dateTimeExecution": "08/05/2026 14:38:02",
  "error": null
}

3. Mapeamento de Erros por Endpoint

3.1 Estrutura do Erro

Quando uma requisição falha, o envelope ResponseMetaDataDTO retorna o campo error preenchido com o nome do campo problemático e a mensagem correspondente. O campo success será false e o status HTTP refletirá o tipo de falha.

// Exemplo de resposta 401 Unauthorized (token inválido)
{
  "success": false,
  "status": "Unauthorized",
  "elapsedTimeMs": 12,
  "dateTimeExecution": "08/05/2026 14:40:01",
  "error": {
    "fieldName": "Token",
    "message": "Token de acesso inválido. Verifique suas credenciais."
  }
}

// Exemplo de resposta 403 Forbidden (produto não liberado)
{
  "success": false,
  "status": "Forbidden",
  "elapsedTimeMs": 18,
  "dateTimeExecution": "08/05/2026 14:40:14",
  "error": {
    "fieldName": "Product",
    "message": "Produto não liberado para esta empresa."
  }
}

// Exemplo de resposta 500 Internal Server Error
{
  "success": false,
  "status": "Internal Server Error",
  "elapsedTimeMs": 320,
  "dateTimeExecution": "08/05/2026 14:40:55",
  "error": {
    "fieldName": null,
    "message": "Erro inesperado ao processar a requisição."
  }
}

3.2 FilterLegalPerson

POST /api/AdvancedSearch/FilterLegalPerson

3.3 FilterNaturalPerson

POST /api/AdvancedSearch/FilterNaturalPerson

3.4 ProcessingIds

POST /api/AdvancedSearch/ProcessingIds

3.5 ViewSearch

POST /api/AdvancedSearch/ViewSearch

3.6 Reprocessing

POST /api/AdvancedSearch/Reprocessing