1. Lire le catalogue
AvecCATALOG_READ, récupérez les identifiants des salles, services, tables,
prescripteurs et remises du restaurant. Le catalogue ne décrit pas les créneaux
réservables : il peut inclure des tables internes ou des remises inactives.
C’est la disponibilité qui détermine ce qui peut être réservé.
2. Chercher un créneau
AvecAVAILABILITY_READ, appelez GET /availability avec start_at_from,
start_at_to et party_size. Les filtres shift_id et room_id sont
facultatifs. Utilisez des dates ISO 8601 avec décalage explicite.
--data-urlencode conserve le signe + du décalage dans les paramètres de
l’URL.
start_at,
shift_id et la salle, si présente, d’un créneau réellement retourné. La
réponse fournit également end_at et duration_minutes.
POST /availability/check vérifie un seul créneau : 200 avec
data.available: false est un résultat indisponible normal.
La consultation ne bloque aucune capacité. La création revérifie le créneau et
peut répondre 422 s’il n’est plus réservable.
3. Créer la réservation
AppelezPOST /reservations avec RESERVATIONS_WRITE. Voici un corps JSON ;
remplacez le créneau d’exemple par un résultat de disponibilité.
true par défaut. Les désactiver supprime les
notifications client et l’envoi du lien de paiement, sans simuler la
réservation, supprimer la création de paiements ni désactiver les notifications
du restaurant.
customer: null crée une réservation anonyme. Sinon, customer.name est requis
à la création. source vaut WEBSITE par défaut. Les exigences d’empreinte
bancaire peuvent être déduites du service ; le choix explicite de produits
prépayés ou d’extras n’est pas pris en charge en v1. Lisez le statut et les
paiements retournés : 201 ne garantit pas une confirmation.
total_amount_paid enregistre un montant en unité monétaire minimale, sans
débiter le client. Les options de contournement et initial_status sont
détaillées dans les scopes et l’endpoint de
création.
Reprendre après un résultat incertain
external_id doit être unique par restaurant. Un doublon renvoie 409, pas la
réponse initiale. Après un timeout, cherchez GET /reservations par
external_id avec RESERVATIONS_READ avant de recréer. Gardez la même
référence externe. L’API ne propose pas de contrat d’en-tête Idempotency-Key.
4. Lire et modifier
GET /reservations accepte des filtres et une pagination : page commence à 1,
per_page vaut 25 par défaut et ne dépasse pas 100. GET /reservations/{id}
retourne le détail. Les deux exigent RESERVATIONS_READ, avec le scope
supplémentaire pour les données sensibles.
PATCH /reservations/{id} exige RESERVATIONS_WRITE. Les champs omis sont
conservés. customer: null détache le client ; { "id": "..." } rattache un
client existant du restaurant. Des champs client sans identifiant modifient la
fiche liée elle-même, ce qui peut affecter les autres réservations du même
client. Si aucun client n’est lié, fournissez son nom pour en créer un et le
rattacher.
Les verrouillages de service POS peuvent refuser une modification avec 409 et
details.locked_fields. Les règles métier peuvent produire 422. L’annulation
dispose d’un endpoint distinct.
5. Annuler
AppelezPOST /reservations/{id}/cancel avec RESERVATIONS_CANCEL, le type de
contenu JSON et un corps JSON : {} ou { "reason": "Demande du client" }. Le
statut devient CANCELED_BY_RESTAURANT. Une réservation déjà annulée est
retournée sans changer son statut ni son motif existants. Un verrouillage de
service POS peut refuser l’annulation avec 409.