Cómo medir el CPL de anuncios por WhatsApp con la API de conversión

CPL es el gasto dividido por el número de leads. Costo por venta es el gasto dividido por el número de ventas. Ejemplo hipotético, solo para la aritmética: R$2.000 de gasto, 160 leads y 8 ventas dan un CPL de R$12,50 y un costo por venta de R$250. Si el ticket promedio fuera R$700, el ingreso es R$5.600 y la razón entre ingreso y gasto es 2,8. Los números son ilustrativos y no representan el resultado de ningún cliente.

El CPL solo engaña: un anuncio con CPL bajo puede traer curiosos que nunca compran. Por eso el ciclo solo se cierra cuando la venta vuelve al sistema de anuncios. Mira también el flujo de leads de anuncios por cliente y la página de gestores de tráfico.

La referencia describe la operación como registrar la venta de un lead de anuncio. Los campos son phone (obligatorio, con código de país y de área, por ejemplo 5511999998888), event, value y occurred_at. El event acepta Purchase (por defecto), Schedule, Lead y QualifiedLead; Purchase marca el lead como ganado, Schedule como agendado y los demás como calificado. El value acepta número o texto como "700,50".

occurred_at registra cuándo ocurrió la venta y alimenta tu reporte. El envío a Meta usa el momento del registro, porque Meta rechaza eventos antiguos. Por eso el camino correcto es llamar en el instante en que el pago se confirma en tu sistema, y no en lote a fin de mes.

# 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: ese teléfono no vino de un anuncio en esta instancia, así que no hay qué atribuir. No es una falla: trátalo como venta orgánica y sigue. La búsqueda tolera la diferencia del noveno dígito, pero verifica que el número de la venta sea el mismo del chat.

409 TRACKING_DISABLED: el seguimiento no está activo en la instancia. Activa la configuración de seguimiento en el panel antes. 409 EVENT_NOT_ACCEPTED: faltan el Pixel y el token guardados, o ese tipo de evento está apagado. 400 INVALID_PHONE, INVALID_EVENT o INVALID_VALUE: dato mal formado, corrígelo en el origen. La guía de instancias por cliente ayuda a saber qué instancia usar en cada venta.

La referencia afirma que llamar dos veces por la misma venta no duplica el evento, lo que te protege de reintentos de tu CRM. Aun así, guarda de tu lado el id de la venta y llama una sola vez por pago confirmado.

Una segunda compra del mismo cliente es otro evento, y debe enviarse cuando ocurra. No bloquees la recompra en tu sistema: es la señal más valiosa para el algoritmo.

Une tres fuentes: gasto (del administrador de anuncios), leads (conversaciones iniciadas por anuncio) y ventas (las llamadas de conversión). La tabla por cliente muestra gasto, leads, CPL, ventas, costo por venta e ingreso. El portal del cliente muestra leads y ventas con su marca, y el reporte en texto es un complemento. Mira automatizar reportes.

Acuerda con el cliente quién marca la venta y cuándo: si la venta se cierra fuera de WhatsApp, alguien debe avisar al sistema. Sin eso, el costo por venta sale mayor que la realidad y el anuncio parece peor de lo que es. Mira también la API de WhatsApp y la referencia.