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 da Direct Data que identifica empresas semelhantes ao perfil desejado. A partir de um conjunto de filtros (CNAE, UF, cidade, porte, situação cadastral, etc.), o cliente obtém uma lista de CNPJs qualificados e enriquecidos.

A API pública v2 substitui integralmente o fluxo anterior (Filter → Preview → Quote → Purchase v1), com três diferenças principais:

• Busca síncrona. O SearchPreview devolve o total encontrado e uma amostra na mesma requisição, sem polling.
• Persistência sob demanda. A lista de empresas só é gerada quando o cliente efetivamente compra (Purchase). Buscas exploratórias não geram registros no banco.
• Compra em lotes. Uma mesma lista aceita várias compras parciais durante 30 dias, sem necessidade de refazer a busca.

1.2 Conceitos-Chave

1.3 Autenticação

Todos os endpoints exigem o header Token com o Guid de autenticação da sua conta. Sem token válido, a resposta é 401 Unauthorized.

Token: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

1.4 Estrutura de Resposta Padrão

Todas as respostas seguem o formato:

{
  "success": true,
  "status": "OK",
  "elapsedTimeMs": 42,
  "dateTimeExecution": "07/07/2026 16:41:01",
  "error": null,
  ... (campos específicos do endpoint)
}

Em caso de erro:

{
  "success": false,
  "status": "Bad Request",
  "elapsedTimeMs": 15,
  "dateTimeExecution": "07/07/2026 16:41:02",
  "error": {
    "fieldName": "Quantity",
    "message": "A quantidade deve ser maior que zero e não pode exceder o total encontrado no preview."
  }
}

1.5 Fluxo de Integração

2. Endpoints — Busca e Cotação

Os endpoints desta seção não geram cobrança e não persistem nada. Quote devolve o preço unitário; SearchPreview devolve total + amostra da busca com um SearchGuid para reutilização na compra.

2.1 SearchPreview

Executa a busca de forma síncrona. Retorna o total de empresas que batem com o filtro (capado internamente), uma amostra de até 5 empresas e um SearchGuid efêmero que pode ser reutilizado no Purchase sem precisar reenviar o filtro.

Body da Requisição

Objeto filters

A maioria dos campos aceita o formato FormValue: { "whiteList": ["valor1", "valor2"], "blackList": ["valor3"] }
whiteList inclui apenas 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/v2/SearchPreview 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": ["ME", "EPP"], "blackList": [] },
    "registrationStatus": { "whiteList": ["1"], "blackList": [] },
    "employeeCountRange": { "min": 10, "max": 49 },
    "openingDateStart": "01/01/2010",
    "openingDateEnd": "31/12/2020"
  },
  "ignoredCnpjList": [
    "12.345.678/0001-99",
    "98765432000111"
  ]
}

Exemplo alternativo — busca por CNAE unificado

{
  "numberOfResults": 1000,
  "filters": {
    "states": { "whiteList": ["SP", "RJ"], "blackList": [] },
    "unifiedCnae": {
      "mode": 3,
      "whiteList": ["4711302", "4712100"],
      "blackList": []
    },
    "companySize": { "whiteList": ["EPP", "MEDIA", "GRANDE"], "blackList": [] }
  }
}

Response — 200 OK

{
  "total": 42,
  "searchGuid": "653805e2-1e6b-43c6-acb8-ccedbf44a96e",
  "rows": [
    {
      "companyName": "ACM* ****CI* LTDA",
      "cnpj": "12.***.***/**01-**",
      "state": "SP",
      "companySize": "ME",
      "registrationStatus": "Ativa",
      "foundationDate": "12/03/2010",
      "mainCnae": { "code": "47.11-3-02", "description": "Comércio varejista de mercadorias em geral" },
      "secondaryCnaes": []
    }
  ],
  "success": true,
  "elapsedTimeMs": 4523,
  "dateTimeExecution": "07/07/2026 16:41:01",
  "error": null
}

2.2 Quote

Retorna o preço unitário atual do Look a Like. Valor global — não varia por cliente. Não gera cobrança.

Request

Sem body e sem query params. Só o header Token.

Response — 200 OK

{
  "unitPrice": 0.36,
  "currency": "BRL",
  "success": true,
  "elapsedTimeMs": 3,
  "dateTimeExecution": "07/07/2026 16:40:00",
  "error": null
}

3. Endpoints — Compra

3.1 Purchase

Confirma a compra e cobra sua empresa por cada empresa incluída no lote. Aceita dois modos:

• Primeira compra: envie searchGuid retornado pelo SearchPreview. A lista é criada nesse momento.
• Comprar mais da mesma lista: envie listGuid retornado pela primeira compra. Válido por 30 dias.

Request

POST /api/LookALike/v2/Purchase HTTP/1.1
Token: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
Content-Type: application/json

