Seguimiento de ventas

El seguimiento de ventas es el vínculo entre lo que Clerk muestra a los visitantes y los pedidos que realizan. Sin esto, Clerk no puede aprender de compras reales, personalizar recomendaciones ni mostrar una atribución de ingresos precisa en el panel de control.

Este artículo explica cómo funciona el seguimiento a nivel de API, cómo configurarlo y cómo depurarlo cuando los pedidos no se registran correctamente.

Cómo Funciona #

Cada pedido rastreado en Clerk pasa por una cadena de tres componentes conectados.

Visitor ID #

Cuando un visitante llega a la tienda online, tu servidor genera un ID de sesión anónimo y lo incluye en cada llamada a la API realizada durante esa sesión. Esto es lo que permite a Clerk conectar la actividad de navegación del visitante —los productos que vio y en los que hizo clic— con el pedido que finalmente realiza.

En una configuración de Clerk.js, el Visitor ID se genera y gestiona automáticamente. En una configuración directa de API, eres responsable de crearlo, almacenarlo (por ejemplo, en una variable de sesión) y pasarla de manera consistente en todas las llamadas.

Labels #

Cada llamada a la API que devuelve resultados —coincidencias de búsqueda, recomendaciones, resultados de Email— debe incluir un parámetro labels. Esto es un array que contiene al menos una cadena descriptiva, como ["Homepage - Trending"] o ["Search - Predictive"], que identifica qué elemento mostró esos productos.

Cuando un visitante hace clic en un producto y luego realiza un pedido, Clerk usa la etiqueta del clic para rastrear la venta hasta el elemento que la originó. Esto es la base para la atribución de ingresos en la analítica.

Las etiquetas que faltan, son idénticas en todos los elementos o demasiado genéricas hacen imposible que Clerk distinga qué elemento influyó en una venta. Esta es una de las razones más comunes por las que la atribución parece incorrecta o falta por completo.

Sale Call #

Cuando el visitante realiza un pedido, una solicitud POST a log/sale vincula el pedido al Visitor ID. Clerk ahora puede conectar toda la cadena: este visitante vio productos mostrados por el elemento X (la etiqueta), hizo clic en uno y completó una compra.

Para que esta cadena funcione, cada clic en un producto mostrado por Clerk también debe registrarse a través de log/click. En una configuración con Clerk.js, esto ocurre automáticamente. En una configuración API, debes llamar a log/click cada vez que un visitante haga clic en un producto de Clerk — consulta la guía de API para más detalles.

Esta cadena — label → click → sale — es lo que impulsa tanto la personalización como la analítica de ingresos en my.clerk.io.

Qué Guarda Clerk #

Cada venta rastreada contiene:

• Un ID de venta único
• IDs de productos, cantidades y precios unitarios
• El Visitor ID (vincula la venta a su sesión)
• Email del cliente e ID del cliente — opcional, permite personalización entre sesiones

Configuración #

Coloca la llamada de seguimiento de ventas en la página de confirmación de pedido, que se carga una vez después de una compra exitosa. No la coloques en la página del carrito ni en ningún otro punto del flujo de compra.

API #

Haz una solicitud POST a log/sale desde tu servidor cuando se complete un pedido. Pasa el mismo Visitor ID que se usó durante toda la sesión.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 567,
    "products": [
      {"id": 12793, "price": 99.95, "quantity": 2},
      {"id": 1546, "price": 14.00, "quantity": 1}
    ],
    "email": "luke@skywalker.com",
    "customer": 1234,
    "visitor": "abc123"
  }' \
  https://api.clerk.io/v2/log/sale

price es siempre el precio unitario de un solo artículo. Clerk lo multiplica internamente por quantity al calcular los ingresos. No envíes el total de la línea.

Consulta la guía de API para todos los detalles sobre cómo generar y mantener el Visitor ID a lo largo de una sesión.

Clerk.js #

Clerk.js gestiona el Visitor ID automáticamente y realiza la llamada a log/sale por ti. Añade el siguiente fragmento en tu página de confirmación de pedido y reemplaza los valores de ejemplo por las variables de tu plataforma:

<span
  class="clerk"
  data-api="log/sale"
  data-sale="ORDER_ID"
  data-email="CUSTOMER_EMAIL"
  data-customer="CUSTOMER_ID"
  data-products='[{"id": 12, "quantity": 1, "price": 99.95}, {"id": 54, "quantity": 2, "price": 9.50}]'>
</span>

Clerk.js detecta el fragmento al cargar la página y envía los datos de la venta a la API, usando el mismo Visitor ID que ha estado rastreando durante la sesión.

Verificando Que Funciona #

Revisa estos tres lugares después de realizar un pedido de prueba.

Developers > Logs — Aquí aparecen en tiempo real los errores de la llamada de tracking. Este es el lugar más rápido para detectar una solicitud mal configurada.

Data > Orders — Los pedidos rastreados confirmados aparecen aquí. Haz clic en un pedido para ver qué productos se rastrearon y si Clerk puede identificarlos. Si un producto muestra una imagen de marcador de posición, el ID de producto en la llamada de venta no coincide con ningún producto de tu catálogo.

