Como medir o CPL de anúncios por WhatsApp com a API de conversão

CPL é o gasto dividido pelo número de leads. Custo por venda é o gasto dividido pelo número de vendas. Exemplo hipotético, só para a aritmética: R$2.000 de gasto, 160 leads e 8 vendas dão CPL de R$12,50 e custo por venda de R$250. Se o ticket médio for R$700, a receita é R$5.600, e a razão entre receita e gasto é 2,8. Os números são ilustrativos e não representam resultado de cliente.

O CPL sozinho engana: um anúncio com CPL baixo pode trazer curiosos que nunca compram. Por isso o ciclo só fecha quando a venda volta para o sistema de anúncios. Veja também o fluxo de leads de anúncio por cliente e a página de gestores de tráfego.

A referência descreve a operação como registrar a venda de um lead de anúncio. Os campos são phone (obrigatório, com DDI e DDD, por exemplo 5511999998888), event, value e occurred_at. O event aceita Purchase (padrão), Schedule, Lead e QualifiedLead; Purchase marca o lead como ganho, Schedule como agendado e os demais como qualificado. O value aceita número ou texto como "700,50".

O occurred_at registra quando a venda aconteceu e alimenta o seu relatório. O envio à Meta usa o momento do registro, porque a Meta recusa eventos antigos. Por isso o caminho certo é chamar no instante em que o pagamento é confirmado no seu sistema, e não em lote no fim do mês.

# Mark a sale from an ad lead (event is optional, default Purchase)
curl -X POST "https://api.zapzapapi.com/api/v1/INSTANCE_ID/tracking/conversion" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"phone":"5511999998888","event":"Purchase","value":700.50,"occurred_at":"2026-11-10T14:30:00Z"}'

// Node: call it when your payment system confirms, and handle the documented errors
async function markSale(instanceId, phone, value) {
  const res = await fetch("https://api.zapzapapi.com/api/v1/" + instanceId + "/tracking/conversion", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.ZAPZAP_API_KEY,
      "x-api-secret": process.env.ZAPZAP_API_SECRET,
    },
    body: JSON.stringify({ phone, event: "Purchase", value }),
  });
  const body = await res.json().catch(() => ({}));
  if (res.ok) return body;                                   // { ok: true, status: "queued", ... }
  if (res.status === 404 && body.error === "LEAD_NOT_FOUND") return null; // not an ad lead: nothing to attribute
  if (res.status === 409 && body.error === "TRACKING_DISABLED") throw new Error("turn on Meta tracking for this instance");
  throw new Error(body.error + ": " + (body.message || res.status));
}

404 LEAD_NOT_FOUND: esse telefone não veio de um anúncio nesta instância, então não há o que atribuir. Não é falha: trate como venda orgânica e siga. A busca tolera a diferença do nono dígito, mas confira se o número da venda é o mesmo do chat.

409 TRACKING_DISABLED: o traqueamento não está ativo na instância. Ative a configuração de traqueamento no painel antes. 409 EVENT_NOT_ACCEPTED: faltam Pixel e token salvos, ou aquele tipo de evento está desligado. 400 INVALID_PHONE, INVALID_EVENT ou INVALID_VALUE: dado malformado, corrija na origem. O guia de instâncias por cliente ajuda a saber qual instância usar em cada venda.

A referência afirma que chamar duas vezes para a mesma venda não duplica o evento, o que protege de retentativas do seu CRM. Mesmo assim, guarde no seu lado o id da venda e só chame uma vez por pagamento confirmado.

Uma segunda compra do mesmo cliente é outro evento, e deve ser enviada quando acontecer. Não bloqueie recompra no seu sistema: ela é o sinal mais valioso para o algoritmo.

Junte três fontes: gasto (do gerenciador de anúncios), leads (conversas iniciadas por anúncio) e vendas (as chamadas de conversão). A tabela por cliente mostra gasto, leads, CPL, vendas, custo por venda e receita. O portal do cliente mostra leads e vendas com a marca dele, e o relatório em texto é um complemento. Veja automatizar relatórios.

Combine com o cliente quem marca a venda e quando: se a venda fecha por fora do WhatsApp, alguém precisa avisar o sistema. Sem isso, o custo por venda sai maior do que a realidade e o anúncio parece pior do que é. Veja também a API de WhatsApp e a referência.