L'objet disponibilité
La disponibilité vient en deux formes, une par point de terminaison de Disponibilité. Les deux disent ce qui était vendable au moment de la lecture et aucune n’est une promesse : le chemin de création revérifie chaque plafond et chaque table sous verrou.
L’objet disponibilité
Section intitulée « L’objet disponibilité »GET /v1/availability renvoie ceci, pour une date de service et un nombre de
couverts. Les services, leurs créneaux et la garantie par carte qu’ils portent
éventuellement sont imbriqués sur place.
Le tableau ci-dessous est généré depuis la spécification OpenAPI et reste en anglais, comme la référence de l'API : noms de champs, valeurs d'énumération et descriptions viennent du backend. Une traduction serait une copie qui ment dès la première évolution du contrat.
objectstring
Valeurs possibles : availability
The object type: always availability.
service_datestring (date)
The service day asked about, YYYY-MM-DD in the restaurant’s timezone.
party_sizeinteger
The party size asked about. Every slot, flag and guarantee below answers for it.
section_idstringnullable
The sec_… filter applied, if any.
day_messagestringnullable
A day-level note from the restaurant, shown as a banner. Independent of the shifts below — it can exist on a day where every service was removed.
display_onlyboolean
Nothing is bookable today and what remains to show is a display-only service’s message. Day-level: NOT the per-shift flag of the same name.
message_onlyboolean
No service runs today, but day_message carries the reason. Distinct from a closure.
closureAvailabilityClosurenullable
The closure covering this date, or null. When set the day takes no bookings and shifts is empty.
objectstring
Valeurs possibles : availability_closure
The object type: always availability_closure.
namestringnullable
The restaurant’s name for the closure, e.g. a holiday. null when it gave none.
guest_messagestringnullable
The restaurant’s own words for this closure. Show them.
start_datestring (date)
First day of the closure, YYYY-MM-DD in the restaurant’s timezone.
end_datestring (date)
Last day of the closure, inclusive, in the same form.
shiftsarray of AvailabilityShift
The services that run on this date. [] on a closed day or a day with no service.
objectstring
Valeurs possibles : availability_shift
The object type: always availability_shift.
idstringnullable
Opaque shf_… id, or null for a service that exists only as a date-scoped override.
namestringnullable
The service’s name, e.g. Dîner. A date override’s name wins over the service’s own. null when neither has one.
guest_messagestringnullable
The restaurant’s own note for this service. Show it.
start_timestringnullable
HH:MM, restaurant timezone.
end_timestringnullable
HH:MM, restaurant timezone.
effective_cutoff_minutesintegernullable
How many minutes before start_time online booking closes FOR THIS service on THIS
date — the value actually enforced, resolved through the restaurant’s rule cascade
(a date override beats this service’s own rule, which beats the house default). This
is the authoritative one: configuration.default_cutoff_minutes is only the house
default and a service may set its own.
0 means bookable right up to the start time, -1 means bookable during the
service, and null means the restaurant has no booking rule at all and booking
never closes.
Once it passes, this service lists no slots and a create is refused with
cutoff_passed — so treat it as the countdown to show a guest, never as permission
to book.
display_onlyboolean
The service is open and worth showing but takes NO online booking. Render its message, never a booking control.
booking_closedboolean
Online booking for this service on this date is over: effective_cutoff_minutes
has passed, or its last seating time is behind the clock. slots is then []
because booking for it has ended, not because it filled, so do not show it as full.
The widget leaves such a service out of the list entirely.
Computed in the restaurant’s timezone at the moment of the request, so it is only
ever true on today’s date — and on yesterday’s, which this API still serves while
an overnight service is seating past midnight: there the overnight service reads
false until its last seating has passed, and every other service true.
requires_approvalboolean
A booking here is a REQUEST: it lands as pending and staff decide. Never tell the guest they are booked.
waitlist_openboolean
A guest of this party size may join the queue for this service. Always false while the restaurant has its booking widget switched off, because that is what the join endpoint itself enforces.
guaranteeAvailabilityGuaranteenullable
The card guarantee a booking of the requested party size in this service will be asked for. null means no card will be asked for.
objectstring
Valeurs possibles : availability_guarantee
The object type: always availability_guarantee.
modestring
Valeurs possibles : imprint
Only card imprints are disclosed today.
currencystring
ISO 4217 currency code of both amounts, e.g. EUR.
per_guest_amountinteger
Minor units per guest.
amountinteger
Minor units for the requested party size.
cancel_hoursintegernullable
Hours before the seating after which a cancellation may be charged. Null means cancellation is always free and only a no-show is charged.
guarantee_from_party_sizeintegernullable
The smallest party this service asks for a card imprint on this date, whatever
party_size you queried with.
null is a promise: no booking on this service on this date is asked for a card, at
any party size. A number is exact: a party of that size or larger is asked, a
smaller one is not. So on a bookable service guarantee is non-null exactly when
party_size is at least this, and you can tell a guest at which size the card step
starts without querying every size. guarantee still carries the amounts.
Set on a display_only or marked-full service too, where guarantee is always
null: it is what a booking placed there with an override would be asked.
It follows the same rule as the create: an imprint the restaurant cannot currently
charge is not asked, and reads null.
configuration.card_guarantee_from_party_size summarises it across every service
and date.
slotsarray of AvailabilitySlot
The seating times still bookable for the requested party size. [] when none is — read the flags above for why.
objectstring
Valeurs possibles : availability_slot
The object type: always availability_slot.
timestring
Seating time as HH:MM in the restaurant timezone.
available_coversintegernullable
Covers still sellable at this time, or null when no covers cap is configured — meaning unlimited, NOT zero. Do not treat null as falsy.
max_covers_per_slotintegernullable
The per-slot pacing cap in force, or null when none is set.
unavailable_slotsarray of string
Times this service SELLS that this party cannot take right now — rejected by a covers cap or because no table fits. Render them greyed out and offer the queue; hiding them is what makes a booking UI feel broken at peak. Times staff never offered, and times that have simply elapsed, are not listed here.
section_idsarray of string
The rooms this service can be booked WHOLE in on this date: the group_id of every
section group with a row drawn on the floor plan this service uses on this date (a
date override may swap the plan). Pass one as entire_section_id.
Absence is a promise: a group not listed here is refused with
no_table_available_in_section for this service on this date. Presence is only a
maybe: a listed room can still be taken, and is then refused with section_occupied
and its conflicts.
It does not depend on party_size or section_id, and it ignores
bookable_online, which a whole-room booking does not read. Empty when the plan in
use has no sections.
L’objet disponibilité mensuelle
Section intitulée « L’objet disponibilité mensuelle »GET /v1/availability/months renvoie ceci. Son indépendance aux filtres est
voulue — ni nombre de couverts, ni section — pour qu’une lecture peigne un
calendrier entier.
objectstring
Valeurs possibles : availability_month
The object type: always availability_month.
monthstring
YYYY-MM.
daysarray of AvailabilityDay
Every day of the month, in order — never a sparse list.
objectstring
Valeurs possibles : availability_day
The object type: always availability_day.
service_datestring (date)
The day, YYYY-MM-DD in the restaurant’s timezone.
pastboolean
Already gone, allowing for an overnight service still seating.
outside_windowboolean
Beyond how far ahead this restaurant takes bookings.
closedboolean
A closure covers this date.
closure_messagestringnullable
The closure’s message to guests, in the restaurant’s own words, when closed is true. null when the day is not closed or the restaurant wrote no message.
no_shiftsboolean
No service runs — closed, not sold out.
message_onlyboolean
No service runs, but staff left a note to read. Open the day; do not offer times.
display_onlyboolean
Only a display-only service remains. Selectable, but it takes no online booking.
reservation_closedboolean
Every service is past its booking cutoff or simply over. Not the same as sold out.
party_sizesarray of integer
Party sizes that could be seated somewhere on this day. EMPTY with every flag false means fully booked.
sectionsarray of object
Per-seating-area breakdown; empty when the restaurant offers no seating choice online.
objectstring
Valeurs possibles : availability_section
The object type: always availability_section.
idstring
The seating area, as its group_id from GET /v1/sections (sec_…). It can differ from the sec_… on a reservation’s table, which names one floor plan’s row.
party_sizesarray of integer
Party sizes that could be seated in this area on this day. [] when none.
waitlist_party_sizesarray of integer
Party sizes that may join the queue for this day. Independent of whether any slot survives. Always empty while the booking widget is switched off.
Nul n’est pas zéro
Section intitulée « Nul n’est pas zéro »available_covers et max_covers_per_slot valent null quand le restaurant ne
pose aucun plafond, ce qui veut dire illimité. Lire null comme zéro ferme un
créneau ouvert. La même forme apparaît sur guarantee_from_party_size et
effective_cutoff_minutes : null est l’absence de règle, pas une règle réglée
à rien.
Un jour vide n’est pas une seule situation
Section intitulée « Un jour vide n’est pas une seule situation »Un jour de GET /v1/availability/months porte au plus un de ces marqueurs.
Service les teste dans cet ordre et s’arrête au premier qui s’applique :
past— la date est passée, en tenant compte d’un service de nuit qui accueille encore après minuit.outside_window— la date est au-delà de l’horizon de réservation du restaurant.closed— une fermeture couvre la date.closure_messageporte son texte quand le restaurant en a écrit un.message_only— aucun service ne tourne et le personnel a laissé une note à montrer.no_shifts— aucun service ne tourne.display_only— un service qui ne prend aucune réservation en ligne tourne, et aucun service réservable n’a plus rien à offrir.reservation_closed— chaque service réservable a dépassé sa limite de réservation ou son dernier horaire d’arrivée. La journée est terminée pour la réservation en ligne, elle n’est pas complète.
Quand tous les marqueurs sont à faux, party_sizes vide veut dire complet. Un
tunnel qui ne teste que « pas de créneau » réduit huit réponses à une seule et
dit au client la mauvaise chose dans sept cas sur huit.
Il en va de même pour un service. Un service dont les slots sont vides porte
booking_closed quand la réservation en ligne est terminée pour lui à cette
date et display_only quand il n’en prend aucune. Quand les deux sont faux, le
service est ouvert et n’a plus rien pour ce nombre de couverts : c’est seulement
alors qu’il est complet.
Aucun point de terminaison n’écrit ceci
Section intitulée « Aucun point de terminaison n’écrit ceci »La disponibilité est dérivée des services, des tables et des réservations du restaurant. Il n’y a rien à créer et rien ici n’arrive par webhook.