API Cadastro de Leads

📌 Visão geral

O POST /lead é um endpoint público (sem necessidade de login) que cadastra um lead (contato) diretamente na base de clientes da Bevean. Ele aceita os mesmos campos do cadastro de cliente da plataforma (nome, e-mail, telefone, documento, endereço, opt-ins e campos personalizados), permite vincular o lead a uma lista (segmento) já existente, e devolve resposta imediata.

O processamento real (deduplicação e gravação) acontece de forma assíncrona, em fila, para suportar alto volume sem travar quem está enviando. O endpoint responde 202 (Aceito) assim que recebe um payload válido — isso confirma que o lead entrou na fila, não que já foi salvo.

URL do endpoint

✅ Quando usar esta opção

Use este endpoint se:

• Você precisa cadastrar leads vindos de um sistema que não tem integração nativa com a Bevean

• Você quer vincular automaticamente o lead a uma lista/segmento específico

• Você precisa enviar campos personalizados (metafields) junto com o cadastro do lead

⚠️ Requisitos importantes

Antes de iniciar, confirme que:

• Você tem uma integração ativa no painel da Bevean (loja, canal de vendas ou uma integração genérica do tipo "site")

• Você tem acesso ao painel para gerar a publicKey

• O corpo da requisição terá pelo menos um entre e-mail, telefone ou documento válido (sem isso, o lead é descartado silenciosamente)

🧭 Etapas do processo

1. Obter a publicKey

1.1. No menu lateral do painel, acesse Integrações e selecione a integração à qual o lead vai pertencer

1.2. Abra a aba Script da integração e clique em Gerar script (se já existir uma chave ativa, ela apenas será exibida novamente)

1.3. Copie o valor de Chave pública usando o botão Copiar chave — esse valor vai no campo publicKey de toda chamada ao /lead

Revogando uma chave: na mesma aba Script, clique em Remover script e confirme. A chave atual é inativada; uma nova pode ser gerada a qualquer momento repetindo o passo 1.2.

A publicKey identifica de qual integração o lead está vindo — não é uma senha de login e não dá acesso a outras informações da conta. Ainda assim, trate-a como uma credencial e evite publicá-la em repositórios de código públicos.

2. Autenticação e formato da chamada

O /lead não usa cabeçalho de autenticação. A identificação de quem está enviando o lead acontece pelo campo publicKey no corpo da requisição.

Exemplo mínimo:

bash

curl -X POST https://tracker.bevean.com/lead \
-H 'Content-Type: application/json' \
-d '{
  "publicKey": "pk_bevean_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "email": "cliente@exemplo.com"
}'

3. Campos disponíveis para cadastro

Todos os campos abaixo, exceto publicKey, são opcionais.

Identificação e contato

Consentimento (opt-in)

Origem e rastreabilidade

Endereço (addresses, lista de objetos)

4. Vincular a uma lista (segmento)

Para adicionar o lead diretamente a uma lista, envie o campo segmentId com o ID da lista:

bash

curl -X POST https://tracker.bevean.com/lead \
-H 'Content-Type: application/json' \
-d '{
  "publicKey": "pk_bevean_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "segmentId": "37e0f821-bfbe-4ec6-8687-1c0dba55289d",
  "name": "Maria Silva",
  "email": "maria@exemplo.com"
}'

Regras importantes:

• A lista precisa já existir e ser do tipo Fixa (manual) — listas Dinâmicas não aceitam vínculo direto

• O vínculo é assíncrono e best-effort: se o segmentId for inválido, de outro tenant, ou de lista dinâmica, o lead ainda assim é cadastrado — só o vínculo falha, sem gerar erro na chamada

• É aditivo (não remove o contato de nenhuma outra lista) e idempotente (se já estiver na lista, nada acontece)

• Se o contato for novo na lista, as automações associadas a ela (ex: boas-vindas) são disparadas normalmente

5. Campos personalizados (metafields)

Envie qualquer campo adicional através do objeto metafields — não é necessário cadastrá-lo antes, a plataforma cria a definição automaticamente:

bash

curl -X POST https://tracker.bevean.com/lead \
-H 'Content-Type: application/json' \
-d '{
  "publicKey": "pk_bevean_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "Rafael Nogueira",
  "email": "rafael@exemplo.com",
  "metafields": {
    "tamanho_calcado": 42,
    "aceita_promocao": true,
    "nivel_fidelidade": "ouro"
  }
}'

Como o tipo é definido (inferido a partir do primeiro valor enviado):

Definindo um rótulo (label) amigável — use o formato expandido:

json

"metafields": {
  "nivel_fidelidade": {
    "value": "ouro",
    "label": "Nível de Fidelidade"
  }
}

Se o lead for reconhecido como contato já existente, os metafields enviados são mesclados com os que o contato já tinha — nenhum valor anterior é apagado, apenas os campos enviados agora são atualizados ou adicionados.

6. Deduplicação

Antes de criar um novo contato, a plataforma verifica se o lead já existe na base do tenant, na seguinte ordem de prioridade:

Reenviar o mesmo lead (ex: retry por erro de rede) não cria duplicidade — apenas atualiza o mesmo contato.

7. Limite de uso (rate limit)

Esse limite é compartilhado com a criação de contatos vindos de outras origens do tracker (eventos de navegação, formulários, carrinho) do mesmo tenant.

8. Exemplo completo

bash

curl -X POST https://tracker.bevean.com/lead \
-H 'Content-Type: application/json' \
-d '{
  "publicKey": "pk_bevean_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "segmentId": "37e0f821-bfbe-4ec6-8687-1c0dba55289d",
  "name": "Ana Beatriz Costa",
  "email": "ana.costa@exemplo.com",
  "phone": "11966665555",
  "document": "12345678901",
  "documentType": "cpf",
  "gender": "female",
  "birthday": "1994-03-21",
  "emailOptinStatus": "subscribed",
  "phoneOptinStatus": "subscribed",
  "source": "landing-black-friday",
  "addresses": [
    {
      "country": "BR",
      "province": "SP",
      "city": "São Paulo",
      "neighborhood": "Centro",
      "address1": "Rua das Flores",
      "number": "123",
      "zip": "01000-000"
    }
  ],
  "metafields": {
    "tamanho_calcado": 37,
    "nivel_fidelidade": { "value": "ouro", "label": "Nível de Fidelidade" }
  }
}'

Resposta de sucesso:

HTTP/1.1 202 Accepted
{ "accepted": 1 }

Resposta de erro (publicKey inválida ou ausente):

HTTP/1.1 422 Unprocessable Entity
{
  "status": 422,
  "error": "Unprocessable Entity",
  "code": "VALIDATION_FAILED",
  "errors": [
    { "field": "publicKey", "message": "O valor é inválido" }
  ]
}

❗ Referência rápida de erros