Reservations API — Manage and Convert Table Reservations

The Reservations API handles the full lifecycle of a table booking: walk-in and online creation, staff confirmation, availability queries, and one-click conversion to an active order. The system automatically marks overdue reservations as no_asistio whenever the reservation list is fetched. There are two route groups — a public route that requires no authentication (for customer-facing booking forms) and a set of authenticated routes for restaurant staff.

Reservation object

number

Unique reservation identifier.

cliente_id

number | null

Linked customer record ID.

mesa_id

number

ID of the assigned table.

mesa_numero

number

Human-readable table number.

cantidad_personas

number

Number of guests in the party.

fecha_hora_inicio

string

Reservation start datetime (ISO 8601).

fecha_hora_fin

string

Reservation end datetime (ISO 8601).

estado

string

Current reservation state. One of pendiente, confirmada, cancelada, completada, or no_asistio.

observaciones

string | null

Optional notes from the customer or staff.

creado_en

string

ISO timestamp of when the reservation was created.

cliente_nombre

string | null

Name of the associated customer.

cliente_telefono

string | null

Phone number of the associated customer.

cliente_email

string | null

Email address of the associated customer.

Public routes (no authentication)

POST /api/public/reservations

Accepts a booking request from a customer without requiring an account. The server always creates a new customer record from the supplied contact details and assigns the most suitable available table if mesa_id is not specified. No de-duplication is performed on the customer data. POST /api/public/reservations

nombre

string

required

Customer’s full name. A new customer record is created in the database using this value.

telefono

string

required

Customer’s phone number. Used to identify the customer record.

fecha_hora_inicio

string

required

Reservation start datetime in a format accepted by MySQL (e.g. "2024-07-20 19:00:00").

fecha_hora_fin

string

required

Reservation end datetime. Must be after fecha_hora_inicio.

cantidad_personas

number

required

Number of guests. Used for automatic table selection — the server will pick the smallest available table with sufficient capacity.

mesa_id

number

Explicitly request a specific table. If omitted, the server auto-assigns one. Returns 400 if no tables are available.

string

Customer’s email address (optional).

observaciones

string

Special requests or notes for the reservation.

Example request

curl -X POST https://your-api-host/api/public/reservations \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Gabriela Ríos",
    "telefono": "5512345678",
    "email": "[email protected]",
    "fecha_hora_inicio": "2024-07-20 19:00:00",
    "fecha_hora_fin": "2024-07-20 21:00:00",
    "cantidad_personas": 3,
    "observaciones": "Preferimos mesa junto a la ventana"
  }'

Example response

{
  "message": "Reservacion creada correctamente",
  "id": 37
}

Public error responses

Status	Condition
`400`	One or more required fields are missing.
`400`	No tables are available for the requested time window and party size.
`409`	The explicitly requested `mesa_id` is already booked for that time window.
`500`	Server error.

Authenticated routes

All routes below require Authorization: Bearer <token>.

GET /api/reservations

Returns all reservations sorted by fecha_hora_inicio descending. Before returning results, the server automatically updates any past pendiente or confirmada reservations whose fecha_hora_fin has passed to no_asistio. Accepts an optional fecha query parameter (YYYY-MM-DD) to filter by start date.

# All reservations
curl https://your-api-host/api/reservations \
  -H "Authorization: Bearer <token>"

# Filter by date
curl "https://your-api-host/api/reservations?fecha=2024-07-20" \
  -H "Authorization: Bearer <token>"

GET /api/reservations/pendientes

Returns only reservations with estado = 'pendiente', sorted by start time ascending. Useful for the host’s confirmation queue.

curl https://your-api-host/api/reservations/pendientes \
  -H "Authorization: Bearer <token>"

GET /api/reservations/mesas-disponibles

Returns tables that have enough capacity and no conflicting pendiente or confirmada reservation in the specified time window. Query parameters (all required)

Parameter	Type	Description
`fecha_hora_inicio`	string	Window start (e.g. `2024-07-20 19:00:00`).
`fecha_hora_fin`	string	Window end.
`cantidad_personas`	number	Minimum required seating capacity.

curl "https://your-api-host/api/reservations/mesas-disponibles?fecha_hora_inicio=2024-07-20+19:00:00&fecha_hora_fin=2024-07-20+21:00:00&cantidad_personas=4" \
  -H "Authorization: Bearer <token>"

Returns an array of { id, numero, capacidad } objects, sorted by capacity ascending.

GET /api/reservations/:id

Returns a single reservation by ID. Returns 404 if not found.