Data > Visitors — Busca un Visitor ID para inspeccionar su sesión completa: qué productos vieron, en qué elementos de Clerk hicieron clic y qué pedidos realizaron. En una configuración de Clerk.js, puedes forzar un Visitor ID específico durante las pruebas agregando ?clerk_visitor=VISITOR_ID a cualquier URL — Clerk.js usará ese ID para la sesión, facilitando el seguimiento completo de una prueba de extremo a extremo.

El panel de control de Health muestra un indicador de estado de alto nivel para el seguimiento de ventas. Un estado en rojo significa que no se han recibido pedidos rastreados recientemente.

Depuración #

Sigue estos pasos cuando las ventas no se estén rastreando correctamente.

Comprobar los Logs #

Ve a Developers > Logs y busca errores provenientes del endpoint log/sale. Esto aplica tanto a configuraciones API como Clerk.js — cualquier solicitud rechazada aparece aquí inmediatamente con un mensaje de error que explica el motivo.

Para configuraciones con Clerk.js, también ejecuta Clerk("debug") en la consola del navegador antes de hacer un pedido de prueba. Esto activa el modo de depuración, lo que hace que Clerk.js registre información detallada sobre cada llamada de seguimiento que realiza — incluyendo el Visitor ID usado, las etiquetas adjuntadas a las llamadas de resultados y cualquier error encontrado. Busca entradas que comiencen con [Clerk] en la salida de la consola.

Verificar Respuesta de API #

El endpoint log/sale siempre devuelve una respuesta. Una respuesta exitosa se ve así:

{"status": "ok"}

Una fallida devuelve un error con la descripción del problema, por ejemplo:

{"status": "error", "error": "Missing required argument: sale"}

Lee el mensaje de error — por lo general, indica exactamente cuál es el problema.

Configuración API: Registra la respuesta HTTP sin procesar de la llamada a log/sale en tu código del lado del servidor. Si aún no lo haces, prueba la llamada directamente con una carga útil conocida y válida:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 999,
    "products": [{"id": 12793, "price": 99.95, "quantity": 1}],
    "visitor": "test-visitor-1"
  }' \
  https://api.clerk.io/v2/log/sale

Si esto tiene éxito pero las llamadas en producción no, compara ambas cargas útiles detalladamente — la diferencia revelará el problema.

Configuración Clerk.js: Abre las DevTools del navegador, ve a la pestaña Network y filtra por clerk. Realiza un pedido de prueba y busca una solicitud que comience con sale?key=.... Haz clic en ella e inspecciona la respuesta allí.

Verificar Parámetros de Solicitud #

Si los pedidos no se rastrean o no se atribuyen correctamente, verifica lo siguiente en tu configuración:

API key — Confirma que key coincida con la Public API Key encontrada en Developers > API Keys. Una clave incorrecta devuelve un error de autenticación de inmediato.

Visitor ID — Verifica que visitor esté presente y que sea el mismo valor utilizado en las llamadas de resultados anteriores durante esa sesión. Si generas un ID nuevo en cada solicitud, o se almacena en algún lugar que se borra antes del checkout, el ID en la llamada de venta no coincidirá con el adjuntado a los clics.

Labels — Confirma que cada llamada que antes devolvía resultados en la sesión incluyó un array labels con una etiqueta única para cada elemento. Si las etiquetas faltan o son idénticas en todos los elementos, Clerk registra la venta pero no puede atribuirla a ningún elemento específico.

Product IDs — Verifica que los IDs en el array products coincidan con los que Clerk tiene en su catálogo. Busca uno de los IDs en Data > Products para confirmarlo. Si no puedes encontrarlo, probablemente estés enviando IDs de variantes o SKUs en lugar de los IDs de producto principal.

Sale ID — Confirma que el valor de sale sea único por pedido y no se reutiliza en varias solicitudes. Clerk ignora silenciosamente los Sale IDs duplicados.

No Se Hace La Llamada #

Configuración API: La llamada no se está ejecutando desde tu servidor. Revisa tu manejador de finalización de pedido — confirma que realmente se está alcanzando después de una compra exitosa y que ninguna excepción esté suprimiendo silenciosamente la llamada de seguimiento. Agrega registros temporales alrededor de la llamada a log/sale para confirmar que se ejecuta.

Configuración Clerk.js: La librería Clerk.js no está en ejecución en la página de confirmación. Abre la consola del navegador y escribe Clerk. Si ves el siguiente error, la librería no se cargó:

Uncaught ReferenceError: Clerk is not defined

Confirma que el script de seguimiento de Clerk.js esté presente en la plantilla de la página de confirmación y que no esté bloqueado por otro script o por una herramienta de consentimiento de cookies.

Sin Impacto de Clerk #

Si la llamada de venta tiene éxito pero no aparecen pedidos como influenciados por Clerk en la analítica, Clerk registró el pedido pero no pudo conectarlo a una sesión ni atribuirlo a un elemento.

