Événements

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

Lister les événements

GET /api/events

cURL

curl https://api.mitoera.com/api/events \
  -u pk_xxxxxxxx:sk_xxxxxxxx

SDK JS

const events = await client.events.listAll();

SDK PHP

$events = $client->events->listAll();

[
  {
    "id": "01926b1c-5678-7abc-8def-000000000002",
    "title": "Concert 12 mars",
    "identifier": "concert-12-mars",
    "chartId": "01926a3f-1234-7abc-8def-000000000001",
    "chartName": "Salle principale",
    "createdAt": "2025-03-01T10:00:00Z"
  }
]

Créer un événement

POST /api/events

Champ	Type	Requis	Description
title	string	oui	Titre affiché
identifier	string	oui	Slug unique, utilisable à la place de l'UUID
chartId	uuid	non	Plan à associer — il doit être publié

cURL

curl -X POST https://api.mitoera.com/api/events \
  -u pk_xxxxxxxx:sk_xxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{"title":"Concert 12 mars","identifier":"concert-12-mars","chartId":"CHART_ID"}'

SDK JS

const event = await client.events.create('Concert 12 mars', 'concert-12-mars', chartId);

SDK PHP

$event = $client->events->create('Concert 12 mars', 'concert-12-mars', $chartId);

Soignez l'identifier

Il rend vos URLs lisibles (/billetterie/concert-12-mars) et évite de trimballer des UUID dans le front. Le widget accepte indifféremment le slug ou l'UUID.

Obtenir un événement

GET /api/events/{eventId}

Par UUID. Pour chercher par slug :

GET /api/events/lookup/{identifier}

cURL

curl https://api.mitoera.com/api/events/lookup/concert-12-mars \
  -u pk_xxxxxxxx:sk_xxxxxxxx

SDK JS

const event = await client.events.get(eventId);
const same  = await client.events.findByIdentifier('concert-12-mars');

SDK PHP

$event = $client->events->get($eventId);
$same  = $client->events->findByIdentifier('concert-12-mars');

Modifier un événement

PUT /api/events/{eventId}

Champ	Type	Requis	Description
title	string	oui	Nouveau titre
identifier	string	oui	Nouveau slug

Changer l'identifier casse les liens

Toute URL et tout widget qui référencent l'ancien slug cesseront de résoudre l'événement. Prévoyez une redirection de votre côté.

Associer un plan

POST /api/events/{eventId}/link-chart/{chartId}

Un événement n'a qu'un seul plan à la fois. Le plan doit être publié.

cURL

curl -X POST https://api.mitoera.com/api/events/EVENT_ID/link-chart/CHART_ID \
  -u pk_xxxxxxxx:sk_xxxxxxxx

SDK JS

await client.events.linkChart(eventId, chartId);

SDK PHP

$client->events->linkChart($eventId, $chartId);

Statuts des sièges

GET /api/events/{eventId}/seats

Retourne l'état de tous les sièges de l'événement.

cURL

curl https://api.mitoera.com/api/events/EVENT_ID/seats \
  -u pk_xxxxxxxx:sk_xxxxxxxx

SDK JS

const map = await client.events.listSeats(eventId);
map.available();         // string[]
map.isAvailable('A-1');  // boolean

SDK PHP

$map = $client->events->listSeats($eventId);
$map->available();         // string[]
$map->isAvailable('A-1');  // bool

La réponse est un objet indexé par clé de siège, enveloppé dans seats — pas un tableau :

{
  "seats": {
    "VIP-1-2":          { "status": "available", "holdToken": null,        "zoneType": "table" },
    "GOLD LEFT-E-24":   { "status": "hold",      "holdToken": "hld_9f2c…", "zoneType": "row"   },
    "A-1":              { "status": "booked",    "holdToken": null,        "zoneType": "row"   }
  }
}

Chaque siège expose un champ zoneType qui indique le type de zone auquel il appartient :

zoneType	Description
row	Rangée classique (numérotée ou en lettres)
table	Section de tables (plan de salle)
free	Zone en accès libre (pas de siège attribué)

Utilisez ce champ pour adapter l'affichage dans vos billets et interfaces : une réservation table affichera « Table 3, Siège 2 » là où une row affichera « Rangée C, Siège 12 ».

