# 07 — Engagement (Profil d'engagement)

Routes pour le graphique **"Profil d'engagement"** du tableau de bord SAM. Ces routes retournent les statistiques de fréquence de connexion des apprenants.

**Base URL :** `/api/moodlev5/engagement`

**Authentification requise :** `X-API-Key` (voir [00-introduction.md](00-introduction.md))

---

## POST `/engagement/refresh`

Synchronise les utilisateurs depuis Moodle, puis retourne les stats d'engagement de l'entreprise sélectionnée.

### Requête

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/engagement/refresh" \
  -H "X-API-Key: bubul_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Réponse

```json
{
  "success": true,
  "stats": {
    "active": 38,
    "inactive2": 13,
    "inactive5": 8,
    "inactive10": 5,
    "neverConnected": 5,
    "total": 69
  }
}
```

### Champs `stats`

| Champ | Description |
|-------|-------------|
| `active` | Connectés dans les 7 derniers jours |
| `inactive2` | Connectés il y a 8 à 30 jours |
| `inactive5` | Connectés il y a 31 à 60 jours |
| `inactive10` | Connectés il y a plus de 60 jours |
| `neverConnected` | Jamais connectés |
| `total` | Total des utilisateurs |

---

## GET `/engagement/company`

Retourne les stats d'engagement pour l'entreprise sélectionnée (sans sync Moodle).

### Requête

```bash
curl -X GET "https://votre-domaine.com/api/moodlev5/engagement/company" \
  -H "X-API-Key: bubul_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Réponse

```json
{
  "success": true,
  "stats": {
    "active": 38,
    "inactive2": 13,
    "inactive5": 8,
    "inactive10": 5,
    "neverConnected": 5,
    "total": 69
  },
  "company": "Acme Corp"
}
```

---

## GET `/engagement/user/{id}`

Retourne les stats d'engagement pour un utilisateur spécifique.

### Paramètres

| Paramètre | Type | Description |
|-----------|------|-------------|
| `id` | integer | ID de l'utilisateur SAM |

### Requête

```bash
curl -X GET "https://votre-domaine.com/api/moodlev5/engagement/user/42" \
  -H "X-API-Key: bubul_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Réponse

```json
{
  "success": true,
  "user": "Jean Dupont",
  "lastAccessAt": "2026-03-01",
  "daysSince": 8,
  "status": "inactive2"
}
```

### Valeurs de `status`

| Valeur | Signification |
|--------|---------------|
| `active` | Connecté dans les 7 derniers jours |
| `inactive2` | Connecté il y a 8 à 30 jours |
| `inactive5` | Connecté il y a 31 à 60 jours |
| `inactive10` | Connecté il y a plus de 60 jours |
| `neverConnected` | Jamais connecté |

---

## Codes d'erreur

| Code | Description |
|------|-------------|
| `400` | Aucune entreprise sélectionnée |
| `401` | Clé API manquante ou invalide |
| `404` | Utilisateur introuvable |