Prenotazioni

Panoramica#

Le prenotazioni sono disponibili dal piano Pro; in un locale con Starter gli endpoint rispondono 403 plan_required. La lettura richiede reservations:read; creare, modificare e impostare lo stato richiedono reservations:write.

Una prenotazione contiene inizio, durata, numero di persone, tavoli, origine (guest, staff o api), stato e, del cliente, solo il nome. Numero di telefono ed e-mail inviati alla creazione restano 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"
}

Gli stati#

Confermare, rifiutare e annullare inviano un'e-mail al cliente, se ha lasciato un indirizzo; con un annullamento il team riceve una notifica. seated, done, no_show e ogni passo indietro sono silenziosi. Qualsiasi altro cambio, o uno fuori dal suo orario, risponde 409 invalid_transition e indica gli stati possibili in quel momento. Se la prenotazione è già nello stato di destinazione, torna invariata.

Orari liberi#

GET /reservations/availability?date=YYYY-MM-DD&party_size=N restituisce gli orari di un giorno con available per ogni orario, più la durata (duration_minutes) e il fuso orario. La griglia segue gli orari di apertura e i giorni speciali come nella pagina di prenotazione; per il resto valgono le regole di una prenotazione fatta dal team: contano tutti i tavoli, anche quelli non prenotabili online, non ci sono preavviso né orizzonte, e non serve che le prenotazioni online siano attive. Gli orari passati compaiono nell'elenco, ma non sono mai liberi.

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

Creare#

POST /reservations crea una prenotazione, con le stesse regole di sopra. starts_at deve essere esattamente uno degli orari di GET /reservations/availability; un altro orario, uno passato o uno in cui non c'è nessun tavolo adatto libero dà 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
}'

Modificare e impostare lo stato#

PATCH /reservations/{id} modifica starts_at, party_size, duration_minutes, table_ids e note. Il nuovo orario non deve per forza rientrare nella griglia, e senza tavoli PATCH non controlla i posti; se poi la prenotazione occupa un tavolo già preso a quell'orario, Flavoso risponde 409 slot_unavailable (table_ids: [] libera i tavoli). Una prenotazione annullata o rifiutata non si può più modificare, e una seduta, andata via o non presentata si può spostare solo a un orario già iniziato (altrimenti 409 invalid_transition). Prima si controlla tutto, poi si salva in un solo passaggio: un 409 significa che non è cambiato nulla e che non è partita alcuna e-mail. Con notify_guest (predefinito true) il cliente riceve un'e-mail quando cambiano orario o numero di persone di una prenotazione in attesa o confermata. Lo stato si imposta con 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"}'

Il libro prenotazioni di un giorno#

Con starts_from e starts_until, GET /reservations restituisce le prenotazioni di un periodo, in ordine crescente di inizio. Per una serata nel locale prendi da mezzanotte a mezzanotte nel suo fuso orario, convertito in UTC. Per sincronizzare con il tuo sistema usa updated_since come per gli ordini.

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

Tavoli e aree#

GET /tables e GET /areas (con store:read o reservations:read) restituiscono i tavoli con posti, area, prenotabilità online e numero minimo di persone, e le aree. Con questi associ i table_ids. La chiave nel codice QR di un tavolo non vi compare mai.

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

Eventi#

reservation.created arriva per ogni nuova prenotazione, reservation.updated per ogni modifica di stato, orario, numero di persone, durata, tavoli o nota, con changed. Se il locale elimina una prenotazione, arriva un ultimo reservation.updated con changed: ["deleted"] e deleted_at; dopodiché la prenotazione restituisce 404.