Verificar y depurar eventos de servidor

​

Paso 1: envía un evento de prueba

curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002",
    "properties": { "test": true }
  }'

{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}

​

Paso 2: comprueba que aparece en el panel

1. Abre el panel de Scanova
2. Ve a Análisis → Seguimiento de conversiones
3. Abre el sitio de seguimiento
4. Tu test_event debería aparecer en 30–60 segundos

​

Paso 3: prueba la deduplicación

# Same request again
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002"
  }'

​

Errores habituales y cómo resolverlos

​

401: falta la clave de API

# Wrong — missing header
curl -X POST "https://track.scanova.io/server-events" -d '{...}'

# Correct
curl -X POST "https://track.scanova.io/server-events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{...}'

​

403: clave no válida o sitio no autorizado

• La clave se copió correctamente (sin espacios ni saltos de línea al final)
• El site_id del cuerpo de la petición coincide exactamente con el sitio que generó la clave
• La clave no se ha revocado en el panel

​

422: error de validación

{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• Falta un campo obligatorio (site_id, event_name o scan_session_id)
• scan_session_id no tiene un formato UUID válido
• conversion_value.currency no es un código ISO de tres letras
• El objeto properties supera los 10 KB
• Una dirección de correo en texto plano dentro de properties (usa user_identifiers.email_hash en su lugar)

​

429: límite de frecuencia superado

• Consulta la cabecera Retry-After de la respuesta
• Usa el endpoint de lotes (POST /server-events/batch) para agrupar varios eventos en menos peticiones

​

El evento se entrega pero no aparece en los informes

• Espera 60 segundos: hay un pequeño retardo de procesamiento
• Comprueba que el site_id del cuerpo corresponde al sitio de seguimiento que estás viendo en el panel
• Comprueba que el scan_session_id es un UUID válido: un formato no válido se rechaza con 422
• Asegúrate de que el scan_session_id que enviaste corresponde a una sesión de escaneo real de un código QR y no a un UUID de prueba: los eventos cuya sesión no se puede resolver no se atribuyen y puede que no aparezcan en los informes