Réservations

Ces endpoints gèrent le cycle de vie des sièges. Ils s'appellent depuis votre serveur, avec la clé secrète — jamais depuis le navigateur.

available ──hold──▶ hold ──book──▶ booked
    ▲                 │              │
    └──release────────┴──release─────┘
    └──expiration automatique du hold

Deux champs à ne pas confondre avec leurs équivalents intuitifs

Le corps attend seatKeys, pas seats. Et holdToken est obligatoire sur hold, book et release : c'est lui qui rattache l'opération à un panier. Il n'existe pas de champ orderId.

Bloquer des sièges

POST /api/events/{eventId}/hold

Bloque temporairement des sièges pendant la durée configurée dans le back-office (Paramètres → Durée de hold). Passé ce délai, ils redeviennent available sans intervention.

Champ	Type	Requis	Description
seatKeys	string[]	oui	Clés des sièges à bloquer
holdToken	string	oui	Jeton du panier — celui de la session

cURL

curl -X POST https://api.mitoera.com/api/events/EVENT_ID/hold \
  -u pk_xxxxxxxx:sk_xxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{"seatKeys":["A-1","A-2"],"holdToken":"hld_9f2c…"}'

SDK JS

const hold = await client.holds.hold(eventId, ['A-1', 'A-2'], holdToken);

SDK PHP

$hold = $client->holds->hold($eventId, ['A-1', 'A-2'], $holdToken);

{
  "holdToken": "hld_9f2c…",
  "seatKeys": ["A-1", "A-2"],
  "expiresAt": "2025-03-12T20:14:00+00:00",
  "durationSeconds": 600
}

Le widget bloque déjà

Quand l'utilisateur sélectionne un siège dans SeatingChart, le hold est posé automatiquement. Cet endpoint sert aux réservations initiées côté serveur — guichet physique, allocation d'un quota, import d'une billetterie externe.

Confirmer une réservation

POST /api/events/{eventId}/book

Bascule les sièges en booked, de façon permanente. C'est la seule opération qui vend réellement les places.

Champ	Type	Requis	Description
seatKeys	string[]	oui	Clés des sièges à confirmer
holdToken	string	oui	Jeton du panier

cURL

curl -X POST https://api.mitoera.com/api/events/EVENT_ID/book \
  -u pk_xxxxxxxx:sk_xxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{"seatKeys":["A-1","A-2"],"holdToken":"hld_9f2c…"}'

SDK JS

const book = await client.holds.book(eventId, ['A-1', 'A-2'], holdToken);

SDK PHP

$book = $client->holds->book($eventId, ['A-1', 'A-2'], $holdToken);

{
  "bookedSeats": ["A-1", "A-2"],
  "eventId": "01926b1c-5678-7abc-8def-000000000002",
  "bookedAt": "2025-03-12T20:06:31+00:00"
}

Confirmez après encaissement, jamais avant

Un book réussi est définitif du point de vue de l'inventaire. Si le paiement échoue ensuite, il vous faut un release explicite — plus de filet automatique, contrairement au hold.

Libérer des sièges

POST /api/events/{eventId}/release

Remet des sièges bloqués ou réservés à l'état available.

Champ	Type	Requis	Description
seatKeys	string[]	oui	Clés des sièges à libérer
holdToken	string	oui	Jeton du panier

cURL

curl -X POST https://api.mitoera.com/api/events/EVENT_ID/release \
  -u pk_xxxxxxxx:sk_xxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{"seatKeys":["A-1","A-2"],"holdToken":"hld_9f2c…"}'

SDK JS

await client.holds.release(eventId, ['A-1', 'A-2'], holdToken);

SDK PHP

$client->holds->release($eventId, ['A-1', 'A-2'], $holdToken);

{ "message": "Seats released" }

Appelez-le dès qu'un panier est abandonné : attendre l'expiration immobilise des places vendables.

Forcer un statut

POST /api/events/{eventId}/change-status

Définit manuellement le statut d'un ou plusieurs sièges, sans passer par le cycle hold/book. Pas de holdToken ici : l'opération est administrative.

Champ	Type	Requis	Description
seatKeys	string[]	oui	Clés des sièges concernés
status	string	oui	available, hold, booked ou canceled

cURL

curl -X POST https://api.mitoera.com/api/events/EVENT_ID/change-status \
  -u pk_xxxxxxxx:sk_xxxxxxxx \
  -H 'Content-Type: application/json' \
  -d '{"seatKeys":["A-5"],"status":"canceled"}'

SDK JS

await client.holds.changeStatus(eventId, ['A-5'], 'canceled');

SDK PHP

$client->holds->changeStatus($eventId, ['A-5'], 'canceled');

{ "message": "Seat status changed" }

Cas d'usage typiques : neutraliser un siège cassé, marquer une place d'invité, rouvrir une zone.

Erreurs

Le corps porte toujours un champ error :

{ "error": "One or more seats are not available" }

Code	Message	Situation	Que faire
409	One or more seats are not available	Un des sièges est déjà hold ou booked	Rafraîchir le plan, proposer d'autres places
404	Event not found	eventId inconnu	Vérifier l'UUID
401	variable	Clé refusée par la couche métier	Voir Diagnostiquer un 401
400	variable	Payload invalide, statut inconnu, holdToken manquant	Contrôler le corps de la requête

Le message ne nomme pas les sièges fautifs. Pour savoir lesquels, relisez l'état de l'événement avec GET /api/events/{eventId}/seats et comparez avec ce que vous demandiez.

Côté SDK, ces réponses lèvent une ApiException portant le statusCode correspondant. Voir Codes d'erreur et, pour le flux complet, Brancher un paiement.