Reservas

Visión general#

Las reservas están disponibles a partir del plan Pro; en un negocio con el plan Starter, las rutas responden con 403 plan_required. Para leer hace falta reservations:read; para crear, cambiar y fijar el estado, reservations:write.

Una reserva lleva inicio, duración, número de personas, mesas, origen (guest, staff o api), estado y, del cliente, solo el nombre. El teléfono y el e-mail que se envían al crearla se quedan en 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"
}

Los estados#

Confirmar, rechazar y cancelar envían un e-mail al cliente si dejó una dirección; con una cancelación, el equipo recibe un aviso. seated, done, no_show y cada vuelta atrás no envían ningún aviso. Cualquier otro cambio, o uno fuera de su franja horaria, responde con 409 invalid_transition e indica los estados posibles en ese momento. Si la reserva ya está en el estado de destino, vuelve sin cambios.

Horas libres#

GET /reservations/availability?date=YYYY-MM-DD&party_size=N devuelve las horas de un día con available por hora, además de la duración (duration_minutes) y la zona horaria. La rejilla sigue los horarios de apertura y los días especiales, como en la página de reservas; por lo demás, rigen las reglas de una reserva hecha por el equipo: cuentan todas las mesas, también las que no se pueden reservar online, no hay antelación mínima ni plazo máximo de reserva, y las reservas online no tienen que estar activadas. Las horas pasadas aparecen en la lista, pero nunca están libres.

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

Crear#

POST /reservations crea una reserva, con las mismas reglas que arriba. starts_at tiene que ser exactamente una de las horas de GET /reservations/availability; otra hora, una pasada o una en la que no hay ninguna mesa adecuada libre da 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
}'

Cambiar y fijar el estado#

PATCH /reservations/{id} cambia starts_at, party_size, duration_minutes, table_ids y note. La hora nueva no tiene que estar en la rejilla, y sin mesas PATCH no comprueba plazas; si después la reserva ocupa una mesa que a esa hora ya está ocupada, Flavoso responde con 409 slot_unavailable (table_ids: [] libera las mesas). Una reserva cancelada o rechazada ya no se puede cambiar, y una cuyo cliente ya está sentado, se fue o no se presentó solo se puede mover a una hora que ya ha empezado (si no, 409 invalid_transition). Primero se comprueba todo y después se guarda en un solo paso: un 409 significa que no se ha cambiado nada y que no ha salido ningún e-mail. Con notify_guest (por defecto true), el cliente recibe un e-mail cuando cambian la hora o el número de personas de una reserva pendiente o confirmada. El estado lo fija 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"}'

El libro de reservas de un día#

Con starts_from y starts_until, GET /reservations devuelve las reservas de un periodo, en orden ascendente por inicio. Para una noche en el negocio, usa el intervalo de medianoche a medianoche en su zona horaria, convertido a UTC. Para conciliar con tu sistema, usa updated_since, como con los pedidos.

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

Mesas y zonas#

GET /tables y GET /areas (con store:read o reservations:read) devuelven las mesas con sus plazas, su zona, si se pueden reservar online y el número mínimo de personas, y las zonas. Con ellas asignas table_ids. La clave del código QR de una mesa nunca aparece.

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

Eventos#

reservation.created llega con cada reserva nueva; reservation.updated, con cada cambio de estado, hora, número de personas, duración, mesas o nota, con changed. Si el negocio borra una reserva, llega un último reservation.updated con changed: ["deleted"] y deleted_at; después, la reserva responde con 404.