Glossaire

Le vocabulaire de la restauration que le reste de ce site emploie sans s’arrêter pour l’expliquer. Chaque entrée est courte volontairement : lorsqu’une notion dispose de sa propre page, l’entrée y renvoie au lieu de la répéter.

Garantie par carte

Une carte de paiement retenue sur une réservation. Service prend une empreinte : la carte est enregistrée et un montant est autorisé, et rien n’est débité au moment de la réservation. Quels services en demandent une, et à partir de quel nombre de couverts, se lit sur le service dans GET /v1/availability (guarantee_from_party_size) ; une réservation qui en déclenche une attend la carte avant d’être publiée. Voir Prendre un acompte.

Couvert

Un client attablé. Un groupe de quatre représente quatre couverts, et party_size compte les couverts. Toutes les capacités de cette API sont exprimées en couverts : available_covers sur un créneau, max_covers_per_slot et les plafonds décrits dans limites de service.

Exception de date

Une modification que le restaurant applique à un service sur une date précise : horaires différents, plafond de couverts différent, autre plan de salle, ou service supprimé ce jour-là. GET /v1/availability renvoie la date telle qu’elle sera réellement assurée, exception déjà appliquée : vous n’avez jamais à combiner les deux vous-même.

Ce n’est pas le tableau override d’une création, qui lève une règle de réservation pour une seule requête. Celui-là est traité dans Réserver au-delà des règles.

Option

Un créneau retiré de la vente pendant qu’un client paie ou se décide. Ce n’est pas une réservation, elle n’a pas de client et elle vit sur /v1/holds jusqu’à ce que vous la convertissiez, que vous la libériez ou que son échéance soit tranchée. Voir Poser une option.

Assertion d’identité

Un court jeton signé que la page hôte remet au widget de réservation pour prouver quel client le consulte, afin que le formulaire arrive prérempli et que la réservation se rattache au bon profil. Cela appartient au widget : sur cette API votre serveur est déjà la partie de confiance, vous désignez donc le client vous-même avec guest_id ou un objet guest. Voir Identifier le client.

Réservation publiée

Une réservation que vous pouvez atteindre. Elle est listée par GET /v1/reservations, elle se résout par son identifiant, elle apparaît dans le flux updated_since et dans le flux d’événements, et son reservation.created part.

Deux réservations ne sont pas encore publiées : celle qui attend une carte (awaiting_guarantee, après une création sur un créneau garanti) et celle qui attend la réponse d’un client en liste d’attente (awaiting_guest). Aucune des deux ne vous parvient et aucun événement les concernant non plus, modifications comprises. La publication est le moment où la réservation devient lisible pour vous, et ce qu’elle dit alors est ce qui a eu lieu, pas ce qui avait été demandé au départ.

Service

Le service que le restaurant assure : déjeuner, dîner, brunch. Dans le code il s’appelle shift, et les deux mots désignent la même chose : GET /v1/availability renvoie les services du jour dans shifts[], chacun avec un identifiant opaque shf_…, et le widget de réservation en accepte un dans l’indice shiftId. Ses heures d’ouverture et de fermeture, son dernier horaire d’arrivée, sa grille de créneaux et ses limites de service lui appartiennent.

Un service qui n’existe que sous forme d’exception de date n’a pas d’identifiant shf_… propre : shifts[].id vaut alors null.

Avec une majuscule et sans article, Service désigne le produit. Lorsqu’une phrase peut se lire des deux façons, ce site écrit l’API Service.

Limites de service

Trois plafonds de couverts que porte un service, et qu’une réservation doit tous franchir :

Plafond	Ce qu’il limite	Publié sous
Par horaire d’arrivée	Les couverts arrivant sur un même horaire de la grille, ce qui cadence la cuisine.	max_covers_per_slot sur chaque créneau
Par service	Les couverts de tout le service, le budget de la soirée.	Non publié
Simultané	Les couverts attablés au même instant, l’occupation de la salle.	Non publié

Vous lisez la réponse plutôt que les trois entrées : available_covers sur un créneau est celui des plafonds qui contraint en premier. Il vaut null lorsque le restaurant n’en fixe aucun, et null signifie alors illimité et non plus rien de disponible.

Une réservation créée avec excluded_from_shift_limits: true ne pèse sur aucun des trois. Ce drapeau et la portée qu’il réclame sont traités dans Réserver au-delà des règles.

Grille de créneaux

Les horaires d’arrivée qu’un service propose à une date : depuis son début, au pas que le restaurant lui fixe (15, 30 ou 60 minutes), jusqu’à son dernier horaire. Ce pas n’est pas un champ lisible : GET /v1/availability renvoie la grille elle-même, et aucune heure entre ses marches. Une création à 19:10 sur un service qui accueille toutes les demi-heures est refusée avec start_time_off_grid alors même que le service est ouvert, et le message de ce refus nomme le pas ainsi que le premier et le dernier horaire.

Balayage

Un passage de fond qui s’exécute à intervalle fixe et tranche ce qu’une échéance seule ne tranche pas. Celui que vous pouvez observer est le balayage des options, toutes les cinq minutes : il fait expirer une option commitment dont l’échéance est passée, ce qui explique que le hold.expired que vous recevez porte l’instant du balayage et non expires_at.

Arrivée sans réservation

Un groupe installé sans avoir réservé, saisi par le personnel à l’accueil. Il vous parvient comme une réservation ordinaire portant source: "walk_in", listée avec les autres valeurs de source dans la référence.