No se está llamando a log/click — Es la causa más común. Clerk no puede atribuir una venta a un elemento a menos que se haya registrado un clic antes de la compra. En una configuración con Clerk.js, el seguimiento de clics es automático — confirma que la librería esté cargada en las páginas donde se muestran resultados de Clerk. En una configuración API, verifica que tu código llama a log/click cada vez que un visitante haga clic en un producto de Clerk, y que la llamada realmente llegue a la API (revisa los registros de tu servidor o la respuesta).

Labels faltantes o inválidos — Verifica que cada llamada que devuelve resultados y cada llamada a log/click incluya un array labels válido. Si las etiquetas faltan, están vacías o contienen solo espacios en blanco, Clerk no puede determinar con qué elemento interactuó el visitante y la venta no será atribuida.

Configuración API: Confirma que el Visitor ID en la llamada a log/sale coincida exactamente con el usado en la llamada a log/click cuando el visitante hizo clic en el producto. Incluso una pequeña diferencia — formato distinto, un carácter extra o un ID regenerado — rompe la vinculación.

Configuración Clerk.js: Los Visitor IDs se manejan automáticamente, pero el vínculo puede romperse si el script de seguimiento falta en una o más páginas del flujo de compra. Revisa que Clerk.js se cargue en cada página desde la de producto hasta la de confirmación.

Errores Comunes #

Estas son las causas más frecuentes de fallos en el seguimiento de ventas o atribución incorrecta.

Sintaxis de Producto Inválida #

Los Product IDs deben enviarse del mismo tipo que se utiliza en tu feed de datos. Si ahí usas enteros, deben ser enteros también en la llamada de venta — no cadenas de texto. Enviar "id": "123" cuando Clerk espera "id": 123 hace que la llamada falle.

El valor de products también debe ser JSON válido. Cadenas escapadas o doblemente codificadas como "products": "[{\"id\":\"123\"}]" no se analizarán correctamente.

Argumentos Faltantes #

Los argumentos key, sale y products son obligatorios. Omitir cualquiera de ellos genera un error. El array de products debe contener al menos un elemento.

Clerk.js No Cargado #

Si la librería Clerk.js falta en la página de confirmación, o está bloqueada, no se realiza la llamada de venta. Dos causas comunes:

• El script de seguimiento no está incluido en la plantilla de la página de confirmación.
• Una herramienta de consentimiento de cookies (como iubenda en modo de bloqueo automático) está bloqueando cdn.clerk.io o api.clerk.io. Añade ambos dominios a la lista permitida para que el seguimiento no se pierda silenciosamente cuando los visitantes rechacen cookies no esenciales.

Product IDs Incorrectos #

Rastrea el ID de producto principal, no el ID de variante. Si un visitante compra una camiseta roja talla M, rastrea el ID principal — no el de esa variante específica. El mismo ID debe usarse tanto en el seguimiento de clics como en la llamada de venta. IDs no coincidentes rompen la atribución incluso cuando ambas llamadas son exitosas.

Cambios en Visitor ID #

En una configuración API, el Visitor ID debe permanecer igual desde la primera vista de página hasta la llamada de venta. Si regeneras el ID en cada carga de página, el clic y la venta se asocian a sesiones diferentes y Clerk no puede conectarlos.

En una configuración Clerk.js esto se gestiona automáticamente, pero puede romperse si falta el script de seguimiento en una o más páginas del flujo de compra.

Incongruencia en Precio Unitario #

price en el array products debe ser el precio unitario de un solo artículo. Clerk lo multiplica por quantity para calcular los ingresos. Enviar el total de línea premultiplicado produce cifras de ingresos infladas en analítica.

Sale IDs Reutilizados #

Clerk guarda solo la primera llamada para un Sale ID dado. Si la página de confirmación puede recargarse o visitarse varias veces, la llamada de seguimiento se ejecuta de nuevo con el mismo Sale ID. La segunda llamada se ignora silenciosamente.

Utiliza un indicador del lado del servidor o una marca de sesión para asegurarte de que la llamada de seguimiento solo se ejecute una vez por pedido.

Datos de Visitante Faltantes #

Si ni visitor ni email están incluidos en la llamada de venta, Clerk registra el pedido pero no puede vincularlo a una sesión ni a un perfil de cliente. El pedido aparece en Data > Orders pero nunca se muestra como influenciado por Clerk en analítica.

Incluye siempre el parámetro visitor. Añadir email y customer cuando estén disponibles también mejora la personalización en sesiones futuras de ese cliente.

Desactivar Seguimiento de Visitantes #

Para dejar de rastrear a un visitante específico — por ejemplo, cuando ha rechazado todo seguimiento mediante un banner de consentimiento de cookies — pasa "visitor": null en todas las llamadas API de esa sesión. Clerk procesa las peticiones normalmente pero no registra ninguna actividad asociada a un perfil de visitante.

En una configuración Clerk.js, configúralo así:

Clerk('config', {
  key: 'YOUR_API_KEY',
  visitor: null
});

Las ventas siguen registrándose cuando el seguimiento de visitantes está desactivado. Clerk recibe los datos del pedido e incluye la venta en la analítica, pero sin ningún contexto de sesión — sin historial de clics, sin productos navegados, sin atribución de elemento. Clerk solo sabe qué se compró, no cómo llegó el visitante ahí.