API de platillos: crear, editar y filtrar menú en CUSCATLECO

El módulo de platillos gestiona el catálogo del menú del restaurante. Los endpoints de creación y edición aceptan imágenes mediante multipart/form-data, lo que permite subir fotografías de cada platillo. Las operaciones de lectura requieren el permiso ver_menu, mientras que la creación, edición y cambio de disponibilidad requieren gestionar_menu. Todos los endpoints requieren sesión activa y registran auditoría.

Los endpoints POST /api/platillos y PUT /api/platillos/:id usan Content-Type: multipart/form-data. No envíes application/json en estas solicitudes, ya que el servidor no procesará el archivo de imagen.

POST /api/platillos

Crea un nuevo platillo en el menú. El nombre debe ser único. Si se adjunta un archivo de imagen, se almacena en el servidor y se guarda la ruta relativa /uploads/<nombre_archivo>. Permiso requerido: gestionar_menu
Content-Type: multipart/form-data

Cuerpo de la solicitud

id_categoria

integer

required

ID de la categoría a la que pertenece el platillo. Las categorías disponibles son: Entradas, Platos Fuertes, Bebidas, Postres.

platillo_nombre

string

required

Nombre del platillo. Debe ser único en el sistema (máximo 100 caracteres).

platillo_precio

number

required

Precio del platillo en dólares. Acepta hasta dos decimales. Ejemplo: 12.50.

platillo_descripcion

string

Descripción del platillo, ingredientes o presentación. Texto libre.

platillo_disponible

boolean

Disponibilidad inicial del platillo. Si se omite, el valor por defecto es true.

imagen

file

Archivo de imagen del platillo (JPEG, PNG, etc.). El campo del formulario debe llamarse exactamente imagen. Si se omite, platillo_imagen_url queda como null.

Respuesta exitosa — 200

mensaje

string

Mensaje de confirmación: "Platillo creado correctamente".

id_platillo

integer

ID asignado al nuevo platillo.

Ejemplo

cURL

curl -X POST http://localhost:3000/api/platillos \
  -b cookies.txt \
  -F "id_categoria=2" \
  -F "platillo_nombre=Pupusa de Chicharrón" \
  -F "platillo_descripcion=Pupusa rellena de chicharrón molido con curtido y salsa de tomate" \
  -F "platillo_precio=3.50" \
  -F "platillo_disponible=true" \
  -F "imagen=@/ruta/a/pupusa.jpg"

Respuesta 200

{
  "mensaje": "Platillo creado correctamente",
  "id_platillo": 15
}

Errores

Código	Descripción
`400`	Faltan campos requeridos (`id_categoria`, `platillo_nombre` o `platillo_precio`), o el nombre ya existe.
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_menu`.

GET /api/platillos

Lista todos los platillos del menú. Los usuarios con rol Administrador ven todos los platillos incluyendo los no disponibles. El resto de roles solo ven platillos con platillo_disponible = true. Permiso requerido: ver_menu

Parámetros de consulta

categoria_id

integer

Filtra platillos por categoría. Ejemplo: ?categoria_id=2.

nombre

string

Filtra por nombre del platillo (búsqueda parcial, sin distinción de mayúsculas). Ejemplo: ?nombre=pupusa.

orderBy

string

default:"nombre"

Campo por el que ordenar. Valores válidos: nombre, precio.

orderDir

string

default:"ASC"

Dirección del orden. Valores válidos: ASC, DESC.

Respuesta exitosa — 200

Retorna un array de objetos platillo.

id_platillo

integer

Identificador único del platillo.

id_categoria

integer

ID de la categoría del platillo.

categoria_nombre

string

Nombre de la categoría. Ejemplo: "Platos Fuertes".

platillo_nombre

string

Nombre del platillo.

platillo_descripcion

string

Descripción del platillo. Puede ser null.

platillo_precio

number

Precio del platillo en dólares.

platillo_imagen_url

string

Ruta relativa de la imagen. Ejemplo: "/uploads/pupusa.jpg". Puede ser null.

platillo_disponible

boolean

Indica si el platillo está disponible para pedidos.

fecha_creacion

string

Fecha de creación en formato YYYY-MM-DD.

fecha_actualizacion

string

Fecha de la última actualización en formato YYYY-MM-DD.

actualizado_por

string

Nombre del usuario que realizó la última modificación. Puede ser null.

Ejemplo

cURL

curl "http://localhost:3000/api/platillos?orderBy=precio&orderDir=ASC" \
  -b cookies.txt

Respuesta 200

[
  {
    "id_platillo": 15,
    "id_categoria": 2,
    "categoria_nombre": "Platos Fuertes",
    "platillo_nombre": "Pupusa de Chicharrón",
    "platillo_descripcion": "Pupusa rellena de chicharrón molido",
    "platillo_precio": 3.50,
    "platillo_imagen_url": "/uploads/pupusa.jpg",
    "platillo_disponible": true,
    "fecha_creacion": "2026-05-20",
    "fecha_actualizacion": "2026-05-20",
    "actualizado_por": "Administrador"
  }
]

GET /api/platillos/:id

Obtiene un platillo específico por su ID. Los roles que no son Administrador solo pueden acceder a platillos con platillo_disponible = true. Permiso requerido: ver_menu

Parámetros de ruta

integer

required

ID del platillo a consultar.

Respuesta exitosa — 200

id_platillo

integer

Identificador único del platillo.

id_categoria

integer

ID de la categoría del platillo.

categoria_nombre

string

Nombre de la categoría.

platillo_nombre

string

Nombre del platillo.

platillo_descripcion

string

Descripción del platillo.

platillo_precio

number

Precio del platillo.

platillo_imagen_url

string

Ruta relativa de la imagen del platillo.

platillo_disponible

boolean

Disponibilidad actual del platillo.

Ejemplo

cURL

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

Respuesta 200

{
  "id_platillo": 15,
  "id_categoria": 2,
  "categoria_nombre": "Platos Fuertes",
  "platillo_nombre": "Pupusa de Chicharrón",
  "platillo_descripcion": "Pupusa rellena de chicharrón molido",
  "platillo_precio": 3.50,
  "platillo_imagen_url": "/uploads/pupusa.jpg",
  "platillo_disponible": true
}

Errores

Código	Descripción
`401`	Sesión no activa.
`403`	Sin permiso `ver_menu`.
`404`	Platillo no encontrado, o no está disponible y el usuario no es Administrador.

PUT /api/platillos/:id

Edita un platillo existente. Solo se pueden editar platillos que están activos (platillo_disponible = true). Si no se adjunta una nueva imagen, se conserva la imagen existente. Permiso requerido: gestionar_menu
Content-Type: multipart/form-data

Parámetros de ruta

integer

required

ID del platillo a editar.

Cuerpo de la solicitud

id_categoria

integer

required

ID de la categoría del platillo.

platillo_nombre

string

required

Nombre actualizado del platillo. Si cambia, no debe coincidir con el nombre de otro platillo.

platillo_precio

number

required

Precio actualizado del platillo.

platillo_descripcion

string

Descripción actualizada del platillo.

imagen

file

Nueva imagen del platillo. Si se omite, se conserva la imagen actual. El campo debe llamarse imagen.

Respuesta exitosa — 200

mensaje

string

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

Ejemplo

cURL

curl -X PUT http://localhost:3000/api/platillos/15 \
  -b cookies.txt \
  -F "id_categoria=2" \
  -F "platillo_nombre=Pupusa de Chicharrón y Queso" \
  -F "platillo_descripcion=Pupusa rellena de chicharrón y queso con curtido" \
  -F "platillo_precio=4.00" \
  -F "imagen=@/ruta/a/nueva_pupusa.jpg"

Respuesta 200

{
  "mensaje": "Platillo actualizado correctamente"
}

Errores

Código	Descripción
`400`	El nombre ya existe en otro platillo.
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_menu`, o el platillo está inactivo (`platillo_disponible = false`).
`404`	Platillo no encontrado.

