Seguimiento

El seguimiento de ventas es el vínculo entre lo que Clerk muestra a los visitantes y los pedidos que realizan. Sin él, Clerk no puede aprender de las 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 registrado en Clerk pasa por una cadena de tres partes conectadas.

Visitor ID #

Cuando un visitante llega a la tienda online, tu servidor genera un ID de sesión anónima 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 de un visitante —los productos que vio y en los que hizo clic— con el pedido que finalmente realiza.

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

Labels #

Cada llamada a la API que devuelve resultados —búsquedas, recomendaciones, resultados en email— debe incluir un parámetro labels. Este 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 una compra, Clerk utiliza la etiqueta del clic para rastrear la venta hasta el elemento que la generó. Esta es la base de la atribución de ingresos en los análisis.

Las etiquetas que faltan, que 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 simplemente no aparece.

Sale Call #

Cuando el visitante realiza un pedido, una consulta POST a log/sale vincula el pedido al Visitor ID. Ahora Clerk puede conectar toda la cadena: este visitante vio productos 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 de API, debes llamar a log/click cada vez que un visitante hace clic en un producto de Clerk — consulta la guía API para más detalles.

Esta cadena — etiqueta → clic → venta — es la que impulsa tanto la personalización como la analítica de ingresos en my.clerk.io.

Qué Guarda Clerk #

Cada venta registrada contiene:

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

Configuración #

Coloca la llamada de seguimiento de ventas en la página de confirmación del 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 proceso de pago.

API #

Realiza una petición POST a log/sale desde tu servidor cuando se complete un pedido. Pasa el mismo Visitor ID que se utilizó 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 por quantity internamente al calcular los ingresos. No envíes el total de la línea.

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

Clerk.js #

Clerk.js gestiona automáticamente el Visitor ID y realiza la llamada log/sale por ti. Agrega el siguiente fragmento en tu página de confirmación de pedido y reemplaza los valores de ejemplo con 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, utilizando el mismo Visitor ID que ha estado rastreando durante toda la sesión.

Verificando que Funciona #

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

Developers > Logs — Cualquier error de la llamada de seguimiento aparecerá aquí en tiempo real. Este es el lugar más rápido para detectar una solicitud mal configurada.

Data > Orders — Los pedidos registrados confirmados aparecerán aquí. Haz clic en un pedido para ver qué productos fueron registrados y si Clerk puede identificarlos. Si un producto muestra una imagen genérica, el ID del producto en la llamada de venta no coincidió con ningún producto de tu catálogo.

Data > Visitors — Busca un Visitor ID para inspeccionar la sesión completa: qué productos vio, en qué elementos de Clerk hizo clic y qué pedidos realizó. En una configuración Clerk.js, puedes forzar un Visitor ID específico durante las pruebas añadiendo ?clerk_visitor=VISITOR_ID a cualquier URL de la página — Clerk.js usará ese ID para la sesión, facilitando el rastreo de todo el flujo de prueba de principio a fin.

El panel de salud muestra un indicador de estado general para el seguimiento de ventas. Un estado en rojo significa que no se han recibido pedidos registrados recientemente.

Depuración #

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

Revisar Registros #

Ve a Developers > Logs y busca cualquier error del endpoint log/sale. Esto aplica tanto a configuraciones por API como Clerk.js — cualquier solicitud rechazada aparece aquí de inmediato, con un mensaje de error que explica lo que estuvo mal.

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

Verificar Respuesta de la API #

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

{"status": "ok"}

Una fallida devuelve un error con una descripción de lo que salió mal, por ejemplo:

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

Lee el mensaje de error — normalmente indica directamente 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 un payload conocido y válido:

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 funciona pero las llamadas en producción no, compara ambos payloads cuidadosamente — la diferencia revelará el problema.

Configuración Clerk.js: Abre 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í.

Verifica los Parámetros de la Solicitud #

Si los pedidos no se están rastreando 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 que devolvieron resultados anteriormente en esa sesión. Si generas un nuevo ID en cada solicitud o lo almacenas en un lugar que se borra antes del pago, el ID en la llamada de venta no coincidirá con el de los clics.

Labels — Confirma que cada llamada que devolvió resultados anteriormente en la sesión incluyó un array labels con una etiqueta única por cada elemento. Si las etiquetas faltan o son idénticas entre elementos, Clerk registrará la venta pero no podrá atribuirla a un elemento específico.

