API de mesas: crear, listar y cambiar estado en CUSCATLECO

El módulo de mesas permite administrar el inventario de mesas del restaurante y controlar su estado en tiempo real. Las operaciones de creación y eliminación requieren el permiso gestionar_mesas, mientras que la consulta del listado requiere listar_mesas y el cambio de estado requiere actualizar_estado_mesa. Todos los endpoints requieren una sesión activa.

Los estados de mesa registran trazabilidad: cada cambio almacena el ID del usuario que lo realizó y la fecha y hora de actualización.

POST /api/mesas

Crea una nueva mesa en el sistema. El número de mesa debe ser único. Permiso requerido: gestionar_mesas

Cuerpo de la solicitud

mesa_numero

integer

required

Número identificador de la mesa. Debe ser único en el restaurante.

mesa_capacidad

integer

required

Capacidad máxima de personas. Debe ser mayor que 0.

mesa_estado

string

Estado inicial de la mesa. Si se omite, se asigna Disponible por defecto. Valores válidos: Disponible, Ocupada, Reservada, Limpieza, Mantenimiento.

mesa_ubicacion

string

Descripción de la ubicación física de la mesa. Ejemplos: Zona Interior, Terraza, Salón VIP.

Respuesta exitosa — 201

message

string

Mensaje de confirmación: "Mesa creada exitosamente".

integer

ID asignado a la nueva mesa.

Ejemplo

cURL

curl -X POST http://localhost:3000/api/mesas \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "mesa_numero": 9,
    "mesa_capacidad": 4,
    "mesa_ubicacion": "Terraza",
    "mesa_estado": "Disponible"
  }'

Respuesta 201

{
  "message": "Mesa creada exitosamente",
  "id": 9
}

Errores

Código	Descripción
`400`	Faltan campos requeridos, capacidad inválida, o el número de mesa ya existe.
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_mesas`.

POST /api/mesas/bulk

Crea múltiples mesas en una sola solicitud. Todas las mesas se crean con estado Disponible. El límite máximo es de 50 mesas por solicitud. Permiso requerido: gestionar_mesas

Cuerpo de la solicitud

mesas

object[]

required

Array de objetos de mesa. Máximo 50 elementos.

Show propiedades de cada mesa

mesa_numero

integer

required

Número de la mesa. Debe ser único en el request y en la base de datos.

mesa_capacidad

integer

required

Capacidad máxima de personas. Debe ser mayor que 0.

mesa_ubicacion

string

Descripción de la ubicación física.

Respuesta exitosa — 201

message

string

Mensaje con la cantidad de mesas creadas. Ejemplo: "5 mesas creadas".

firstId

integer

ID del primer registro insertado.

Ejemplo

cURL

curl -X POST http://localhost:3000/api/mesas/bulk \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "mesas": [
      { "mesa_numero": 10, "mesa_capacidad": 4, "mesa_ubicacion": "Terraza" },
      { "mesa_numero": 11, "mesa_capacidad": 6, "mesa_ubicacion": "Zona Interior" },
      { "mesa_numero": 12, "mesa_capacidad": 2, "mesa_ubicacion": "Barra" }
    ]
  }'

Respuesta 201

{
  "message": "3 mesas creadas",
  "firstId": 10
}

Errores

Código	Descripción
`400`	El array está vacío, supera el límite de 50, contiene números duplicados, o alguna mesa ya existe.
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_mesas`.

GET /api/mesas

Devuelve el listado completo de mesas del restaurante ordenadas por número de mesa de forma descendente. Permiso requerido: listar_mesas

Respuesta exitosa — 200

Retorna un array de objetos mesa.

id_mesa

integer

Identificador único de la mesa.

mesa_numero

integer

Número visible de la mesa en el restaurante.

mesa_capacidad

integer

Número máximo de personas.

mesa_ubicacion

string

Zona o área del restaurante donde se encuentra.

mesa_estado

string

Estado actual de la mesa. Valores posibles: Disponible, Ocupada, Reservada, Limpieza, Mantenimiento.

mesa_actualizada_por

string

Nombre del último usuario que modificó la mesa. Puede ser null si nunca fue actualizada.

Ejemplo