PATCH /api/platillos/:id/estado

Activa o desactiva la disponibilidad de un platillo sin modificar sus demás datos. Un platillo desactivado no aparece en el menú para roles que no sean Administrador. Permiso requerido: gestionar_menu

Parámetros de ruta

integer

required

ID del platillo al que se desea cambiar la disponibilidad.

Cuerpo de la solicitud

platillo_disponible

boolean

required

Nuevo estado de disponibilidad. true para activar, false para desactivar.

Respuesta exitosa — 200

mensaje

string

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

Ejemplo

cURL

curl -X PATCH http://localhost:3000/api/platillos/15/estado \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "platillo_disponible": false
  }'

Respuesta 200

{
  "mensaje": "Estado del platillo actualizado correctamente"
}

Errores

Código	Descripción
`400`	El campo `platillo_disponible` no fue enviado.
`401`	Sesión no activa.
`403`	Sin permiso `gestionar_menu`.
`404`	Platillo no encontrado.

Autenticación

Endpoints

POST /api/platillos

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores

GET /api/platillos

Parámetros de consulta

Respuesta exitosa — 200

Ejemplo

GET /api/platillos/:id

Parámetros de ruta

Respuesta exitosa — 200

Ejemplo

Errores

PUT /api/platillos/:id

Parámetros de ruta

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores

PATCH /api/platillos/: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/platillos

​Cuerpo de la solicitud

​Respuesta exitosa — 200

​Ejemplo

​Errores

​GET /api/platillos

​Parámetros de consulta

​Respuesta exitosa — 200

​Ejemplo

​GET /api/platillos/:id

​Parámetros de ruta

​Respuesta exitosa — 200

​Ejemplo

​Errores

​PUT /api/platillos/:id

​Parámetros de ruta

​Cuerpo de la solicitud

​Respuesta exitosa — 200

​Ejemplo

​Errores

​PATCH /api/platillos/:id/estado

​Parámetros de ruta

​Cuerpo de la solicitud

​Respuesta exitosa — 200

​Ejemplo

​Errores

Build docs developers (and LLMs) love

POST /api/platillos

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores

GET /api/platillos

Parámetros de consulta

Respuesta exitosa — 200

Ejemplo

GET /api/platillos/:id

Parámetros de ruta

Respuesta exitosa — 200

Ejemplo

Errores

PUT /api/platillos/:id

Parámetros de ruta

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores

PATCH /api/platillos/:id/estado

Parámetros de ruta

Cuerpo de la solicitud

Respuesta exitosa — 200

Ejemplo

Errores