# API SAM - Utilisateurs (Stagiaires)

[← Introduction](00-introduction.md) | [Accueil](README.md) | [Cohortes →](02-cohorts.md)

---

Gestion des stagiaires Moodle.

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

---

## Endpoints

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | `/users` | Liste des stagiaires |
| GET | `/users/{moodle_id}` | Détail d'un stagiaire |
| POST | `/users` | Créer un stagiaire |
| PUT | `/users/{moodle_id}` | Modifier un stagiaire |
| DELETE | `/users/{moodle_id}` | Supprimer un stagiaire |
| POST | `/users/{moodle_id}/toggle` | Activer/Désactiver |
| GET | `/users/{moodle_id}/courses` | Cours du stagiaire |
| POST | `/users/sync` | Synchroniser depuis Moodle |

---

## GET /users

Liste les stagiaires (paginé).

**Paramètres query :**

| Paramètre | Type | Défaut | Description |
|-----------|------|--------|-------------|
| page | int | 1 | Numéro de page |
| per_page | int | 20 | Éléments par page (max: 100) |
| search | string | - | Recherche par nom/email |

**Exemple :**

```bash
curl -X GET "https://votre-domaine.com/api/moodlev5/users?page=1&per_page=20" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "moodle_id": 123,
        "username": "jdupont",
        "email": "j.dupont@example.com",
        "firstname": "Jean",
        "lastname": "Dupont",
        "fullname": "Jean Dupont",
        "suspended": false,
        "syncedAt": "2026-02-12T10:30:00+00:00",
        "createdAt": "2026-02-01T09:00:00+00:00",
        "updatedAt": "2026-02-12T10:30:00+00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}
```

---

## GET /users/{moodle_id}

Récupère un stagiaire par son ID Moodle.

**Exemple :**

```bash
curl -X GET "https://votre-domaine.com/api/moodlev5/users/123" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "data": {
    "user": {
      "moodle_id": 123,
      "username": "jdupont",
      "email": "j.dupont@example.com",
      "firstname": "Jean",
      "lastname": "Dupont",
      "fullname": "Jean Dupont",
      "suspended": false,
      "syncedAt": "2026-02-12T10:30:00+00:00",
      "createdAt": "2026-02-01T09:00:00+00:00",
      "updatedAt": "2026-02-12T10:30:00+00:00"
    }
  }
}
```

---

## POST /users

Crée un nouveau stagiaire.

**Body JSON :**

```json
{
  "username": "jdupont",
  "email": "j.dupont@example.com",
  "firstName": "Jean",
  "lastName": "Dupont",
  "password": "MotDePasse123!"
}
```

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| username | string | Oui | Nom d'utilisateur unique |
| email | string | Oui | Adresse email unique |
| firstName | string | Oui | Prénom |
| lastName | string | Oui | Nom |
| password | string | Non | Mot de passe (généré si absent) |

**Exemple :**

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/users" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jdupont",
    "email": "j.dupont@example.com",
    "firstName": "Jean",
    "lastName": "Dupont",
    "password": "MotDePasse123!"
  }'
```

**Réponse (201) :**

```json
{
  "success": true,
  "message": "Utilisateur créé avec succès",
  "data": {
    "user": {
      "moodle_id": 124,
      "username": "jdupont",
      "email": "j.dupont@example.com",
      "firstname": "Jean",
      "lastname": "Dupont",
      "fullname": "Jean Dupont",
      "suspended": false,
      "syncedAt": "2026-02-12T11:00:00+00:00",
      "createdAt": "2026-02-12T11:00:00+00:00",
      "updatedAt": "2026-02-12T11:00:00+00:00"
    }
  }
}
```

---

## PUT /users/{moodle_id}

Met à jour un stagiaire.

**Body JSON :**

```json
{
  "email": "nouveau@example.com",
  "firstName": "Jean-Pierre",
  "lastName": "Dupont",
  "password": "NouveauMotDePasse123!",
  "suspended": false
}
```

| Champ | Type | Description |
|-------|------|-------------|
| email | string | Nouvelle adresse email |
| firstName | string | Nouveau prénom |
| lastName | string | Nouveau nom |
| password | string | Nouveau mot de passe |
| suspended | boolean | `true` = désactivé, `false` = actif |

**Exemple :**

```bash
curl -X PUT "https://votre-domaine.com/api/moodlev5/users/123" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nouveau@example.com",
    "firstName": "Jean-Pierre"
  }'
```

**Réponse :**

```json
{
  "success": true,
  "message": "Utilisateur mis à jour avec succès",
  "data": {
    "user": {
      "moodle_id": 123,
      "username": "jdupont",
      "email": "nouveau@example.com",
      "firstname": "Jean-Pierre",
      "lastname": "Dupont",
      "fullname": "Jean-Pierre Dupont",
      "suspended": false,
      ...
    }
  }
}
```

---

## DELETE /users/{moodle_id}

Supprime définitivement un stagiaire de Moodle et de la base locale.

> **Attention :** Cette action est irréversible. L'utilisateur sera complètement supprimé de Moodle via `core_user_delete_users`.

**Exemple :**

```bash
curl -X DELETE "https://votre-domaine.com/api/moodlev5/users/123" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "message": "Utilisateur supprimé avec succès"
}
```

**Erreurs possibles :**

| Code | Message | Description |
|------|---------|-------------|
| 404 | Utilisateur non trouvé | L'ID Moodle n'existe pas |
| 500 | Erreur lors de la suppression | Échec de l'appel API Moodle |

---

## POST /users/{moodle_id}/toggle

Active ou désactive un stagiaire.

**Exemple :**

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/users/123/toggle" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "message": "Utilisateur activé avec succès",
  "data": {
    "user": {
      "moodle_id": 123,
      "suspended": false,
      ...
    }
  }
}
```

---

## GET /users/{moodle_id}/courses

Liste les cours d'un stagiaire avec sa progression.

**Exemple :**

```bash
curl -X GET "https://votre-domaine.com/api/moodlev5/users/123/courses" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "data": {
    "courses": [
      {
        "moodle_id": 45,
        "shortname": "SEC-001",
        "fullname": "Formation Sécurité",
        "progress": 75,
        "completed": false,
        "startdate": "2026-01-15T00:00:00+00:00",
        "enddate": "2026-03-15T00:00:00+00:00"
      }
    ]
  }
}
```

---

## POST /users/sync

Synchronise les stagiaires depuis Moodle vers la base locale.

**Exemple :**

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/users/sync" \
  -H "X-API-Key: bubul_sk_xxx"
```

**Réponse :**

```json
{
  "success": true,
  "message": "Synchronisation terminée : 150 utilisateurs",
  "data": {
    "stats": {
      "added": 5,
      "updated": 142,
      "deleted": 3,
      "total": 150
    }
  }
}
```

---

## Commandes CLI

```bash
# Synchroniser tous les utilisateurs
php bin/console sam:sync:users

# Synchroniser une entreprise spécifique
php bin/console sam:sync:users --company=uuid-entreprise
```