# Spécification API v2 — La Comte (festorga) & Orgexpo

> Document à transmettre aux développeurs des API **festorga (« La Comte »)** et **Orgexpo**.
> Objectif : permettre au site **Fort Fort Lointain 2026** d'afficher proprement les **troupes/animations** et **créateurs/exposants**, et de filtrer par statut.
> Les points marqués **🆕** sont les ajouts demandés ; le reste documente l'existant (à conserver).

---

## 1. Conventions communes

- **Transport** : HTTPS obligatoire. Réponses **JSON** (`Content-Type: application/json; charset=utf-8`).
- **Authentification** : en-tête `X-API-Key: <clé>` (clés déjà fournies, à conserver).
- **Encodage** : UTF-8. Dates au format **ISO 8601** (`2026-09-05` ou `2026-09-05T10:00:00+02:00`).
- **Codes HTTP** : `200` OK, `401` clé absente/invalide, `404` ressource inconnue, `429` quota, `500` erreur.
- **Images** : URLs **absolues en HTTPS**, accessibles publiquement sans clé (affichées en `<img>`).
- **Rétro-compatibilité** : les nouveaux champs s'**ajoutent** ; aucun champ existant n'est renommé/supprimé.

---

## 2. 🆕 Endpoint commun — Liste des événements (pour le sélecteur)

Permet au back-office d'afficher un **menu déroulant des événements** au lieu de saisir un identifiant à la main.

### La Comte (festorga)
```
GET https://la-comte.festorga.fr/api/v1/events
X-API-Key: <clé>
```
### Orgexpo
```
GET https://orgexpo.fr/api/evenements.php
X-API-Key: <clé>
```

### Réponse attendue (identique pour les deux)
```json
{
  "count": 2,
  "events": [
    {
      "id": "e_bdc56aa61b2e",
      "nom": "Fort Fort Lointain 2026",
      "date_debut": "2026-09-05",
      "date_fin": "2026-09-06",
      "lieu": "Hippodrome de Parilly, Bron",
      "statut": "publie"
    },
    {
      "id": "e_0a1b2c3d4e5f",
      "nom": "Édition 2025",
      "date_debut": "2025-09-06",
      "date_fin": "2025-09-07",
      "lieu": "…",
      "statut": "archive"
    }
  ]
}
```
| Champ | Type | Obligatoire | Note |
|---|---|---|---|
| `id` | string | ✅ | identifiant à passer aux autres endpoints |
| `nom` | string | ✅ | libellé affiché dans le sélecteur |
| `date_debut` / `date_fin` | date ISO | ⬜ | tri / affichage |
| `lieu` | string | ⬜ | — |
| `statut` | string | ⬜ | `publie` / `brouillon` / `archive` |

---

## 3. La Comte (festorga) — Activités & Troupes

### 3.1 Activités (existant) — à compléter
```
GET https://la-comte.festorga.fr/api/v1/events/{eventId}/activities
X-API-Key: <clé>
```

**Réponse actuelle (à conserver)** + champs **🆕** :
```json
{
  "event": { "id": "e_bdc56aa61b2e", "nom": "Fort Fort Lointain 2026" },
  "count": 58,
  "activites": [
    {
      "id": "s_bfdb45cd5b66",
      "type": "stand",
      "type_label": "Stand",
      "nom": "Potion du sorcier Viking",
      "troupe": "ADVENTURE GAMES",
      "troupe_id": "t_12ab34cd",          // 🆕 lien vers la fiche troupe (cf. 3.2)
      "description": "…",
      "univers": "Sorcellerie",
      "emplacement": "T026",
      "image": "https://la-comte.festorga.fr/api/v1/photo/…",
      "statut": "valide",                  // 🆕 valide | en_attente | refuse
      "email": "contact@adventuregames.fr" // 🆕 contact (non affiché publiquement)
    }
  ]
}
```

