L'objet client

Un client, c’est une fiche du répertoire du restaurant. C’est ce que renvoie Clients, ce que ?expand=guest intègre dans une réservation ou une entrée de liste d’attente et ce que livre tout webhook guest.*.

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

The object type: always guest.

idstring

The guest’s id, gst_…. Opaque and permanent. When two profiles are merged, the one that disappears keeps resolving to the survivor in ?id= on GET /v1/guests.

first_namestringnullable

First name. A profile has a first name or a last name, possibly both; null when it has only the other.

last_namestringnullable

Last name. null when the profile has only a first name.

emailstringfacultatifnullable

Primary e-mail address, trimmed and lower-cased. null when none is known.

phonestringfacultatifnullable

Primary phone number: E.164 (+33612345678) when it could be parsed for the restaurant’s country, otherwise as entered with separators removed — so do not assume E.164. null when none is known.

notesstringfacultatifnullable

The restaurant’s own notes on the guest profile: free text written by its staff, or carried over from its previous reservation system — the restaurant’s words about the guest, not the guest’s. A booking’s guest_notes are the guest’s own. null when there are none.

blacklistedboolean

Whether the restaurant has flagged this guest as unwelcome. A flag only: it does not by itself refuse a booking.

blacklist_reasonstringfacultatifnullable

Why the guest was flagged — required by the restaurant when it sets blacklisted. null when the guest is not flagged.

dietary_preferencesarray of string

Dietary preferences the restaurant recorded, as free-form labels. [] when none.

allergiesarray of string

Allergies the restaurant recorded, as free-form labels. [] when none.

birthdaystring (date)facultatifnullable

Date of birth, YYYY-MM-DD. null when not recorded.

anniversarystring (date)facultatifnullable

An anniversary date the restaurant recorded, YYYY-MM-DD. null when not recorded.

vipboolean

Whether the restaurant marked the guest as a VIP.

languagestringfacultatifnullable

Valeurs possibles : fr en de es it nl pt da sv no fi

The language the restaurant writes to this guest in, as an ISO 639-1 code. Set to the restaurant’s primary language when the profile is created unless one is given, so null only on a profile that never had one.

sourcestring

Valeurs possibles : manual widget import host_assertion api website_newsletter

How the restaurant first learned of this guest. Not the same vocabulary as a reservation’s source.

• manual: entered by the restaurant’s staff.
• widget: first seen booking in the restaurant’s booking widget.
• import: brought over from the restaurant’s previous reservation system.
• host_assertion: first seen booking through the widget embedded on a partner’s page, with the partner vouching for their identity.
• api: first seen on a booking created through this API.
• website_newsletter: first seen signing up to the newsletter on the restaurant’s website.

marketing_email_consentboolean

Whether the guest agreed to receive marketing e-mail from the restaurant.

marketing_email_consent_atstring (date-time)facultatifnullable

When marketing_email_consent last became true, ISO 8601 with the restaurant’s UTC offset. null while consent is false.

marketing_sms_consentboolean

Whether the guest agreed to receive marketing text messages from the restaurant.

marketing_sms_consent_atstring (date-time)facultatifnullable

When marketing_sms_consent last became true, ISO 8601 with the restaurant’s UTC offset. null while consent is false.

visit_countinteger

How many of the guest’s bookings ended with them seated (seated, partially_seated or completed). Recomputed hourly, so it can trail a visit by up to about two hours.

no_show_countinteger

How many of the guest’s bookings ended no_show. Recomputed like visit_count.

cancellation_countinteger

How many of the guest’s bookings were cancelled, counting only bookings whose time has passed — a cancelled booking for next month is not counted until then. Recomputed like visit_count.

first_visit_atstring (date-time)facultatifnullable

When the guest’s earliest visit (a booking counted in visit_count) started: ISO 8601 with the restaurant’s UTC offset, on the calendar day it actually started — a seating after midnight carries the next day’s date. null until they have one. Recomputed like visit_count.

last_visit_atstring (date-time)facultatifnullable

When the guest’s latest visit started, in the same format as first_visit_at. null until they have one. Recomputed like visit_count.

created_atstring (date-time)

When the profile was created: ISO 8601 with the restaurant’s UTC offset.

updated_atstring (date-time)

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

L’objet entier est une donnée client

Il n’existe pas de vue partielle d’une fiche. Tous les chemins qui y mènent — GET /v1/guests, GET /v1/guests/{id}, ?expand=guest — demandent la portée guests:read, et une clé qui ne l’a pas reçoit un 403 insufficient_scope plutôt qu’un objet allégé. C’est la différence avec une réservation, où la même portée protège quatre champs et où le reste revient de toute façon. Voir Authentification.

Les compteurs — visit_count, no_show_count, cancellation_count — et les marqueurs du restaurant sont le registre du restaurant sur ce client, pas le vôtre. Ils bougent quand son personnel travaille la salle.

Les identifiants survivent à une fusion

Le restaurant fusionne les fiches en double, et le gst_… absorbé continue de se résoudre : GET /v1/guests/{identifiant_absorbé} renvoie la fiche survivante, sous l’identifiant de celle-ci. Comparez l’id reçu à celui que vous avez envoyé pour le remarquer. Un webhook guest.merged annonce la fusion au moment où elle a lieu et une défusion s’annonce de la même façon — les deux sont dans le catalogue d’événements.

Ce que porte un webhook

Chaque livraison guest.* met la fiche entière dans data.object, coordonnées comprises, quelles que soient les portées de la clé derrière le point de terminaison. Une fiche vous parvient aussi attachée à une réservation, et là la règle est celle de la réservation — voir L’objet réservation.