# API SAM - Cohortes

[← Users](01-users.md) | [Accueil](README.md) | [Cours →](03-courses.md)

---

Gestion des cohortes Moodle et de leurs membres.

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

---

## Endpoints

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | `/cohorts` | Liste des cohortes |
| GET | `/cohorts/{moodle_id}` | Détail d'une cohorte |
| POST | `/cohorts` | Créer une cohorte |
| PUT | `/cohorts/{moodle_id}` | Modifier une cohorte |
| GET | `/cohorts/{moodle_id}/members` | Liste des membres |
| POST | `/cohorts/{moodle_id}/members` | Ajouter des membres |
| DELETE | `/cohorts/{moodle_id}/members` | Retirer des membres |

---

## GET /cohorts

Liste les cohortes (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 |

**Exemple :**

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

**Réponse :**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "moodle_id": 1,
        "name": "Promotion 2026",
        "id_number": "PROMO-2026",
        "description": "Stagiaires de la promotion 2026",
        "member_count": 25,
        "visible": true
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 10,
      "total_pages": 1
    }
  }
}
```

---

## GET /cohorts/{moodle_id}

Récupère une cohorte par son ID Moodle.

**Exemple :**

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

**Réponse :**

```json
{
  "success": true,
  "data": {
    "cohort": {
      "moodle_id": 1,
      "name": "Promotion 2026",
      "id_number": "PROMO-2026",
      "description": "Stagiaires de la promotion 2026",
      "member_count": 25,
      "visible": true
    }
  }
}
```

---

## POST /cohorts

Crée une nouvelle cohorte.

**Body JSON :**

```json
{
  "name": "Nouvelle Cohorte",
  "idNumber": "COH-001",
  "description": "Description de la cohorte"
}
```

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| name | string | Oui | Nom de la cohorte |
| idNumber | string | Non | Identifiant unique |
| description | string | Non | Description |

**Exemple :**

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/cohorts" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nouvelle Cohorte",
    "idNumber": "COH-001",
    "description": "Description de la cohorte"
  }'
```

**Réponse (201) :**

```json
{
  "success": true,
  "message": "Cohorte créée avec succès",
  "data": {
    "cohort": {
      "moodle_id": 5,
      "name": "Nouvelle Cohorte",
      "id_number": "COH-001",
      "description": "Description de la cohorte",
      "member_count": 0,
      "visible": true
    }
  }
}
```

---

## PUT /cohorts/{moodle_id}

Met à jour une cohorte.

**Body JSON :**

```json
{
  "name": "Cohorte Modifiée",
  "idNumber": "COH-001-V2",
  "description": "Nouvelle description"
}
```

**Exemple :**

```bash
curl -X PUT "https://votre-domaine.com/api/moodlev5/cohorts/5" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cohorte Modifiée"
  }'
```

**Réponse :**

```json
{
  "success": true,
  "message": "Cohorte mise à jour avec succès",
  "data": {
    "cohort": { ... }
  }
}
```

---

## GET /cohorts/{moodle_id}/members

Liste les membres d'une cohorte.

**Paramètres query :**

| Paramètre | Type | Défaut | Description |
|-----------|------|--------|-------------|
| page | int | 1 | Numéro de page |
| per_page | int | 20 | Éléments par page |

**Exemple :**

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

**Réponse :**

```json
{
  "success": true,
  "data": {
    "members": [
      {
        "moodle_id": 123,
        "username": "jdupont",
        "email": "j.dupont@example.com",
        "firstname": "Jean",
        "lastname": "Dupont",
        "fullname": "Jean Dupont"
      }
    ],
    "total": 25
  }
}
```

---

## POST /cohorts/{moodle_id}/members

Ajoute des membres à une cohorte.

**Body JSON :**

```json
{
  "user_ids": [123, 456, 789]
}
```

**Exemple :**

```bash
curl -X POST "https://votre-domaine.com/api/moodlev5/cohorts/1/members" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [123, 456, 789]
  }'
```

**Réponse :**

```json
{
  "success": true,
  "message": "3 membre(s) ajouté(s)",
  "data": {
    "added": 3
  }
}
```

---

## DELETE /cohorts/{moodle_id}/members

Retire des membres d'une cohorte.

**Body JSON :**

```json
{
  "user_ids": [123, 456]
}
```

**Exemple :**

```bash
curl -X DELETE "https://votre-domaine.com/api/moodlev5/cohorts/1/members" \
  -H "X-API-Key: bubul_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [123, 456]
  }'
```

**Réponse :**

```json
{
  "success": true,
  "message": "2 membre(s) retiré(s)",
  "data": {
    "removed": 2
  }
}
```

---

## Commandes CLI

```bash
# Synchroniser toutes les cohortes
php bin/console sam:sync:cohorts

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