{
  "searchGuid": "653805e2-1e6b-43c6-acb8-ccedbf44a96e",
  "quantity": 10
}

Ou, para comprar mais empresas de uma lista existente:

{
  "listGuid": "589d81b6-a5f5-4dc9-b061-4578f59323f4",
  "quantity": 5
}

Response — 200 OK

{
  "listGuid": "589d81b6-a5f5-4dc9-b061-4578f59323f4",
  "exportGuid": "3da0f3eb-3748-453b-900b-c8f2e50a59e7",
  "quantityCharged": 10,
  "amountCharged": 3.60,
  "currency": "BRL",
  "status": "Enriquecendo Arquivo",
  "availableUntil": "06/08/2026, 16:31",
  "purchasedAt": "07/07/2026, 16:41",
  "totalOfList": 42,
  "alreadyPurchased": 10,
  "available": 32,
  "success": true,
  "elapsedTimeMs": 16595,
  "dateTimeExecution": "07/07/2026 16:41:01",
  "error": null
}

Response — 400 Bad Request (quantidade excede disponível)

{
  "listGuid": "00000000-0000-0000-0000-000000000000",
  "exportGuid": null,
  "quantityCharged": 0,
  "amountCharged": 0,
  "currency": "BRL",
  "status": "Bad Request",
  "availableUntil": "",
  "purchasedAt": null,
  "totalOfList": 42,
  "alreadyPurchased": 32,
  "available": 10,
  "success": false,
  "elapsedTimeMs": 45,
  "dateTimeExecution": "07/07/2026 17:15:22",
  "error": {
    "fieldName": "Quantity",
    "message": "A quantidade deve ser maior que zero e não pode exceder o total encontrado no preview."
  }
}

4. Endpoints — Acompanhamento e Download

4.1 GetExport

Retorna o status atual de um lote de compra. Após o Purchase, o compilado passa pelos estágios Pago → Enriquecendo Arquivo → Concluído. Baixe o arquivo em Download apenas quando isDownloadReady for true.

Path

Response — 200 OK

{
  "exportGuid": "3da0f3eb-3748-453b-900b-c8f2e50a59e7",
  "exportStatus": "Concluído",
  "listName": "API_Preview_589d81b6-a5f5-4dc9-b061-4578f59323f4",
  "quantity": 10,
  "amountCharged": 3.60,
  "currency": "BRL",
  "purchasedAt": "07/07/2026 16:41:01",
  "completedAt": "07/07/2026 16:44:38",
  "refundReason": null,
  "isDownloadReady": true,
  "success": true,
  "elapsedTimeMs": 12,
  "dateTimeExecution": "07/07/2026 17:00:00",
  "error": null
}

4.2 Download

Baixa o arquivo ZIP enriquecido do lote. Disponível apenas quando exportStatus == "Concluído".

Path

Response

Em caso de sucesso, retorna 200 OK com o corpo em application/zip (stream binário — não é JSON). Nome do arquivo: LookALike-{ListName}.zip.

Códigos de erro específicos

5. Códigos de Erro

5.1 Estrutura do Erro

Em qualquer resposta com success: false, o corpo inclui o campo error:

"error": {
  "fieldName": "Quantity",
  "message": "A quantidade deve ser maior que zero e não pode exceder o total encontrado no preview."
}

5.2 Códigos HTTP e Mensagens

6. Limites e Boas Práticas

6.1 Rate Limit

Os endpoints SearchPreview e Purchase têm limite de requisições simultâneas por Token (não por janela de tempo, pois cada requisição pode levar até 5 min no pior caso).

Quando o limite é atingido, a API retorna 429 Too Many Requests. Espere alguma requisição pendente concluir antes de tentar de novo.

6.2 SearchGuid e Cache

• Cada chamada de SearchPreview gera um SearchGuid novo — mesmo se o filtro for idêntico.
• O SearchGuid vive em memória por 15 minutos.
• É consumido (invalidado) na primeira Purchase — não dá para reutilizar.
• Se expirar antes da compra, chame SearchPreview de novo.
• O cache é isolado por cliente — SearchGuid gerado por outra empresa nunca funciona no seu token.

6.3 ListGuid e Expiração de Lista

• Cada primeira Purchase materializa a lista e devolve um ListGuid persistente.
• Válido por 30 dias — durante esse prazo, você pode chamar Purchase passando o mesmo listGuid para comprar mais empresas da mesma busca.
• A quantidade máxima é limitada pelo total original encontrado — o campo available na resposta do Purchase mostra o saldo atual.
• Após 30 dias, o listGuid expira e a lista bloqueia novas compras — refaça o SearchPreview para gerar uma nova busca com dados frescos.
• Listas de versões anteriores (v1) não aceitam novas compras via este endpoint — retornam 409.