API pública — tokens, autenticação e limites

A API pública do Data Lead deixa você ler leads, conversas, playbooks, uso e webhooks de fora do painel — de um ERP, de uma automação ou de um relatório próprio.

Endereço base:

https://app.datalead.datastone.com.br/api/v1

Criar um token

Os tokens ficam na tela Configurações, no menu lateral, grupo Conta (endereço /configuracoes), na seção Tokens da API. Só o dono e os administradores da conta criam e revogam tokens.

1. Preencha Nome do token (ex.: Integração com o ERP), até 80 caracteres.
2. Escolha as Permissões: Somente leitura (padrão) ou Leitura e escrita.
3. Clique em Gerar token.

O token aparece uma única vez:

Copie agora: este token não será exibido de novo.

Ele começa com dl_. O Data Lead guarda apenas um resumo criptográfico — se você perder o token, gere outro e revogue o antigo. Guarde-o num cofre de segredos.

Há um teto de 20 tokens ativos por conta; ao atingi-lo a criação é recusada com "Você já tem 20 tokens ativos. Revogue um antes de criar outro." Tokens revogados não ocupam vaga.

Autenticar

Envie o token no cabeçalho Authorization:

curl -H "Authorization: Bearer dl_SEU_TOKEN" \
  https://app.datalead.datastone.com.br/api/v1/leads

Cada token pertence a uma conta e enxerga apenas os dados dela.

API servidor-a-servidor: não a chame do navegador. As respostas não trazem cabeçalhos de CORS, de propósito — um token de portador com acesso de leitura à conta inteira não tem lugar numa página web. Se precisar consumi-la no navegador, faça um proxy no seu servidor.

Escopos

PATCH /leads/{id} é a única escrita da API. Um token de leitura recebe 403 nela.

O escopo não muda depois da criação. Para trocar, gere outro token e revogue o antigo. A lista mostra o selo de cada token (Somente leitura ou Leitura e escrita) — depois de criado, é a única forma de saber se aquele token pode alterar leads.

Validade

Tokens criados pela tela não expiram. A expiração existe no produto, mas hoje nenhum token nasce com data-limite pela interface. Um token vencido é recusado exatamente como um revogado, com o mesmo 401 — dizer "expirou" confirmaria a quem tem o token na mão que ele um dia valeu.

Revogar

Na lista, clique em Revogar. A confirmação é explícita:

Quem usa <nome do token> perde o acesso à API na hora, e não há como reativá-lo. Gere um token novo antes de revogar se a integração precisa continuar funcionando.

A linha continua na lista com o selo Revogado: o histórico de "este token existiu e foi usado até tal dia" é justamente o que se olha depois de um vazamento. A coluna Último uso ajuda a decidir o que pode ser revogado com segurança.

Limite de requisições

O teto por IP é mais folgado porque uma conta pode ter vários tokens saindo do mesmo servidor.

Ao estourar qualquer um dos dois, a resposta é 429 com o cabeçalho retry-after dizendo quantos segundos esperar:

{ "error": "Muitas requisições. Tente de novo em instantes." }

Paginação por cursor

As listagens devolvem sempre o mesmo envelope:

{ "data": [], "next_cursor": null }

Repita a chamada com ?cursor=<valor recebido> até next_cursor vir null:

curl -H "Authorization: Bearer dl_SEU_TOKEN" \
  "https://app.datalead.datastone.com.br/api/v1/leads?limit=100&cursor=MjAyNi0wOS0wNVQxMjowMDowMC4wMDBafDVmMWM4YjBlLTlkMmEtNGExMS05YTBlLTJjNmQxZjNiN2U0MA"

• ?limit= vai de 1 a 200 (padrão 50).
• O cursor é opaco: devolva o valor recebido, sem tentar interpretá-lo ou montar um à mão.
• Um cursor ilegível devolve 400 ({"error":"Cursor inválido"}), nunca a primeira página de novo — repetir a página 1 em silêncio faria um cliente paginando em laço reprocessar os mesmos registros para sempre.

A paginação é por chave, não por deslocamento: um lead novo criado durante a varredura não faz você pular linhas.

Contatos mascarados

E-mail e telefone vêm mascarados, como na tabela de leads do painel:

A regra também vale para o texto das mensagens em GET /conversations/{id}.

Quando o lead simplesmente não tem e-mail ou telefone, o campo vem null — nunca um travessão. Máscara quer dizer "existe, escondido"; null quer dizer "não existe".

Para o contato completo, use a exportação em CSV da tela de Leads, que exige sessão e é autenticada por pessoa.

Especificação OpenAPI

O documento OpenAPI 3.1 é público e não exige token:

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

Na tela de Configurações, o link Baixar a especificação OpenAPI (JSON) faz a mesma coisa. Cole o arquivo no Swagger UI, no Postman ou no gerador de cliente que preferir.

Veja também

• Endpoints da API
• Códigos de erro da API
• Webhooks
• Configurações da conta

Precisa de ajuda?

Fale com o suporte da Data Stone pelo canal combinado com a sua conta. Tenha à mão o início do token (os 12 primeiros caracteres, exibidos na lista) e o horário da chamada — nunca envie o token inteiro.