API de eventos

A API de eventos é o caminho para quem programa: o seu sistema avisa o Leadz de um cadastro, uma compra ou um cancelamento, e o Leadz cria ou atualiza o contato. Diferente do webhook, aqui não há mapeamento de campos. O formato é fixo, com uma lista fechada de tipos de evento, e cada chamada leva uma chave.

Esta página é técnica. Se você não programa, use um webhook de entrada.

#Antes de começar

• A API precisa estar no seu plano. Sem ela, a tela mostra «API não ativa no seu plano».
• Seu cargo precisa ter acesso a Configurações e a Integrações no workspace (a conta da sua empresa dentro do Leadz).

#Gerar a chave

O que saber sobre a chave:

• Ela é sua e vale só para o workspace em que foi gerada. Cada usuário tem a própria.
• Regenerar token cria uma chave nova e invalida a anterior na hora.
• A tela mostra só o começo da chave e a data do último uso.
• Nunca coloque a chave em código que roda no navegador nem em repositório público.

#Endereço

O endereço completo aparece na tela, no campo Endpoint. Use sempre o que a tela mostrar. O caminho termina assim:

POST https://SEU-ENDERECO/api/v1/events

A lista de eventos em JSON, sem precisar de chave:

GET https://SEU-ENDERECO/api/v1/events/catalog

#Autenticação

Envie a chave no cabeçalho Authorization:

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

#Corpo da requisição

Campos de contact:

#Como o contato é encontrado

O Leadz procura um contato existente pelo e-mail, pelo telefone ou pelo data.external_id (o identificador da pessoa no seu sistema). Achou, atualiza. Não achou, cria, desde que o evento traga contact.firstName.

Nos eventos que criam contato (user.created, lead.created), contact.firstName é obrigatório. Nos demais, envie pelo menos contact.email, contact.phone ou data.external_id.

#Eventos aceitos

A lista completa, com os campos de cada evento, fica na tela, em Eventos disponíveis. Cada item abre um exemplo de JSON.

A tela lista também os eventos lead.group_*, lead.dm_1x1 e tracker.custom. Eles são usados pela ligação com o Sparkle Tracker e não aplicam tags.

Todo evento aceito aparece no histórico da ficha do contato.

#Registrar a negociação de uma compra

O evento de compra só grava uma negociação no contato quando você diz a situação dela em data.negotiation_status:

A negociação é identificada por data.negotiation_key ou, se ele não vier, por data.order_id. Envie a mesma chave no checkout (open) e na compra (won) para que os dois eventos sejam a mesma negociação. Sem negotiation_status, o evento atualiza o contato e o histórico, mas não cria negociação.

#Exemplo em cURL

curl -X POST "https://SEU-ENDERECO/api/v1/events" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase.completed",
    "event_id": "pedido_9988_aprovado",
    "contact": {
      "firstName": "Ana",
      "email": "ana@exemplo.com",
      "phone": "5511999990000"
    },
    "data": {
      "order_id": "pedido_9988",
      "amount": 197.0,
      "currency": "BRL",
      "product_name": "Curso Exemplo",
      "negotiation_status": "won"
    }
  }'

#Respostas

Evento aceito, com o código 202:

{
  "ok": true,
  "id": "identificador-do-evento",
  "type": "purchase.completed",
  "outcome": "processed",
  "message": "Evento aceite",
  "contact_id": null,
  "contact_display_id": null,
  "request_id": "identificador-da-requisicao"
}

O 202 quer dizer que o evento foi recebido. O contato é criado ou atualizado logo em seguida, em segundo plano. Por isso contact_id volta vazio.

Quando o event_id já foi recebido, a resposta é 200 com "outcome": "duplicate" e nada é processado de novo.

Os erros têm este formato:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token API inválido",
    "request_id": "identificador-da-requisicao"
  }
}

Guarde o request_id das respostas de erro. Ele ajuda o suporte a encontrar a chamada.

#Limites

• Por dia. O total de eventos por dia depende do seu plano. A tela mostra o consumo em Uso hoje. Ao passar do limite, a resposta é 429 com «Limite diário da API atingido».
• Por minuto. Cada chave tem um limite de chamadas por minuto. Ao passar, a resposta é 429 com «Limite de requisições da API excedido. Aguarde um minuto e tente de novo.»
• Sem chave válida. Chamadas sem chave, ou com chave fora do formato, ficam limitadas a 120 por minuto por origem.
• Chave recusada. Uma chave recusada recebe 401 direto por até 5 minutos, antes de ser conferida de novo. Não adianta insistir com a mesma chave nesse intervalo.
• Tamanho. O corpo pode ter até 1 MB.
• Histórico. O Leadz guarda os 200 eventos mais recentes de cada workspace. A proteção contra event_id repetido vale enquanto o evento estiver guardado.

#Usar os eventos em um funil

Um evento enviado pela API pode iniciar um funil pelo gatilho Evento do Sparkle Tracker, o mesmo usado pela ligação com o Tracker. No campo Evento do Tracker, escolha Compra concluída, Reembolso ou Qualquer evento do Tracker. O gatilho aparece no editor quando o Tracker está conectado ou quando você tem uma chave gerada.

#Problemas comuns

A resposta é 401 com «Token API inválido»

A chave está errada, incompleta ou é de outro workspace. Confira se o cabeçalho está no formato Authorization: Bearer SEU_TOKEN, sem aspas nem espaços sobrando.

A resposta é 401 dizendo que a chave foi revogada

Alguém clicou em Regenerar token, e a chave antiga parou de valer. Atualize o seu sistema com a chave nova.

A resposta é 400 com «Campos obrigatórios ausentes»

A mensagem lista os campos que faltam, como contact.firstName ou data.order_id. Compare o seu corpo com o exemplo do evento em Eventos disponíveis.

O evento deu 202, mas o contato não apareceu

O evento foi aceito, mas não trouxe como identificar a pessoa. Em eventos que não criam contato, como tag.applied, o contato precisa existir antes. Confira o e-mail e o telefone enviados.

A compra chegou, mas não criou negociação

Faltou data.negotiation_status. Envie "won" para compra concluída.

O mesmo evento aparece duas vezes no histórico do contato

Faltou o event_id. Envie sempre um identificador único por evento, igual nas tentativas de reenvio. Assim o reenvio volta como duplicate e não é processado de novo.

#Veja também

• Webhooks de entrada
• Sparkle Tracker
• Webhook de saída