# Eolem Planning — API Reference

API REST pour gérer des formations dans Google Calendar.

## Base URL

```
https://planning.eolem.com/api/calendar.php
```

## Authentification

Toutes les requêtes nécessitent le header `X-API-Key`.

```
X-API-Key: <votre_clé_api>
```

## Concepts

- Les formations sont des événements "journée entière" (all-day) dans Google Calendar.
- Le titre d'un événement suit le format : `Formation - Client - Lieu`.
- Les horaires (ex: 09:00 - 17:00) sont stockés dans la description de l'événement.
- Une formation sur plusieurs jours crée un seul événement continu (bande).
- Google Calendar utilise des dates de fin exclusives : une formation du 15 au 17 avril a une date de fin Google au 18 avril. L'API gère cette conversion automatiquement à la création.

### Statuts et couleurs

| Statut | Valeur API | colorId Google | Couleur |
|--------|-----------|----------------|---------|
| Option | `option` | 5 | Jaune (Banana) |
| Confirmée | `confirmee` | 1 | Lavande (Lavender) |
| Commandée | `commandee` | 11 | Rouge (Tomato) |

---

## POST — Créer une formation

Crée un événement journée entière dans Google Calendar.

### Requête

```
POST /api/calendar.php
Content-Type: application/json
X-API-Key: <clé>
```

### Body (JSON)

| Champ | Type | Requis | Défaut | Description |
|-------|------|--------|--------|-------------|
| `formation` | string | oui | | Nom de la formation |
| `client` | string | oui | | Nom du client |
| `lieu` | string | oui | | Lieu de la formation |
| `statut` | string | oui | | `option`, `confirmee` ou `commandee` |
| `date_debut` | string | oui | | Premier jour, format `YYYY-MM-DD` |
| `date_fin` | string | oui | | Dernier jour, format `YYYY-MM-DD` |
| `heure_debut` | string | non | `09:00` | Heure de début, format `HH:MM` |
| `heure_fin` | string | non | `17:00` | Heure de fin, format `HH:MM` |
| `description` | string | non | `""` | Notes libres |

### Exemple

```json
{
  "formation": "PHP Avancé",
  "client": "Acme Corp",
  "lieu": "Lyon",
  "statut": "commandee",
  "date_debut": "2026-05-04",
  "date_fin": "2026-05-08",
  "heure_debut": "09:00",
  "heure_fin": "17:00",
  "description": "Formation inter-entreprises"
}
```

### Réponse (201)

```json
{
  "created": [
    {
      "id": "abc123def456",
      "summary": "PHP Avancé - Acme Corp - Lyon",
      "start": "2026-05-04",
      "end": "2026-05-09"
    }
  ]
}
```

Note : `end` dans la réponse est la date exclusive Google Calendar (dernier jour + 1).

### Règles de validation

- `formation`, `client`, `lieu` : non vides
- `statut` : exactement `option`, `confirmee` ou `commandee`
- `date_fin` >= `date_debut`
- `heure_fin` > `heure_debut`

---

## GET — Lister les événements

Retourne tous les événements dans une plage de dates.

### Requête

```
GET /api/calendar.php?date_start=YYYY-MM-DD&date_end=YYYY-MM-DD
X-API-Key: <clé>
```

### Paramètres query string

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `date_start` | string | oui | Début de la plage, format `YYYY-MM-DD` |
| `date_end` | string | oui | Fin de la plage, format `YYYY-MM-DD` |
| `id` | string | non | Si fourni, retourne un seul événement par son ID |

### Réponse (200) — Liste

```json
[
  {
    "id": "abc123def456",
    "summary": "PHP Avancé - Acme Corp - Lyon",
    "location": "Lyon",
    "description": "09:00 - 17:00\nFormation inter-entreprises",
    "colorId": "11",
    "start": "2026-05-04",
    "end": "2026-05-09"
  }
]
```

### Réponse (200) — Événement unique (avec `id`)