curl https://your-api-host/api/reservations/37 \
  -H "Authorization: Bearer <token>"

POST /api/reservations

Creates a reservation from the staff side. The mesa_id is required (unlike the public endpoint, no auto-assignment is performed). The reservation checks for time conflicts before inserting.

mesa_id

number

required

ID of the table to reserve.

fecha_hora_inicio

string

required

Reservation start datetime.

fecha_hora_fin

string

required

Reservation end datetime.

cantidad_personas

number

required

Number of guests.

cliente_id

number

ID of an existing customer record to link.

observaciones

string

Staff notes.

Returns 409 if the table is already reserved for the overlapping window.

PUT /api/reservations/:id

Performs a full replacement update. All fields except observaciones are required.

mesa_id

number

required

New table ID.

fecha_hora_inicio

string

required

New start datetime.

fecha_hora_fin

string

required

New end datetime.

cantidad_personas

number

required

New party size.

estado

string

required

New state. Must be one of pendiente, confirmada, cancelada, completada, or no_asistio.

observaciones

string

Updated notes.

The time-conflict check excludes the reservation being updated, so rescheduling within the same slot is allowed.

PATCH /api/reservations/:id/estado

Updates only the reservation state. When the new state is cancelada or no_asistio, the table is freed to libre if it has no other active orders.

estado

string

required

One of pendiente, confirmada, cancelada, completada, or no_asistio.

curl -X PATCH https://your-api-host/api/reservations/37/estado \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "estado": "confirmada" }'

POST /api/reservations/:id/convertir-pedido

Converts a confirmada or pendiente reservation directly into an active order in a single transaction. The reservation is marked completada and the table is set to ocupada. Returns the new order ID. Roles: admin, mesero, cajero

mesero_id

number

required

ID of the waiter opening the order.

items

array

required

Order line items. Each must have producto_id and cantidad.

Show item object

producto_id

number

required

Menu product ID.

cantidad

number

required

Quantity.

precio_unitario

number

Price override; defaults to current product price.

observaciones

string

Per-item note.

observaciones

string

Order-level notes.

metodo_pago

string

Payment method if paying at seating: efectivo, tarjeta, qr, or transferencia.

curl -X POST https://your-api-host/api/reservations/37/convertir-pedido \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mesero_id": 5,
    "items": [
      { "producto_id": 12, "cantidad": 2 },
      { "producto_id": 3,  "cantidad": 1 }
    ]
  }'

{
  "id": 102,
  "message": "Pedido creado correctamente desde la reservacion"
}

The reservation must be in confirmada or pendiente state. Attempting to convert a cancelada, completada, or no_asistio reservation returns 400.

DELETE /api/reservations/:id

Permanently deletes a reservation record. Returns 404 if not found.

curl -X DELETE https://your-api-host/api/reservations/37 \
  -H "Authorization: Bearer <token>"

Authentication

Restaurant Operations

Billing & Reporting

Administration

Reservations API — Manage and Convert Table Reservations

Reservation object

Public routes (no authentication)

POST /api/public/reservations

Example request

Example response

Public error responses

Authenticated routes

GET /api/reservations

GET /api/reservations/pendientes

GET /api/reservations/mesas-disponibles

GET /api/reservations/:id

POST /api/reservations

PUT /api/reservations/:id

PATCH /api/reservations/:id/estado

POST /api/reservations/:id/convertir-pedido

DELETE /api/reservations/:id

Build docs developers (and LLMs) love

Authentication

Restaurant Operations

Billing & Reporting

Administration

Documentation Index

​Reservation object

​Public routes (no authentication)

​POST /api/public/reservations

​Example request

​Example response

​Public error responses

​Authenticated routes

​GET /api/reservations

​GET /api/reservations/pendientes

​GET /api/reservations/mesas-disponibles

​GET /api/reservations/:id

​POST /api/reservations

​PUT /api/reservations/:id

​PATCH /api/reservations/:id/estado

​POST /api/reservations/:id/convertir-pedido

​DELETE /api/reservations/:id

Build docs developers (and LLMs) love

Reservation object

Public routes (no authentication)

POST /api/public/reservations

Example request

Example response

Public error responses

Authenticated routes

GET /api/reservations

GET /api/reservations/pendientes

GET /api/reservations/mesas-disponibles

GET /api/reservations/:id

POST /api/reservations

PUT /api/reservations/:id

PATCH /api/reservations/:id/estado

POST /api/reservations/:id/convertir-pedido

DELETE /api/reservations/:id