Endpoints da API

Todos os endpoints ficam sob https://app.datalead.datastone.com.br/api/v1 e exigem Authorization: Bearer dl_…, exceto a especificação OpenAPI. Veja API pública para tokens, escopos, limites e paginação.

Nos exemplos abaixo, $DL é o seu token:

export DL="dl_SEU_TOKEN"
export API="https://app.datalead.datastone.com.br/api/v1"

Resumo

Método e rota	Escopo	Paginação
`GET /leads`	leitura	cursor
`GET /leads/{id}`	leitura	—
`PATCH /leads/{id}`	escrita	—
`GET /conversations`	leitura	cursor
`GET /conversations/{id}`	leitura	—
`GET /playbooks`	leitura	lista completa
`GET /usage`	leitura	—
`GET /webhooks`	leitura	lista completa
`GET /openapi.json`	público	—

GET /leads

Lista os leads da conta, do mais recente para o mais antigo. Aceita ?limit= (1 a 200, padrão 50) e ?cursor=. Um ?limit= fora dessa faixa devolve 400, com a faixa na mensagem — não é recortado em silêncio.

curl -H "Authorization: Bearer $DL" "$API/leads?limit=2"

{
  "data": [
    {
      "id": "5f1c8b0e-9d2a-4a11-9a0e-2c6d1f3b7e40",
      "created_at": "2026-09-05T14:22:07.118Z",
      "name": "João Ribeiro",
      "email": "jo***@padariacentral.com.br",
      "phone": "(11) 9****-0042",
      "company": "Padaria Central",
      "score": 82,
      "status": "qualified",
      "conversation_id": "c2b0f6a1-3d4e-4f52-8b77-9e1a5c0d2f31",
      "crm": {
        "hubspot": {
          "id": "701234567",
          "url": "https://app.hubspot.com/contacts/0/contact/701234567",
          "status": "synced"
        }
      }
    },
    {
      "id": "8a7d2c14-6e3b-4c90-b2f1-0d4e9a6c7b52",
      "created_at": "2026-09-05T11:03:44.902Z",
      "name": "Marina Alves",
      "email": null,
      "phone": "(21) 9****-1188",
      "company": null,
      "score": 41,
      "status": "open",
      "conversation_id": "3d9f1a72-8c05-4be6-a7d3-1f28e4b90c65",
      "crm": {}
    }
  ],
  "next_cursor": "MjAyNi0wOS0wNVQxMTowMzo0NC45MDJafDhhN2QyYzE0LTZlM2ItNGM5MC1iMmYxLTBkNGU5YTZjN2I1Mg"
}

status é um de open, qualified, disqualified, converted. O objeto crm traz uma chave por provedor conectado, com status de sincronização em pending, synced ou error.

GET /leads/{id}

curl -H "Authorization: Bearer $DL" "$API/leads/5f1c8b0e-9d2a-4a11-9a0e-2c6d1f3b7e40"

A resposta é o objeto de lead acima, sem envelope. Um lead inexistente — ou de outra conta — devolve o mesmo 404, para o identificador não virar oráculo de existência.

PATCH /leads/{id}

Única escrita da API. Exige token com escopo de escrita; um token de leitura recebe 403.

curl -X PATCH \
  -H "Authorization: Bearer $DL" \
  -H "Content-Type: application/json" \
  -d '{"status":"converted"}' \
  "$API/leads/5f1c8b0e-9d2a-4a11-9a0e-2c6d1f3b7e40"

A resposta é o lead atualizado, com o contato mascarado como no GET:

{
  "id": "5f1c8b0e-9d2a-4a11-9a0e-2c6d1f3b7e40",
  "created_at": "2026-09-05T14:22:07.118Z",
  "name": "João Ribeiro",
  "email": "jo***@padariacentral.com.br",
  "phone": "(11) 9****-0042",
  "company": "Padaria Central",
  "score": 82,
  "status": "converted",
  "conversation_id": "c2b0f6a1-3d4e-4f52-8b77-9e1a5c0d2f31",
  "crm": { "hubspot": { "id": "701234567", "url": "https://app.hubspot.com/contacts/0/contact/701234567", "status": "synced" } }
}

O corpo aceita apenas status. Qualquer outro campo é recusado com 400:

{ "error": "Corpo inválido. Envie { \"status\": … } com um destes valores: open, qualified, disqualified, converted." }

Recusar em vez de ignorar é deliberado: quem manda { "status": …, "score": … } acredita ter mudado os dois, e gravar só um deixaria o seu CRM e o Data Lead divergentes sem ninguém perceber. O score é calculado pelo agente e o contato é dado do visitante — nenhum dos dois é gravável pela API.

GET /conversations

Aceita ?limit=, ?cursor=, ?since= (data ISO 8601) e ?outcome= (open, qualified, disqualified, handoff, closed). A lista não traz a transcrição.

curl -H "Authorization: Bearer $DL" \
  "$API/conversations?since=2026-09-01T00:00:00Z&outcome=qualified&limit=1"