```json
{
  "id": "abc123def456",
  "summary": "PHP Avancé - Acme Corp - Lyon",
  "location": "Lyon",
  "description": "09:00 - 17:00\nFormation inter-entreprises",
  "colorId": "11",
  "start": "2026-05-04",
  "end": "2026-05-09"
}
```

### Champs de la réponse

| Champ | Type | Description |
|-------|------|-------------|
| `id` | string | Identifiant Google Calendar de l'événement |
| `summary` | string | Titre au format `Formation - Client - Lieu` |
| `location` | string | Lieu (champ location Google Calendar) |
| `description` | string | Première ligne = horaires (`HH:MM - HH:MM`), lignes suivantes = notes |
| `colorId` | string | ID couleur Google Calendar (5=Option, 1=Confirmée, 11=Commandée) |
| `start` | string | Date de début `YYYY-MM-DD` |
| `end` | string | Date de fin exclusive `YYYY-MM-DD` (dernier jour + 1) |

---

## PUT — Modifier un événement

Mise à jour partielle d'un événement existant. Seuls les champs fournis sont modifiés.

### Requête

```
PUT /api/calendar.php?id=<eventId>
Content-Type: application/json
X-API-Key: <clé>
```

### Body (JSON) — tous les champs sont optionnels

| Champ | Type | Description |
|-------|------|-------------|
| `summary` | string | Nouveau titre complet |
| `location` | string | Nouveau lieu |
| `description` | string | Nouvelle description |
| `statut` | string | `option`, `confirmee` ou `commandee` — met à jour la couleur |
| `colorId` | string | ID couleur Google Calendar (alternative directe à `statut`) |
| `date_debut` | string | Nouvelle date de début `YYYY-MM-DD` |
| `date_fin` | string | Nouvelle date de fin `YYYY-MM-DD` (inclusive, convertie en exclusive) |

### Exemple — Changer le statut d'une formation

```json
{
  "statut": "commandee"
}
```

### Réponse (200)

```json
{
  "id": "abc123def456",
  "summary": "PHP Avancé - Acme Corp - Lyon",
  "location": "Lyon",
  "description": "09:00 - 17:00",
  "colorId": "11",
  "start": "2026-05-04",
  "end": "2026-05-09"
}
```

---

## DELETE — Supprimer un événement

### Requête

```
DELETE /api/calendar.php?id=<eventId>
X-API-Key: <clé>
```

### Réponse

`204 No Content` (pas de body).

---

## Codes d'erreur

| Code | Signification | Exemple |
|------|---------------|---------|
| 400 | Paramètres manquants ou body JSON invalide | `{"error": "Paramètres date_start et date_end requis"}` |
| 401 | API key invalide ou manquante | `{"error": "API key invalide ou manquante"}` |
| 405 | Méthode HTTP non supportée | `{"error": "Méthode non autorisée"}` |
| 422 | Validation échouée | `{"error": "Validation échouée", "details": {"formation": "La formation est obligatoire."}}` |
| 503 | Google Calendar non authentifié | `{"error": "Google Calendar non authentifié. Connectez-vous via l'interface web d'abord."}` |

---

## Exemples curl

### Créer une formation

```bash
curl -X POST https://planning.eolem.com/api/calendar.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: VOTRE_CLE" \
  -d '{
    "formation": "Angular Avancé",
    "client": "Orsys",
    "lieu": "Lyon",
    "statut": "commandee",
    "date_debut": "2026-06-15",
    "date_fin": "2026-06-17"
  }'
```

### Lister les formations d'un mois

```bash
curl "https://planning.eolem.com/api/calendar.php?date_start=2026-06-01&date_end=2026-06-30" \
  -H "X-API-Key: VOTRE_CLE"
```

### Changer le statut d'une formation

```bash
curl -X PUT "https://planning.eolem.com/api/calendar.php?id=EVENT_ID" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: VOTRE_CLE" \
  -d '{"statut": "confirmee"}'
```

### Supprimer une formation

```bash
curl -X DELETE "https://planning.eolem.com/api/calendar.php?id=EVENT_ID" \
  -H "X-API-Key: VOTRE_CLE"
```