| Champ 🆕 | Type | Pourquoi |
|---|---|---|
| `statut` | string | N'afficher que `valide` ; prévoir un **filtre par statut** côté site. **Le plus important.** |
| `troupe_id` | string | Relier l'activité à la fiche troupe (3.2). |
| `email` | string | Contact organisateur (interne). |

### 3.2 🆕 Troupes (entité dédiée) — nouvel endpoint
Aujourd'hui une « troupe » n'est qu'un **nom** ; la vignette de troupe doit donc emprunter la photo d'une de ses activités → **une troupe sans activité photographiée n'a aucune image**. Il faut une **fiche troupe** propre.

```
GET https://la-comte.festorga.fr/api/v1/events/{eventId}/troupes
X-API-Key: <clé>
```
```json
{
  "count": 32,
  "troupes": [
    {
      "id": "t_12ab34cd",
      "nom": "ADVENTURE GAMES",
      "logo": "https://la-comte.festorga.fr/…/logo.jpg",   // 🆕 photo/logo de la troupe
      "description": "Présentation de la troupe…",          // 🆕
      "univers": "Sorcellerie",
      "site_web": "https://adventuregames.fr",              // 🆕
      "facebook": "https://facebook.com/…",                 // 🆕
      "instagram": "https://instagram.com/…",               // 🆕
      "email": "contact@adventuregames.fr",                 // 🆕
      "statut": "valide"                                     // 🆕
    }
  ]
}
```
> À défaut d'un endpoint séparé, intégrer ces champs dans un objet `troupe` complet au sein de chaque activité.

---

## 4. Orgexpo — Exposants / Créateurs

### Existant — à compléter
```
GET https://orgexpo.fr/api/exposants.php?idEvenement={eventId}
X-API-Key: <clé>
```
```json
{
  "evenement": "pB7jZ1gcDh",
  "count": 127,
  "exposants": [
    {
      "id": "1nsGGUvrbu",
      "nom": "Agarthis",
      "description": "Artisanat du cuir…",
      "emplacementtype": "stand",
      "emplacementnumero": "B12",
      "siteWeb": "https://…",
      "facebook": "https://…",
      "instagram": "https://…",
      "image": "https://orgexpo.fr/img/dossier/1nsGGUvrbu/stand/1.jpg",
      "statut": "valide",                 // 🆕 valide | en_attente | refuse
      "email": "contact@agarthis.fr",     // 🆕 contact (interne)
      "categorie": "Cuir & accessoires",  // 🆕 catégorie / univers (filtres)
      "images": [                          // 🆕 galerie (optionnel)
        "https://orgexpo.fr/img/dossier/1nsGGUvrbu/stand/1.jpg",
        "https://orgexpo.fr/img/dossier/1nsGGUvrbu/stand/2.jpg"
      ]
    }
  ]
}
```

| Champ 🆕 | Type | Priorité | Pourquoi |
|---|---|---|---|
| `statut` | string | ⭐⭐⭐ | N'afficher que les exposants `valide` (aujourd'hui on reçoit tout). |
| `email` | string | ⭐⭐ | Contact (interne). |
| `categorie` | string | ⭐⭐ | Filtres / regroupement côté site. |
| `images` | string[] | ⭐ | Galerie multi-photos (optionnel). |

---

## 5. Récapitulatif des priorités

| API | Demande | Priorité |
|---|---|---|
| Les deux | Endpoint **liste des événements** (sélecteur) | ⭐⭐ |
| La Comte | `statut` sur les activités | ⭐⭐⭐ |
| La Comte | **Fiche troupe** (logo, description, web, réseaux, email, statut) | ⭐⭐⭐ |
| La Comte | `email` activité | ⭐ |
| Orgexpo | `statut` exposant | ⭐⭐⭐ |
| Orgexpo | `categorie` | ⭐⭐ |
| Orgexpo | `email` | ⭐⭐ |
| Orgexpo | `images[]` (galerie) | ⭐ |

> Contact technique côté site : Jérémy Loir — back-office Fort Fort Lointain.