Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/123048152-JJDS/CafeteriaPM_S203/llms.txt

Use this file to discover all available pages before exploring further.

CafeteriaPM’s order management system covers the full journey from a waiter creating an order at the table through kitchen preparation to cashier payment. Orders are associated with a table and a waiter, contain one or more product line items (each with optional text observations), and advance through six states with validated transitions. Every state change is recorded in historial_estados_pedido, giving you a complete audit trail for every order.

​
Creating an Order

POST /pedidos/ creates a new order in the pendiente state. The endpoint is restricted to the mesero and admin roles. Required fields:
  • id_mesa — the ID of the table being served
  • detalles — an array of one or more line items
Each line item requires:
  • id_producto — the product ID
  • cantidad — the number of units ordered
  • observacion (optional) — a free-text instruction stored in detalle_observaciones (e.g., "sin azúcar", "extra picante")
The API validates that the table exists and that every product in detalles exists and has disponible == true. The product’s current precio is captured in precio_unitario at the moment of order creation — subsequent price changes do not affect existing orders. 
{
  "id_mesa": 3,
  "detalles": [
    {"id_producto": 1, "cantidad": 2, "observacion": "sin azúcar"},
    {"id_producto": 5, "cantidad": 1}
  ]
}
A successful response returns 201 Created with the full OrderOut object, including the generated order ID and computed total.

​
Filtering Orders

GET /pedidos/ returns a list of orders and supports several query parameters for filtering and pagination. Any authenticated user may call this endpoint.
ParameterTypeDescription
estado_idintegerFilter by order state ID (see GET /pedidos/estados)
mesa_idintegerFilter to orders belonging to a specific table
fecha_iniciostringISO 8601 date — include orders created on or after this date
fecha_finstringISO 8601 date — include orders created on or before this date
busquedastringIf numeric, matches the order ID exactly; otherwise performs a case-insensitive search on the table’s display number
limitintegerMaximum number of results to return
offsetintegerNumber of results to skip (for pagination)
Results are ordered newest-first (id DESC). Each result includes total computed from line item subtotals. Use GET /pedidos/estados to retrieve all valid state IDs and names.

​
Kitchen Queue

GET /pedidos/cola-cocina returns all orders currently in the pendiente or en_preparacion states, sorted oldest first (created_at ASC). This is the primary endpoint for kitchen display screens and is accessible to any authenticated user. The oldest orders appear at the top so kitchen staff can work through them in the order they were received without needing to sort manually.

​
PDF Tickets

GET /pedidos/{id}/ticket/pdf generates a downloadable PDF ticket for a specific order using ReportLab. The ticket is returned as an application/pdf response with the header: 
Content-Disposition: attachment; filename=ticket_pedido_{id}.pdf
The ticket includes:
  • Title: “CafeteriaPM - Ticket de Venta”
  • Order info: order number, table number, and date/time
  • Line item table: quantity, product name, unit price, and subtotal for each detail
  • Total row: sum of all subtotals
  • Footer: “¡Gracias por su visita!”
Role restriction: admin, caja, mesero

​
State Transitions

Orders advance through a validated state machine. The API enforces allowed transitions and rejects invalid moves with 400 Bad Request. Use PATCH /pedidos/{id}/estado with {"id_estado_nuevo": <state_id>} to move an order forward. Quick reference for common transitions: 
// Assign to kitchen (pendiente → en_preparacion)
{"id_estado_nuevo": 2}

// Mark ready — triggers automatic stock deduction (en_preparacion → listo)
{"id_estado_nuevo": 3}

// Mark as delivered (listo → entregado)
{"id_estado_nuevo": 4}
The full allowed transition map is:
FromAllowed destinations
pendienteen_preparacion, cancelado
en_preparacionlisto, cancelado
listoentregado, pagado, cancelado
entregadopagado, cancelado
pagado(none — terminal state)
cancelado is a special destination: the API allows transitioning any order to cancelado regardless of its current state, bypassing the normal transition map. Transitioning to pagado is normally done automatically by POST /ventas/, but can also be reached directly from listo.
When an order transitions to listo, the API calls descontar_ingredientes() internally. This deducts the ingredient quantities defined in each product’s recipe from stock_actual. If any ingredient has insufficient stock, the transition is rejected with 400 and no stock is changed.
For the complete state machine diagram and reserved-state behavior, see Order Lifecycle.

​
Deleting Orders

DELETE /pedidos/{id} is restricted to the admin role and only succeeds when the order is in the cancelado state. Attempting to delete an order in any other state returns 400 Bad Request with the message "Solo se pueden eliminar pedidos cancelados".If the order has an associated sale record (ventas table), the deletion is also blocked with 400 Bad Request: "No se puede eliminar el pedido porque tiene una venta asociada." In this case the order should remain in the system for financial record-keeping.
To safely remove an unwanted order, first transition it to cancelado via PATCH /pedidos/{id}/estado, then call DELETE /pedidos/{id}.

Build docs developers (and LLMs) love

Get started for freeTalk to us