> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Verificar y depurar eventos de servidor

> Comprueba que tus eventos de conversión de servidor llegan, se atribuyen correctamente y aparecen en los informes, y resuelve los errores más habituales.

## Paso 1: envía un evento de prueba

Envía un único evento de prueba con un `event_id` conocido para poder seguirle la pista:

```bash theme={null}
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 }
  }'
```

Una respuesta correcta tiene este aspecto:

```json theme={null}
{
  "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

Vuelve a enviar la misma petición con el mismo `event_id`:

```bash theme={null}
# 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"
  }'
```

La segunda petición devolverá `200`, pero el evento quedará marcado como duplicado y no contará como conversión. Comprueba que el número de eventos en los informes no ha subido.

***

## Errores habituales y cómo resolverlos

### `401`: falta la clave de API

La petición no lleva la cabecera `X-API-Key`.

```bash theme={null}
# 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

O la clave de API no es válida o está revocada, o el `site_id` del cuerpo no corresponde al sitio al que pertenece la clave. Comprueba que:

* 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

El cuerpo de la petición no pasó la validación del esquema. La respuesta incluye los detalles:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

Causas habituales:

* 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

Estás enviando más de 1000 eventos por minuto y clave de API. Espera y reintenta:

* 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