> ## 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.

# Vérifier et déboguer les événements serveur

> Confirmez que vos événements de conversion serveur sont bien reçus, correctement attribués et présents dans les rapports, et corrigez les erreurs courantes.

## Étape 1 : envoyer un événement de test

Envoyez un seul événement de test avec un `event_id` connu, pour pouvoir le suivre :

```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 }
  }'
```

Une réponse correcte ressemble à ceci :

```json theme={null}
{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}
```

## Étape 2 : vérifier qu'il apparaît dans le tableau de bord

1. Ouvrez le tableau de bord Scanova
2. Allez dans **Analyses → Suivi des conversions**
3. Ouvrez le site de suivi
4. Votre `test_event` devrait apparaître en 30–60 secondes

## Étape 3 : tester la déduplication

Renvoyez la même requête avec le même `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 deuxième requête renvoie `200`, mais l'événement est marqué comme doublon et exclu des totaux de conversions. Vérifiez que le nombre d'événements dans les rapports n'a pas augmenté.

***

## Erreurs courantes et corrections

### `401` — Clé d'API manquante

L'en-tête `X-API-Key` est absent de la requête.

```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` — Clé invalide ou site non autorisé

Soit la clé d'API est invalide ou révoquée, soit le `site_id` du corps de la requête ne correspond pas au site auquel la clé appartient. Vérifiez que :

* La clé a été copiée correctement (sans espace ni saut de ligne à la fin)
* Le `site_id` du corps de la requête correspond exactement au site qui a généré la clé
* La clé n'a pas été révoquée dans le tableau de bord

### `422` — Erreur de validation

Le corps de la requête n'a pas passé la validation du schéma. La réponse en donne le détail :

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

Causes fréquentes :

* Un champ obligatoire manque (`site_id`, `event_name` ou `scan_session_id`)
* `scan_session_id` n'est pas un UUID valide
* `conversion_value.currency` n'est pas un code ISO à trois lettres
* L'objet `properties` dépasse 10 Ko
* Une adresse e-mail en clair dans `properties` (utilisez plutôt `user_identifiers.email_hash`)

### `429` — Limite de débit dépassée

Vous envoyez plus de 1 000 événements par minute et par clé d'API. Patientez, puis relancez :

* Consultez l'en-tête `Retry-After` de la réponse
* Utilisez le point de terminaison de lot (`POST /server-events/batch`) pour regrouper plusieurs événements en moins de requêtes

### L'événement est reçu mais n'apparaît pas dans les rapports

* Attendez 60 secondes — le traitement prend un court instant
* Vérifiez que le `site_id` de votre requête correspond au site de suivi que vous consultez dans le tableau de bord
* Vérifiez que le `scan_session_id` est un UUID valide — un format invalide est rejeté avec `422`
* Assurez-vous que le `scan_session_id` envoyé correspond à une vraie session de scan issue d'un QR Code, et non à un UUID de test — les événements dont la session est introuvable ne sont pas attribués et peuvent ne pas apparaître dans les rapports