Product IDs — Verifica que los IDs en el array products coincidan con los IDs que Clerk tiene en su catálogo. Busca uno de los IDs en Data > Products para confirmar. Si no lo encuentras, es probable que estés enviando IDs de variantes o SKUs en lugar de IDs de productos principales.

Sale ID — Confirma que el valor de sale sea único por pedido y que no se reutilice entre solicitudes. Clerk ignora en silencio los IDs de venta duplicados.

No se Realiza la Llamada #

Configuración API: La llamada no se está enviando desde tu servidor. Revisa tu handler de finalización de pedido — confirma que realmente se alcance tras una compra exitosa y que ninguna excepción esté suprimiendo la llamada de seguimiento. Añade registros temporales alrededor de la llamada a log/sale para confirmar que se ejecuta.

Configuración Clerk.js: La librería Clerk.js no se está ejecutando 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á siendo bloqueado por otro script o una herramienta de consentimiento de cookies.

Sin Impacto Clerk #

Si la llamada de venta se realiza con éxito pero no aparece ningún pedido como influenciado por Clerk en los análisis, Clerk registró el pedido pero no pudo vincularlo a una sesión ni atribuirlo a un elemento.

log/click no se está ejecutando — La causa más común. Clerk no puede atribuir la 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 los resultados de Clerk. En una configuración de API, verifica que tu código llame a log/click cada vez que un visitante haga clic en un producto mostrado por Clerk y que la llamada realmente llegue a la API (revisa los registros de tu servidor o la respuesta).

Etiquetas faltantes o no válidas — 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 que se envió en la llamada log/click cuando el visitante hizo clic en el producto. Incluso una pequeña diferencia —un formato distinto, un carácter extra, o un ID regenerado— rompe el vínculo.

Configuración Clerk.js: Los Visitor IDs se gestionan automáticamente, pero el enlace puede romperse si el script de seguimiento falta en una o más páginas del flujo de compra. Verifica que Clerk.js esté cargado en cada página entre la página de producto y la página de confirmación.

Errores Comunes #

Estas son las causas más frecuentes por las que el seguimiento de ventas falla o la atribución no funciona correctamente.

Sintaxis de Producto no Válida #

Los IDs de producto deben enviarse como el mismo tipo usado en tu feed de datos. Si ahí usas enteros, deben ser enteros también en la llamada de venta, no cadenas. 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 todos obligatorios. Omitir cualquiera de ellos devuelve un error. El array 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 ninguna llamada de venta. Dos causas habituales:

• 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. Permite ambos dominios para que el seguimiento no se pierda silenciosamente cuando los visitantes rechazan cookies no esenciales.

IDs de Producto Incorrectos #

Haz el seguimiento del ID de producto principal, no del ID de variante. Si un visitante compra una camiseta roja, talla M, haz el seguimiento del ID principal — no del ID de esa variante específica. El mismo ID debe usarse tanto en el seguimiento de clics como en la llamada de venta. Los IDs no coincidentes rompen la atribución incluso si ambas llamadas tienen éxito.

Cambios en Visitor ID #

En una configuración por API, el Visitor ID debe mantenerse igual desde la primera visualización de página hasta la llamada de venta. Si lo regeneras en cada carga, el clic y la venta se asociarán a sesiones distintas y Clerk no podrá conectarlos.

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

Desajuste en el 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 un total de línea premultiplicado produce cifras de ingresos infladas en los análisis.

IDs de Venta Reutilizados #

Clerk almacena solo la primera llamada para un ID de venta dado. Si la página de confirmación del pedido puede actualizarse o visitarse de nuevo, la llamada de seguimiento se ejecuta de nuevo con el mismo ID de venta. La segunda llamada se ignora silenciosamente.

Usa una bandera en el servidor o un marcador de sesión para asegurar que la llamada de seguimiento se ejecute solo una vez por pedido.

Faltan Datos del Visitante #

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 o perfil de cliente. El pedido aparecerá en Data > Orders pero nunca se mostrará como influenciado por Clerk en los análisis.

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

Desactivando el Seguimiento de Visitantes #

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

En una configuración Clerk.js, indícalo en la configuración así:

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

Las ventas aún se registran cuando el seguimiento de visitantes está desactivado. Clerk recibe los datos del pedido y los incluye en los análisis, pero sin contexto de sesión —sin historial de clics, sin productos visitados, sin atribución a elementos. Clerk solo sabe qué se compró, no cómo llegó ahí el visitante.