API de leads: envie, atualize e consulte leads do seu sistema

Os seus leads nascem em outro lugar: no formulário do site, no sistema de pedidos, no CRM que o time já usa. Importar uma planilha toda semana funciona no começo, mas deixa o lead esperando dias pelo primeiro contato. A API de leads do wleads deixa o seu sistema mandar cada lead no momento em que ele surge, e avisar o wleads quando algo muda.

É uma API para quem desenvolve, ou para uma ferramenta de automação que faça requisições HTTP. O wleads não tem integrações prontas com formulários, anúncios ou CRMs: a API é o caminho para ligar o seu sistema às cadências.

O que a API faz

Em todas as rotas, external_id é o id do lead no seu sistema. Você não precisa guardar nenhum id do wleads.

Chaves de API com escopos

Cada chamada leva uma chave de API do workspace no cabeçalho Authorization. A chave pertence a um workspace, e tudo o que ela faz acontece nele: o seu sistema nunca escolhe o workspace, e o lead de outro workspace simplesmente não existe para ela.

Cada chave recebe só os escopos de que precisa. Uma chave pode escrever leads sem poder lê-los, por exemplo, o que limita o estrago se ela vazar. Uma chave pode ser revogada a qualquer momento, e quem a usava perde o acesso.

Criar ou atualizar um lead pelo seu id

A mesma chamada cria o lead, se ele ainda não existe, ou atualiza o que já existe com aquele id. Um exemplo, com dados fictícios:

PUT /api/v1/leads/pedido-4821
Authorization: Bearer SUA_CHAVE_DE_API
Content-Type: application/json

{
  "name": "Mariana Lopes",
  "phone": "+5511XXXXXXXXX",
  "source": "site",
  "consent_basis": "opt_in",
  "attributes": { "produto": "Cozinha planejada" },
  "cadence": "ID_DA_CADENCIA"
}

Algumas regras que evitam surpresas:

• Um campo que você não manda mantém o valor atual. Para atualizar só o telefone, mande só o telefone.
• Os campos personalizados (attributes) são os do seu workspace, os mesmos que as mensagens usam como variáveis. Cada um é atualizado separadamente.
• A cadência é sua escolha. Um lead novo entra na cadência indicada, ou na padrão se você não indicar nenhuma; um lead existente é movido para ela.
• Mandar o mesmo lead de novo não cria duplicado. A resposta diz se o lead foi criado, atualizado ou ficou igual, então repetir uma chamada que falhou é seguro.
• Use um id que não seja dado pessoal. O id do seu sistema continua no wleads mesmo depois de uma eliminação; um número de pedido serve, um e-mail não.

A base legal do contato vai em consent_basis: pediu contato (opt_in), já é cliente (existing_customer), legítimo interesse (legitimate_interest) ou não informada (unknown).

Registrar eventos

Quando algo muda no seu sistema, avise o wleads com um evento:

{ "type": "lost", "reason": "Fechou com outro fornecedor" }

O opted_out coloca o telefone na mesma lista de saída de um pedido de saída feito pelo WhatsApp: nenhuma mensagem sai mais para esse número no workspace, em nenhum lead. Mandar de novo um evento que já foi registrado não duplica nada.

Consultar onde o lead está

A consulta devolve os dados do lead, o estágio em que ele está e o próximo passo: se há um passo de cadência a enviar, se ele respondeu e espera alguém, se está adiado ou se foi encerrado. É assim que o seu sistema sabe, por exemplo, que um lead respondeu e já está com uma pessoa do time.

Apagar dados pessoais (LGPD)

A LGPD dá ao titular o direito de pedir a eliminação dos dados pessoais tratados com o consentimento dele (art. 18, VI, da Lei nº 13.709/2018). Isto não é aconselhamento jurídico: para decidir o seu caso, fale com um advogado ou com o encarregado de dados da empresa.

Quando o pedido chega, uma chamada DELETE apaga os dados pessoais do lead e o texto das mensagens trocadas com ele. Fica só o formato do histórico, como datas e status, e o id do seu sistema. Se a pessoa já tinha pedido para sair, a recusa continua valendo: a lista de saída guarda um hash com chave, nunca o telefone.

O que a API ainda não faz

• Não avisa o seu sistema. Ainda não há webhooks de saída: o wleads não chama o seu sistema quando um lead responde, sai ou é encerrado. Para saber, consulte o lead.
• Não envia mensagens. A API cuida dos leads; quem envia são as cadências, pela fila do dia ou pelo envio automático.
• Não substitui integrações prontas. Não há conectores com formulários, anúncios ou CRMs. Se os seus leads chegam por planilha, a importação de leads por CSV resolve sem código.

Para consultar e trabalhar os leads a partir de um assistente de IA, em vez de código, veja o MCP do wleads.

Perguntas frequentes

Preciso de um desenvolvedor para usar a API?

Sim, ou de uma ferramenta de automação que faça requisições HTTP. A API recebe chamadas com uma chave de acesso e dados em JSON. Se os seus leads estão numa planilha, a importação por CSV resolve sem código.

O que acontece se eu enviar o mesmo lead duas vezes?

Nada é duplicado. O lead é identificado pelo id do seu sistema: a segunda chamada atualiza o que mudou ou não muda nada. A resposta diz se o lead foi criado, atualizado ou ficou igual.

A API avisa o meu sistema quando o lead responde?

Ainda não: o wleads não tem webhooks de saída. O seu sistema pode consultar o lead a qualquer momento e ver o estágio e o próximo passo dele.

Como a API ajuda com a LGPD?

Ela registra a base legal de cada lead, aceita um evento de pedido de saída e apaga os dados pessoais de um lead quando o titular pede. A lista de saída guarda só um hash com chave, nunca o telefone. Isto não é aconselhamento jurídico.

Posso escolher a cadência de cada lead pela API?

Sim. Ao criar ou atualizar o lead, informe a cadência. Um lead novo entra nela, ou na cadência padrão se nenhuma for indicada; um lead existente é movido para ela.

Para ligar o seu sistema às cadências de WhatsApp, crie sua conta no wleads e gere a sua primeira chave de API.