{
  "data": [
    {
      "id": "c2b0f6a1-3d4e-4f52-8b77-9e1a5c0d2f31",
      "started_at": "2026-09-05T14:18:02.005Z",
      "last_message_at": "2026-09-05T14:22:05.771Z",
      "ended_at": "2026-09-05T14:22:07.118Z",
      "outcome": "qualified",
      "score": 82,
      "is_test": false,
      "playbook_id": "b41d7e59-2a68-4f03-8c1d-5e7a9b0c2d34",
      "summary": "Padaria com 12 funcionários buscando controle de estoque; pediu contato comercial."
    }
  ],
  "next_cursor": null
}

Uma data ilegível em since devolve 400 (Parâmetro since deve ser uma data ISO 8601), e um outcome fora da lista devolve Parâmetro outcome inválido — aceitar em silêncio devolveria a base inteira para quem pediu "só o que mudou desde ontem".

GET /conversations/{id}

A conversa com a transcrição, em ordem cronológica.

curl -H "Authorization: Bearer $DL" "$API/conversations/c2b0f6a1-3d4e-4f52-8b77-9e1a5c0d2f31"

{
  "id": "c2b0f6a1-3d4e-4f52-8b77-9e1a5c0d2f31",
  "started_at": "2026-09-05T14:18:02.005Z",
  "last_message_at": "2026-09-05T14:22:05.771Z",
  "ended_at": "2026-09-05T14:22:07.118Z",
  "outcome": "qualified",
  "score": 82,
  "is_test": false,
  "playbook_id": "b41d7e59-2a68-4f03-8c1d-5e7a9b0c2d34",
  "summary": "Padaria com 12 funcionários buscando controle de estoque; pediu contato comercial.",
  "messages": [
    { "id": "0f2a…", "role": "assistant", "content": "Oi! Posso ajudar a escolher o plano?", "ts": "2026-09-05T14:18:03.220Z" },
    { "id": "1b8c…", "role": "user", "content": "Meu e-mail é jo***@padariacentral.com.br", "ts": "2026-09-05T14:21:40.010Z" }
  ],
  "messages_truncated": false
}

O texto das mensagens sai com e-mail e telefone mascarados, as mesmas máscaras de /leads. A transcrição íntegra só é acessível no painel, autenticado por pessoa.

Teto da transcrição. messages traz no máximo 5.000 mensagens. Acima disso vêm as 5.000 primeiras e messages_truncated vira true — o campo está sempre na resposta, inclusive como false, para o seu código poder conferir sem adivinhar. Uma conversa desse tamanho é sinal de laço ou de integração reaproveitando a mesma conversa; se você precisar dela inteira, fale com o suporte antes de montar contorno.

GET /playbooks

Lista completa, sem a definição interna do playbook (perguntas, critérios e instruções não saem pela API). next_cursor é sempre null.

curl -H "Authorization: Bearer $DL" "$API/playbooks"

{
  "data": [
    {
      "id": "b41d7e59-2a68-4f03-8c1d-5e7a9b0c2d34",
      "name": "Qualificação B2B",
      "objective": "meeting",
      "active": true,
      "created_at": "2026-08-14T09:12:31.400Z"
    }
  ],
  "next_cursor": null
}

objective é um de meeting, lead, whatsapp, sale.

Escrita de playbook é substituição inteira. A API pública não grava playbooks — quem grava é o painel, e a rota que ele usa (PUT /api/v1/agent/playbooks/{id}, autenticada pela sessão, não por token) troca a definição completa. Tudo o que você não mandar no corpo é apagado, sem erro nenhum: perguntas, critérios, o link de checkout do playbook e o rótulo do botão de checkout. Se você automatiza esse PUT, monte o corpo a partir da leitura mais recente daquele playbook — nunca de um snapshot guardado antes de uma atualização do produto.

GET /usage

Consumo do mês corrente e limite do plano. Não tem envelope de lista.

curl -H "Authorization: Bearer $DL" "$API/usage"

{
  "month": "2026-09-01",
  "identifications": 37,
  "credits": 44,
  "by_kind": { "reveal": 25, "enrich": 12 },
  "plan": { "id": "pro", "name": "Pro", "identifications_per_month": 1000 }
}

GET /webhooks

Lista completa dos endpoints cadastrados. O segredo de assinatura nunca é devolvido.

curl -H "Authorization: Bearer $DL" "$API/webhooks"

{
  "data": [
    {
      "id": "9a2b6d70-4c15-4e83-b0a9-7f3c2e1d8b46",
      "url": "https://seusistema.com/webhooks/datalead",
      "events": ["lead.created", "lead.qualified"],
      "active": true,
      "description": "ERP interno",
      "last_status": 204,
      "last_delivery_at": "2026-09-05T14:22:09.640Z",
      "failures": 0,
      "created_at": "2026-08-20T17:45:02.117Z"
    }
  ],
  "next_cursor": null
}

GET /openapi.json

Documento OpenAPI 3.1, público e sem token:

curl https://app.datalead.datastone.com.br/api/v1/openapi.json

Veja também

Precisa de ajuda?

Fale com o suporte da Data Stone pelo canal combinado com a sua conta. Tenha à mão a rota chamada, o status recebido e o horário da chamada.