L'objet entrée de liste d'attente

Une entrée de liste d’attente, c’est un client qui attend une table pour une date de service. Elle revient d’Entrées de liste d’attente et de tous les webhooks waitlist_entry.*.

Champs

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 : waitlist_entry

The object type: always waitlist_entry.

idstring

The entry’s id, wl_…. Opaque and permanent.

statusstring

Valeurs possibles : active offered suggested promoted cancelled expired

Where the entry is in the queue.

• active: waiting.
• offered: a place has been offered to the guest and the offer is still open.
• suggested: a booking has been proposed to the restaurant’s staff, who decide.
• promoted: it became a booking — see reservation.
• cancelled: the guest or the restaurant withdrew it.
• expired: it ran out of time: the service passed, or the offers ran out.

joined_viastring

Valeurs possibles : widget staff partner_platform

How the guest joined the queue. Not called source, which means something else on a reservation and on a guest.

• widget: in the restaurant’s booking widget.
• staff: added by the restaurant’s staff.
• partner_platform: in the booking widget embedded on a partner’s page.

service_datestring (date)

The service day the guest wants a table on, YYYY-MM-DD in the restaurant’s timezone.

party_sizeinteger

How many guests the entry is for.

window_startstring

The earliest start time the guest will take a table at, HH:MM on service_date in the restaurant’s timezone. With window_end it is the range the matching engine may offer inside — a slot outside it is never offered to this entry. Read it with window_start_day_offset, which says whether the clock time belongs to the service date or to its post-midnight tail.

window_endstring

The latest start time the guest will take, HH:MM on service_date in the restaurant’s timezone, read with window_end_day_offset. Always at or after window_start once both offsets are applied, so a window that runs past midnight — 23:30 to 00:30 — is window_end_day_offset: 1, not a wrapped clock time.

window_start_day_offsetinteger

0 = the service date, 1 = its post-midnight tail.

window_end_day_offsetinteger

0 = the service date, 1 = its post-midnight tail.

shift_namestringfacultatifnullable

The name of the service the guest joined for, as it was shown to them when they joined — a later rename does not change it. null when that service had no name.

shift_start_timestringfacultatifnullable

That service’s start, wall-clock HH:MM in the restaurant’s timezone, as it was when the guest joined. null when not recorded.

shift_end_timestringfacultatifnullable

That service’s end, in the same form. null when not recorded.

notesstringfacultatifnullable

The guest’s own request, as they typed it when joining. Guest data: present only when your key carries guests:read; otherwise the field is absent, not null. Every webhook delivery carries it.

reservationstringfacultatifnullable

The booking this entry became, once it is one a consumer can fetch. Null while an offer is still open — that hold is not a published booking.

gueststring or Guestfacultatif

The guest waiting. By default their id, gst_…; the full Guest object when you pass ?expand=guest, which needs the guests:read scope — without it the request is refused with 403 insufficient_scope, never downgraded to the id. Webhook deliveries always carry the id.

Every entry has a guest, so in practice the field is always present; it would be absent, not null, on an entry without one.

created_atstring (date-time)

When the guest joined: ISO 8601 with the restaurant’s UTC offset.

updated_atstring (date-time)

When the entry last changed, in the same format. The value updated_since compares against.

La plage n’est pas deux heures d’horloge

window_start et window_end sont des heures murales sur service_date, et chacune porte son propre décalage de jour. Une plage qui passe minuit est window_end_day_offset: 1, jamais une heure qui boucle, si bien que window_end est toujours au niveau ou après window_start une fois les deux décalages appliqués. Appliquez-les avant de comparer ou d’afficher.

Les champs de service sont un instantané. shift_name, shift_start_time et shift_end_time sont ce qui a été montré au client au moment où il a rejoint la file, et un renommage ultérieur ne les change pas.

Les statuts, et celui qui laisse un identifiant derrière lui

Une entrée attend (active), reçoit une proposition de place (offered) ou est proposée au personnel (suggested), puis finit promoted, cancelled ou expired. Seul promoted produit une réservation et reservation la nomme. Ce champ est nul tant qu’une proposition est ouverte — la table qu’une proposition retient n’est pas une réservation publiée, et le glossaire dit ce que cela veut dire.

Ce que votre clé peut lire

notes contient la demande du client dans ses mots et demande guests:read ; sans cette portée le champ est absent, pas nul. guest est l’identifiant gst_…, et ?expand=guest le remplace par l’objet client entier — également guests:read, et refusé plutôt que rabattu sans elle. Les livraisons de webhook portent l’identifiant et portent notes quelle que soit la clé, exactement comme sur une réservation.