# API SAM - Documentation

Documentation de l'API REST pour le module SAM (Suivi des Apprenants Moodle).

**Auteur :** Andrew MAHE

---

## Fichiers de documentation

| Fichier | Description |
|---------|-------------|
| [00-introduction.md](00-introduction.md) | Authentification, format des réponses, codes HTTP |
| [01-users.md](01-users.md) | Gestion des stagiaires (CRUD, toggle, sync) |
| [02-cohorts.md](02-cohorts.md) | Gestion des cohortes et membres |
| [03-courses.md](03-courses.md) | Gestion des cours |
| [04-progress.md](04-progress.md) | Progression détaillée (cours, sections, quiz) |
| [05-exports.md](05-exports.md) | Exports Excel/PDF |
| [06-moodle-configuration.md](06-moodle-configuration.md) | **Configuration Moodle** (tokens, fonctions, permissions) |
| [07-engagement.md](07-engagement.md) | **Profil d'engagement** (fréquence de connexion, stats par entreprise/utilisateur) |
| [08-submissions.md](08-submissions.md) | Activités récentes et complétions (pagination, filtres) |

---

## Base URL

```
https://votre-domaine.com/api/moodlev5
```

---

## Obtenir une clé API

Pour utiliser l'API SAM, vous devez disposer d'une clé API personnelle.

### Étapes pour obtenir votre clé :

1. **Demander un accès à la plateforme**
   - Envoyez un email à **contact@bubul.app** en précisant votre besoin
   - Notre équipe vous créera un compte sur la plateforme

2. **Se connecter à Bubul**
   - Rendez-vous sur **[bubul.app](https://bubul.app)**
   - Connectez-vous avec vos identifiants

3. **Générer votre clé API**
   - Accédez à **Paramètres** → **Développeur**
   - Cliquez sur **Générer ma clé API**
   - Copiez votre clé (format : `bubul_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)

### Important

- Gardez votre clé API **confidentielle**
- Ne la partagez jamais dans du code public (GitHub, etc.)
- En cas de compromission, révoquez-la immédiatement depuis les paramètres

---

## Authentification rapide

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

---

## Commandes CLI

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

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

# Synchroniser les cours
php bin/console sam:sync:courses

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

---

## Version

**API Version:** 1.0
**Dernière mise à jour:** 2026-02-12
**Auteur:** Andrew MAHE