Reservierungen

Überblick#

Reservierungen gibt es ab dem Tarif Pro; in einem Betrieb mit Starter antworten die Routen mit 403 plan_required. Lesen braucht reservations:read, anlegen, ändern und den Stand setzen reservations:write.

Eine Reservierung trägt Beginn, Dauer, Personenzahl, Tische, Quelle (guest, staff oder api), Stand und vom Gast nur den Namen. Telefonnummer und E-Mail, die beim Anlegen mitkommen, bleiben in 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"
}

Die Stände#

Bestätigen, Ablehnen und Absagen schicken dem Gast eine E-Mail, wenn er eine Adresse hinterlassen hat; bei einer Absage bekommt das Team eine Meldung. seated, done, no_show und jedes Zurück sind still. Ein anderer Wechsel, oder einer außerhalb seiner Zeit, antwortet mit 409 invalid_transition und nennt die Stände, die gerade gehen. Steht die Reservierung schon auf dem Ziel, kommt sie unverändert zurück.

Freie Zeiten#

GET /reservations/availability?date=YYYY-MM-DD&party_size=N liefert die Zeiten eines Tages mit available je Zeit, dazu die Dauer (duration_minutes) und die Zeitzone. Das Raster folgt den Öffnungszeiten und Sondertagen wie auf der Buchungsseite; sonst gelten die Regeln einer Buchung durch das Team: alle Tische zählen, auch die nicht online buchbaren, es gibt keinen Vorlauf und keinen Horizont, und Online-Reservierungen müssen nicht eingeschaltet sein. Vergangene Zeiten stehen in der Liste, sind aber nie frei.

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

Anlegen#

POST /reservations legt eine Reservierung an, nach denselben Regeln wie oben. starts_at muss genau eine der Zeiten aus GET /reservations/availability sein; eine andere Zeit, eine vergangene oder eine, zu der kein passender Tisch frei ist, ergibt 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
}'

Ändern und den Stand setzen#

PATCH /reservations/{id} ändert starts_at, party_size, duration_minutes, table_ids und note. Die neue Zeit muss nicht im Raster liegen, und ohne Tische prüft PATCH keine Plätze; hält die Reservierung danach einen Tisch, der zu dieser Zeit schon vergeben ist, antwortet Flavoso mit 409 slot_unavailable (table_ids: [] gibt die Tische frei). Eine abgesagte oder abgelehnte Reservierung lässt sich nicht mehr ändern, und eine, die sitzt, gegangen oder nicht erschienen ist, nur auf eine Zeit verschieben, die schon begonnen hat (sonst 409 invalid_transition). Erst wird alles geprüft, dann in einem Schritt gespeichert: ein 409 heißt, dass nichts geändert ist und keine Mail hinausging. Mit notify_guest (Vorgabe true) bekommt der Gast eine Mail, wenn sich Zeit oder Personenzahl einer offenen oder bestätigten Reservierung ändern. Den Stand setzt 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"}'

Das Reservierungsbuch eines Tages#

Mit starts_from und starts_until liefert GET /reservations die Reservierungen eines Zeitraums, aufsteigend nach Beginn. Für einen Abend im Betrieb nimmst du Mitternacht bis Mitternacht in seiner Zeitzone, umgerechnet in UTC. Zum Abgleich mit deinem System nimmst du updated_since wie bei Bestellungen.

# 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"

Tische und Bereiche#

GET /tables und GET /areas (mit store:read oder reservations:read) liefern die Tische mit Plätzen, Bereich, ob online buchbar und Mindestpersonenzahl, und die Bereiche. Damit ordnest du table_ids zu. Der Schlüssel im QR-Code eines Tisches steht nie darin.

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

Ereignisse#

reservation.created kommt bei jeder neuen Reservierung, reservation.updated bei jeder Änderung von Stand, Zeit, Personenzahl, Dauer, Tischen oder Anmerkung, mit changed. Löscht der Betrieb eine Reservierung, kommt ein letztes reservation.updated mit changed: ["deleted"] und deleted_at; danach antwortet sie mit 404.