cURL

curl http://localhost:3000/api/mesas \
  -b cookies.txt

Respuesta 200

[
  {
    "id_mesa": 8,
    "mesa_numero": 8,
    "mesa_capacidad": 8,
    "mesa_ubicacion": "Salón VIP",
    "mesa_estado": "Disponible",
    "mesa_actualizada_por": null
  },
  {
    "id_mesa": 3,
    "mesa_numero": 3,
    "mesa_capacidad": 6,
    "mesa_ubicacion": "Terraza",
    "mesa_estado": "Ocupada",
    "mesa_actualizada_por": "Carlos Pérez"
  }
]

DELETE /api/mesas/:id

Elimina permanentemente una mesa del sistema. Esta operación no se puede deshacer. Permiso requerido: gestionar_mesas

Parámetros de ruta

integer

required

ID de la mesa a eliminar.

Respuesta exitosa — 200

message

string

Mensaje de confirmación: "Mesa eliminada exitosamente".

Ejemplo

cURL

curl -X DELETE http://localhost:3000/api/mesas/9 \
  -b cookies.txt

Respuesta 200

{
  "message": "Mesa eliminada exitosamente"
}

Errores

Código	Descripción
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_mesas`.
`404`	No existe una mesa con el ID indicado.

PATCH /api/mesas/:id/estado

Actualiza el estado de una mesa específica. Los cambios quedan registrados en auditoría con el usuario que los realizó. Permiso requerido: actualizar_estado_mesa

Parámetros de ruta

integer

required

ID de la mesa cuyo estado se desea cambiar.

Cuerpo de la solicitud

mesa_estado

string

required

Nuevo estado de la mesa. Valores válidos: Disponible, Ocupada, Reservada, Limpieza, Mantenimiento.

Respuesta exitosa — 200

message

string

Mensaje de confirmación: "Estado actualizado correctamente".

Ejemplo

cURL

curl -X PATCH http://localhost:3000/api/mesas/3/estado \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "mesa_estado": "Limpieza"
  }'

Respuesta 200

{
  "message": "Estado actualizado correctamente"
}

Errores

Código	Descripción
`400`	El campo `mesa_estado` está ausente o el valor no es válido.
`401`	Sesión no activa.
`403`	Sin permiso `actualizar_estado_mesa`.
`404`	No existe una mesa con el ID indicado.

Autenticación

Endpoints

POST /api/mesas

Cuerpo de la solicitud

Respuesta exitosa — 201

Ejemplo

Errores

POST /api/mesas/bulk

Cuerpo de la solicitud

Respuesta exitosa — 201

Ejemplo

Errores

GET /api/mesas

Respuesta exitosa — 200

Ejemplo

DELETE /api/mesas/:id

Parámetros de ruta

Respuesta exitosa — 200

Ejemplo

Errores

PATCH /api/mesas/:id/estado

Parámetros de ruta

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores

Build docs developers (and LLMs) love

Autenticación

Endpoints

Documentation Index

​POST /api/mesas

​Cuerpo de la solicitud

​Respuesta exitosa — 201

​Ejemplo

​Errores

​POST /api/mesas/bulk

​Cuerpo de la solicitud

​Respuesta exitosa — 201

​Ejemplo

​Errores

​GET /api/mesas

​Respuesta exitosa — 200

​Ejemplo

​DELETE /api/mesas/:id

​Parámetros de ruta

​Respuesta exitosa — 200

​Ejemplo

​Errores

​PATCH /api/mesas/:id/estado

​Parámetros de ruta

​Cuerpo de la solicitud

​Respuesta exitosa — 200

​Ejemplo

​Errores

Build docs developers (and LLMs) love

POST /api/mesas

Cuerpo de la solicitud

Respuesta exitosa — 201

Ejemplo

Errores

POST /api/mesas/bulk

Cuerpo de la solicitud

Respuesta exitosa — 201

Ejemplo

Errores

GET /api/mesas

Respuesta exitosa — 200

Ejemplo

DELETE /api/mesas/:id

Parámetros de ruta

Respuesta exitosa — 200

Ejemplo

Errores

PATCH /api/mesas/:id/estado

Parámetros de ruta

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores