Endpoint - Tracking

Para que el aprendizaje IA y las metricas del panel funcionen, Mibizum necesita saber que paso despues de cada busqueda: si el cliente hizo click en un resultado, si convirtio (compro), o si abandono. Estos eventos los reporta el frontend con el endpoint de tracking.

TIP

Si usas el widget oficial o el SDK JS, el tracking se hace por ti. Solo necesitas estos endpoints si construyes una UI de busqueda 100% a medida.

POST /v1/{tenant}/track/search

Registra una busqueda visible para el cliente (lo que se mostro en el overlay o en la pagina de resultados).

curl -X POST https://api.mibizum.io/v1/tu-tienda/track/search \
  -H "Authorization: Bearer mb_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "uuid-v4-del-cliente",
    "query": "hidratante",
    "results_count": 12,
    "channel": "overlay"
  }'

Campos

Campo	Tipo	Descripcion
session_id	uuid	Identificador opaco de la sesion (el SDK lo genera y guarda en localStorage)
query	string	El termino que vio el cliente (no el query_norm)
results_count	int	Numero de resultados que se le mostraron
channel	enum	overlay / results_page
accept_language	string	(opcional) Idioma del navegador del cliente

POST /v1/{tenant}/track/click

Registra un click sobre un resultado. Alimenta el patron de "clicks reiterados" (ver /sugerencias en el panel).

curl -X POST https://api.mibizum.io/v1/tu-tienda/track/click \
  -H "Authorization: Bearer mb_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "uuid-v4-del-cliente",
    "query": "hidratante",
    "item_id": "sku-001",
    "position": 1
  }'

POST /v1/{tenant}/track/conversion

Registra una compra que vino de una busqueda. Es la senal mas valiosa: la usa el ranking para boost de productos que convierten.

curl -X POST https://api.mibizum.io/v1/tu-tienda/track/conversion \
  -H "Authorization: Bearer mb_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "uuid-v4-del-cliente",
    "item_id": "sku-001",
    "order_id": "tu-order-123",
    "revenue": 24.90,
    "currency": "EUR"
  }'

Privacidad y consentimiento

Mibizum no usa cookies de tracking. El session_id lo genera el SDK y vive en localStorage con TTL de 24h. Las IPs se hashean con un salt por tenant antes de almacenarse y solo se usan para metricas agregadas (no para identificar individuos).

Para cumplir con GDPR, el merchant debe:

• Incluir el localStorage del SDK en su politica de cookies/almacenamiento.
• Si el cliente rechaza, no llamar al SDK. El widget detecta la ausencia y degrada elegantemente a busqueda sin tracking.

Ver Aviso de privacidad para el detalle legal.