Concepts

Cinq objets suffisent à décrire toute la plateforme. Les comprendre évite la plupart des erreurs d'intégration.

Plan (chart)

La carte d'une salle : ses sièges, ses rangées, ses zones. Un plan est réutilisable — la même salle sert à tous vos spectacles.

Un plan a un statut :

Statut	Signification
draft	En cours de dessin, non utilisable par un événement
published	Publié, associable à des événements et affichable par le widget
archived	Retiré de la circulation

Un quatrième état existe, mais ce n'est pas un statut : le booléen pendingChanges indique qu'un plan publié a été modifié depuis. Les événements continuent alors de servir la version publiée jusqu'à la republication.

Un plan se dessine dans le back-office ou dans l'éditeur embarqué, et se publie via POST /api/charts/{chartId}/publish.

Catégorie

Un regroupement de sièges par tarif ou par zone : « Carré Or », « Balcon », « PMR ». Une catégorie porte un nom, une couleur d'affichage et un tarif de base. Chaque siège du plan appartient à une catégorie.

Les catégories sont attachées au plan : c'est le même découpage qui sert à tous les événements de cette salle.

Événement

Une occurrence : une date de spectacle sur un plan donné. C'est au niveau de l'événement que vivent les statuts de sièges — le même siège A-1 peut être libre le 12 mars et réservé le 15 mars.

Un événement porte :

• un title — ce que voit l'humain
• un identifier — un slug unique, pratique pour construire vos URLs et retrouver l'événement sans connaître son UUID
• un chartId — le plan associé (un seul à la fois)

Siège et statut

Chaque siège d'un événement est dans l'un de ces quatre états :

Statut	Signification
available	Libre, sélectionnable
hold	Bloqué temporairement pendant un achat en cours
booked	Réservé fermement
canceled	Retiré de la vente (siège cassé, distanciation, régie…)

Hold et session

Un hold est un blocage temporaire. Sa durée est configurée dans le back-office (Paramètres → Durée de hold). Passé ce délai, le siège redevient available sans intervention.

Une session matérialise un panier côté serveur. Vous la créez avant d'afficher la page, elle renvoie :

• un sessionToken — à transmettre au widget côté navigateur
• un holdToken — à réutiliser côté serveur pour confirmer ou libérer les sièges de ce panier
• un expiresIn — sa durée de vie en secondes

Le trio hold → book → release est détaillé dans la recette Holds et sessions.

Workspace

Votre espace de travail : il contient vos plans, événements, catégories, clés API et membres d'équipe. Toutes les requêtes API sont automatiquement limitées au workspace de la clé utilisée — vous n'avez jamais à le préciser.