Look a Like

Manual de Integração — API Direct Data

---

Produto: Look a Like — Geração de Listas Similares por Critérios de Negócio

Base URL: /api/LookALike

Autenticação: Header Token (Guid)

Versão: 1.0

1. Visão Geral

1.1 Descrição do Produto

O Look a Like é o produto Direct Data que constrói listas de empresas similares a um perfil definido pelo cliente, a partir de critérios de negócio como atividade econômica (CNAE), localização (UF, cidade, bairro, CEP), porte, situação cadastral, situação especial e faixa de funcionários. O resultado final é um arquivo CSV enriquecido, pronto para uso comercial.

Esta API permite ao cliente submeter os filtros de busca, visualizar uma amostra do resultado (top 5 empresas) antes de comprar, cotar o preço para uma quantidade desejada, confirmar a compra (cobrança automática) e baixar o arquivo final quando o enriquecimento concluir.

1.2 Conceitos-Chave

O fluxo do Look a Like é composto por quatro conceitos principais:

1.3 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.4 Estrutura de Resposta Padrão

Todas as respostas (exceto Download, que devolve um stream binário) 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": "22/05/2026 14:32:15",
  "error": null
}

1.5 Enumeradores

Status do Preview

Retornado no campo previewStatus dos endpoints Filter e GetPreview:

Status do Export

Retornado no campo exportStatus dos endpoints Purchase e GetExport:

Modo de Filtro CNAE Unificado

Define em qual coluna de CNAE o filtro unificado é aplicado:

1.6 Fluxo de Integração Recomendado

O fluxo padrão segue 6 etapas: enviar filtros, aguardar o preview, cotar, comprar, aguardar o enriquecimento e finalmente baixar o CSV.

2. Endpoints — Preview

2.1 Filter

Submete os filtros de busca e dispara a construção assíncrona do preview. Retorna o previewGuid que deve ser usado em todas as chamadas subsequentes do fluxo. Pelo menos uma whitelist deve estar preenchida em algum dos filtros.

Body da Requisição

Objeto filters

A maioria dos campos aceita o formato FormValue: { "whiteList": ["valor1", "valor2"], "blackList": ["valor3"] }
whiteList inclui apenas as empresas que possuem os valores informados; blackList exclui empresas que possuem os valores informados. Ambas as listas podem ser vazias.

Exemplo de Requisição

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

{
  "numberOfResults": 5000,
  "filters": {
    "states": { "whiteList": ["SP"], "blackList": [] },
    "cities": { "whiteList": ["São Paulo"], "blackList": [] },
    "neighborhoods": { "whiteList": ["Centro", "Bela Vista"], "blackList": [] },
    "primaryCnae": { "whiteList": ["6201500", "6202300"], "blackList": [] },
    "companySize": { "whiteList": ["1", "3"], "blackList": [] },
    "registrationStatus": { "whiteList": ["1"], "blackList": [] },
    "employeeCountRange": { "min": 10, "max": 49 },
    "openingDateStart": "01/01/2010",
    "openingDateEnd": "31/12/2020"
  }
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 215,
  "dateTimeExecution": "22/05/2026 14:32:15",
  "error": null,
  "previewGuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "previewStatus": "Processing",
  "createdAt": "22/05/2026 14:32:15"
}

Campos da Resposta

2.2 GetPreview

Retorna o status atual do preview. Quando o status é PreviewCompleted, a resposta inclui o total de empresas encontradas (totalFound) e uma amostra de até 5 empresas (sample).

Path Parameters

Exemplo de Requisição

GET /api/LookALike/Preview/a1b2c3d4-e5f6-7890-abcd-1234567890ab HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200) — PreviewCompleted

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 89,
  "dateTimeExecution": "22/05/2026 14:33:08",
  "error": null,
  "previewGuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "previewStatus": "PreviewCompleted",
  "createdAt": "22/05/2026 14:32:15",
  "completedAt": "22/05/2026 14:32:48",
  "totalFound": 3247,
  "sample": [
    {
      "companyName": "TECIDOS EXEMPLO LTDA",
      "startOfActivity": "14/03/2010",
      "city": "São Paulo",
      "companySize": "ME"
    }
  ]
}

Campos da Resposta

3. Endpoints — Cotação e Compra

3.1 Quote

Calcula o preço para exportar uma quantidade específica do preview. Não cobra nem reserva nada. Útil para o cliente exibir o valor antes de confirmar a compra.

Body da Requisição

Exemplo de Requisição

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

{
  "previewGuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "quantity": 500
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 35,
  "dateTimeExecution": "22/05/2026 14:35:02",
  "error": null,
  "previewGuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "quantity": 500,
  "unitPrice": 0.45,
  "totalPrice": 225.00,
  "currency": "BRL"
}

Campos da Resposta

3.2 Purchase

Confirma a compra: cria o compilado (subset do preview), cobra o valor da empresa e enfileira o enriquecimento. Retorna o exportGuid que deve ser usado para acompanhar o status e baixar o arquivo final.

Body da Requisição

Exemplo de Requisição

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

{
  "previewGuid": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "quantity": 500
}

Exemplo de Resposta (200)

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 412,
  "dateTimeExecution": "22/05/2026 14:36:14",
  "error": null,
  "exportGuid": "b2c3d4e5-f6a7-8901-bcde-2345678901bc",
  "exportStatus": "Processing",
  "amountCharged": 225.00,
  "currency": "BRL",
  "purchasedAt": "22/05/2026 14:36:14"
}

Campos da Resposta

4. Endpoints — Export e Download

4.1 GetExport

Retorna o estado atual de um export. O cliente deve fazer polling neste endpoint até o status ficar Completed (ou Error em caso de falha).

Path Parameters

Exemplo de Requisição

GET /api/LookALike/Export/b2c3d4e5-f6a7-8901-bcde-2345678901bc HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200) — Completed

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 47,
  "dateTimeExecution": "22/05/2026 14:42:01",
  "error": null,
  "exportGuid": "b2c3d4e5-f6a7-8901-bcde-2345678901bc",
  "exportStatus": "Completed",
  "listName": "Têxtil SP — Maio/2026",
  "quantity": 500,
  "amountCharged": 225.00,
  "currency": "BRL",
  "purchasedAt": "22/05/2026 14:36:14",
  "completedAt": "22/05/2026 14:41:53",
  "refundReason": null,
  "isDownloadReady": true
}

Campos da Resposta

4.2 Download

Devolve o stream de um pacote ZIP contendo o arquivo CSV final com os dados enriquecidos (e eventuais metadados auxiliares). Disponível apenas quando o status do export é Completed. O conteúdo é entregue como application/zip com cabeçalho Content-Disposition: attachment.

Path Parameters

Exemplo de Requisição

GET /api/LookALike/Export/b2c3d4e5-f6a7-8901-bcde-2345678901bc/Download HTTP/1.1
Host: {base-url-directdata}
Token: 00000000-0000-0000-0000-000000000000

Exemplo de Resposta (200)

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="LookALike-API_Preview_a1b2c3d4-e5f6-7890-abcd-ef1234567890.zip"

<binary ZIP stream>

# Dentro do ZIP (exemplo):
#   resultado.csv          ← lista enriquecida (CNPJ, Razão Social, CNAE, etc.)
#   metadata.json          ← metadados da exportação (opcional)

5. Mapeamento de Erros por Endpoint

5.1 Estrutura do Erro

Quando uma requisição falha (exceto no Download), 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": "22/05/2026 14:40:01",
  "error": {
    "fieldName": "Token",
    "message": "Token de acesso inválido. Verifique suas credenciais."
  }
}

// Exemplo de resposta 404 Not Found (Guid não pertence à empresa)
{
  "success": false,
  "status": "Not Found",
  "elapsedTimeMs": 28,
  "dateTimeExecution": "22/05/2026 14:40:14",
  "error": {
    "fieldName": "previewGuid",
    "message": "Preview não encontrado ou não acessível."
  }
}

5.2 Filter / GetPreview

POST /api/LookALike/Filter · GET /api/LookALike/Preview/{previewGuid}

5.3 Quote / Purchase

POST /api/LookALike/Quote · POST /api/LookALike/Purchase

5.4 GetExport / Download

GET /api/LookALike/Export/{exportGuid} · GET /api/LookALike/Export/{exportGuid}/Download