Deux pièges classiques

La clé de siège n'est pas un identifiant opaque : c'est le libellé du plan, espaces compris (GOLD LEFT-E-24). N'en déduisez aucun format.

seats est un objet, pas un tableau. Un .filter() ou un foreach appliqué directement dessus échoue. Passez par Object.entries() en JavaScript, ou utilisez le SeatStatusMap des SDK qui s'en charge.

Filtrer sur quelques sièges seulement se fait par paramètre de requête répété :

GET /api/events/{eventId}/seats?seatKeys[]=A-1&seatKeys[]=A-2

Ce filtre a un effet de bord utile : un siège du plan publié qui n'a jamais été manipulé n'a pas encore de ligne en base. Le demander explicitement le crée en available plutôt que de l'omettre de la réponse.

Statut	Signification
available	Libre, sélectionnable
hold	Bloqué temporairement
booked	Réservé fermement
canceled	Retiré de la vente

À quoi ressemble une clé de siège

La règle ci-dessus tient : ne construisez pas les clés vous-même, prenez celles que l'API et le widget vous donnent. Les formes qui suivent sont indicatives — elles servent à lire une clé, à la reconnaître dans un journal, et à repérer une clé manifestement cassée. Elles ne constituent pas un gabarit à reproduire.

Objet du plan	Forme	Exemple
Bloc de sièges	{section}-{rangée}-{siège}	PARTERRE-A-12
Section de tables	{section}-{table}-{siège}	VIP-3-6
Table isolée	{section}-{siège}	BAR-4

Quelques propriétés utiles :

• Les numéros de table et de siège commencent à 1, jamais à 0.
• Le premier segment est la section de l'objet. Si elle est vide, le libellé prend le relais, puis l'identifiant interne — d'où des clés comme Tables groupées-1-1.
• Les rangées suivent le format choisi dans l'éditeur : lettres, chiffres ou chiffres romains, dans un sens ou dans l'autre, avec un départ de numérotation éventuellement décalé. PARTERRE-C-14 est donc une clé ordinaire, pas un signe que quelque chose cloche.
• Les sièges désactivés ou supprimés d'un plan ne produisent aucune clé.
• Une clé reste stable tant que la section n'est pas renommée et que la numérotation n'est pas retouchée. Renommer une section change toutes ses clés : à éviter sur un plan déjà vendu.

Repérer une clé cassée

Une clé valide contient toujours au moins un segment non vide avant le premier tiret. Une valeur comme --, - ou une chaîne vide n'identifie aucun siège : si vous en rencontrez une, signalez-la plutôt que de la traiter — elle ne correspondra à rien côté serveur, et plusieurs sièges distincts risquent de la partager.

Une réponse vide ne veut pas dire « événement non prêt »

Les sièges d'un événement sont créés à la demande, pas à la publication du plan. Tant que personne n'a rien réservé, GET /api/events/{eventId}/seats renvoie un objet seats vide — c'est l'état normal d'un événement neuf, pas une anomalie.

Les sièges vendables sont ceux du plan publié, que le widget connaît déjà. Ne conditionnez pas l'ouverture de la vente à la présence de lignes dans cette réponse : vous bloqueriez tous vos événements avant leur première vente.

Changer des statuts en masse

PATCH /api/events/{eventId}/seats/bulk-status

Champ	Type	Requis	Description
seats	string[]	oui	Sièges concernés
status	string	oui	available, hold, booked ou canceled

Utile pour neutraliser une rangée en régie ou rouvrir une zone à la vente.

SDK JS

const n = await client.events.bulkUpdateSeats(eventId, ['A-1', 'A-2'], 'canceled');

SDK PHP

$n = $client->events->bulkUpdateSeats($eventId, ['A-1', 'A-2'], 'canceled');

La réponse indique le nombre de sièges effectivement modifiés.

Supprimer un événement

DELETE /api/events/{eventId}

cURL

curl -X DELETE https://api.mitoera.com/api/events/EVENT_ID \
  -u pk_xxxxxxxx:sk_xxxxxxxx

SDK JS

await client.events.delete(eventId);

SDK PHP

$client->events->delete($eventId);