# API SAM - Introduction

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

---

## Authentification

### Clé API

Toutes les requêtes doivent inclure une clé API dans le header :

```
X-API-Key: bubul_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Paramètre Company (Admin uniquement)

Les administrateurs doivent spécifier l'entreprise cible via le paramètre query :

```
?company=uuid-de-l-entreprise
```

---

## Format des réponses

### Succès

```json
{
  "success": true,
  "message": "Message optionnel",
  "data": { ... }
}
```

### Erreur

```json
{
  "success": false,
  "message": "Description de l'erreur",
  "errors": { ... }
}
```

---

## Codes HTTP

| Code | Description |
|------|-------------|
| 200 | Succès |
| 201 | Ressource créée |
| 400 | Requête invalide |
| 401 | Non authentifié |
| 403 | Accès refusé |
| 404 | Ressource non trouvée |
| 409 | Conflit (doublon) |
| 500 | Erreur serveur |

---

## Pagination

Les endpoints de liste supportent la pagination :

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

**Réponse paginée :**

```json
{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}
```

---

## Endpoint de test

### GET /me

Retourne les informations de l'utilisateur connecté.

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

**Réponse :**

```json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "name": "Jean Dupont",
      "roles": ["ROLE_USER"]
    },
    "company": {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Mon Entreprise",
      "has_moodle_config": true
    }
  }
}
```

---

### GET /status

Vérifie la connexion au LMS Moodle.

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

**Réponse :**

```json
{
  "success": true,
  "data": {
    "connected": true,
    "moodle_url": "https://moodle.example.com",
    "site_name": "Mon LMS",
    "version": "4.1"
  }
}
```