Réservations

Vue d'ensemble#

Les réservations sont disponibles à partir de l'offre Pro ; dans un établissement en offre Starter, les routes répondent 403 plan_required. La lecture nécessite reservations:read ; la création, la modification et le changement de statut, reservations:write.

Une réservation porte le début, la durée, le nombre de personnes, les tables, la source (guest, staff ou api), le statut et, concernant le client, seulement son nom. Le numéro de téléphone et l'e-mail transmis lors de la création restent dans Flavoso.

{
  "object": "reservation",
  "id": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "code": "R7K2Q9",
  "status": "confirmed",
  "starts_at": "2026-10-10T17:30:00.000Z",
  "duration_minutes": 120,
  "party_size": 4,
  "table_ids": [
    "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
  ],
  "source": "staff",
  "guest_name": "Alex Example",
  "note": "Window seat if possible",
  "created_at": "2026-10-04T12:00:00.000Z",
  "updated_at": "2026-10-04T12:00:00.000Z"
}

Les statuts#

Confirmer, refuser et annuler envoient un e-mail au client s'il a laissé une adresse ; lors d'une annulation, l'équipe reçoit une notification. seated, done, no_show et chaque retour en arrière sont silencieux. Tout autre changement, ou un changement hors de sa plage horaire, répond 409 invalid_transition et indique les statuts possibles à ce moment. Si la réservation est déjà au statut cible, elle est renvoyée inchangée.

Créneaux libres#

GET /reservations/availability?date=YYYY-MM-DD&party_size=N renvoie les horaires d'une journée avec available par horaire, ainsi que la durée (duration_minutes) et le fuseau horaire. La grille suit les horaires d'ouverture et les jours particuliers comme sur la page de réservation ; pour le reste, les règles d'une réservation faite par l'équipe s'appliquent : toutes les tables comptent, même celles qui ne sont pas réservables en ligne, il n'y a ni délai minimal ni horizon, et les réservations en ligne n'ont pas besoin d'être activées. Les horaires passés figurent dans la liste, mais ne sont jamais libres.

curl "https://api.flavoso.com/v1/reservations/availability?date=2026-10-10&party_size=4" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Créer#

POST /reservations crée une réservation, selon les mêmes règles que ci-dessus. starts_at doit être exactement l'un des horaires de GET /reservations/availability ; un autre horaire, un horaire passé ou un horaire où aucune table adaptée n'est libre donne 409 slot_unavailable.

curl -X POST https://api.flavoso.com/v1/reservations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-48211" \
  -d '{
  "starts_at": "2026-10-10T17:30:00Z",
  "party_size": 4,
  "guest_name": "Alex Example",
  "guest_phone": "+49 151 00000000",
  "note": "Window seat if possible",
  "status": "confirmed",
  "notify_guest": false
}'

Modifier et changer le statut#

PATCH /reservations/{id} modifie starts_at, party_size, duration_minutes, table_ids et note. Le nouvel horaire n'a pas besoin d'être dans la grille, et sans tables, PATCH ne vérifie aucune place ; si la réservation occupe ensuite une table déjà prise à cet horaire, Flavoso répond 409 slot_unavailable (table_ids: [] libère les tables). Une réservation annulée ou refusée ne peut plus être modifiée, et une réservation installée, partie ou absente ne peut être déplacée qu'à un horaire déjà commencé (sinon 409 invalid_transition). Tout est vérifié d'abord, puis enregistré en une seule étape : un 409 signifie que rien n'a été modifié et qu'aucun e-mail n'est parti. Avec notify_guest (par défaut true), le client reçoit un e-mail quand l'horaire ou le nombre de personnes d'une réservation en attente ou confirmée change. Le statut se change avec POST /reservations/{id}/status.

# Two more people and half an hour later
curl -X PATCH https://api.flavoso.com/v1/reservations/RESERVATION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"party_size": 6, "starts_at": "2026-10-10T18:00:00Z"}'

# The party has arrived
curl -X POST https://api.flavoso.com/v1/reservations/RESERVATION_ID/status \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "seated"}'

Le carnet de réservations d'une journée#

Avec starts_from et starts_until, GET /reservations renvoie les réservations d'une période, par début croissant. Pour une soirée dans l'établissement, prenez de minuit à minuit dans son fuseau horaire, converti en UTC. Pour synchroniser avec votre système, utilisez updated_since comme pour les commandes.

# Saturday's book in Berlin (UTC+2): local midnight to local midnight, sorted by start
curl "https://api.flavoso.com/v1/reservations?starts_from=2026-10-09T22:00:00Z&starts_until=2026-10-10T22:00:00Z&status=pending,confirmed" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Tables et zones#

GET /tables et GET /areas (avec store:read ou reservations:read) renvoient les tables avec leurs places, leur zone, leur caractère réservable en ligne et le nombre minimum de personnes, ainsi que les zones. C'est ainsi que vous faites correspondre table_ids. La clé du QR code d'une table n'y figure jamais.

curl https://api.flavoso.com/v1/tables -H "Authorization: Bearer $ACCESS_TOKEN"
curl https://api.flavoso.com/v1/areas -H "Authorization: Bearer $ACCESS_TOKEN"

Événements#

reservation.created arrive pour chaque nouvelle réservation, reservation.updated pour chaque changement de statut, d'heure, de nombre de personnes, de durée, de tables ou de remarque, avec changed. Quand l'établissement supprime une réservation, un dernier reservation.updated arrive avec changed: ["deleted"] et deleted_at ; ensuite, elle répond 404.