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.

Every order in CafeteriaPM passes through a well-defined lifecycle enforced by the API. The PATCH /pedidos/{id}/estado endpoint validates that each transition is allowed before updating the state. Critically, when an order transitions to listo (ready), the API automatically deducts the required ingredient quantities from stock by calling descontar_ingredientes() — no separate inventory step is needed.

​
Order States

Each state reflects a distinct phase in the order’s journey from placement to payment.
StateDescription
pendienteOrder has been created and is waiting to be picked up by the kitchen.
en_preparacionThe kitchen has acknowledged the order and started preparing it.
listoThe order is fully prepared and ready for the waiter to collect. Ingredient stock is deducted at this point.
entregadoThe order has been carried to the table and delivered to the customer.
pagadoPayment has been processed; a Venta record is created and linked to the order. Terminal state.
canceladoThe order was cancelled. Only cancelled orders can be permanently deleted. Terminal state.
reservadoA special state used by the table reservation system. This is not part of the normal order preparation flow.

​
Valid Transitions

The API enforces a strict transition graph. Any attempt to jump to a state not listed in the Allowed Next States column is rejected.
Current StateAllowed Next States
pendienteen_preparacion, cancelado
en_preparacionlisto, cancelado
listoentregado, pagado, cancelado
entregadopagado
pagado(terminal — no further transitions)
cancelado(terminal — order can only be deleted)
cancelado can be reached from any non-terminal state (pendiente, en_preparacion, listo, or entregado) as a special shortcut — the transition guard always permits a move to cancelado regardless of the current state.
Attempting an invalid transition returns 400 Bad Request with a descriptive message:
{
  "detail": "No se puede cambiar de 'pendiente' a 'pagado'"
}
Always follow the transition graph above. In particular, you cannot skip states (e.g. going directly from pendiente to listo) or reverse a completed transition.

​
Automatic Stock Deduction

When an order transitions to listo, the service calls descontar_ingredientes(db, pedido_id). This function:
  1. Loads every OrderDetail row for the order.
  2. For each detail, iterates over the product’s ProductoIngrediente recipe entries.
  3. Accumulates the total required quantity per ingredient as item.cantidad × recipe_quantity.
  4. Checks that every ingredient has sufficient stock_actual before applying any changes.
  5. Subtracts the accumulated quantities from each Ingrediente.stock_actual in a single atomic flush.
If any ingredient has insufficient stock, the entire deduction is aborted and the transition is rejected with 400 Bad Request. No partial deductions are applied. Example deduction: 
Order: 2× Café Americano
Recipe: Café Americano requires 10g Coffee, 200ml Water per unit

Accumulated requirement:
  Coffee → 2 × 10g  = 20g  deducted from stock
  Water  → 2 × 200ml = 400ml deducted from stock
You can inspect the resulting inventory levels through GET /stats/inventario-estado (requires admin or cocina role) to spot ingredients approaching their stock_minimo threshold.

​
Payment Flow

Once an order reaches listo or entregado, a cashier registers payment by calling POST /ventas/. This creates a Venta record linked to the order and automatically advances the order to pagado. 
curl -X POST http://localhost:8000/ventas/ \
  -H "Authorization: Bearer <caja_or_admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_pedido": 42,
    "id_metodo_pago": 1,
    "monto_recibido": 20.00
  }'
The Venta record stores the cashier ID, payment method, total amount, amount received, and timestamp. The computed cambio (change due) is derived from monto_recibido − monto_total.

​
History Tracking

Every state transition — including the initial pendiente creation — is recorded in the historial_estados_pedido table. Each row captures:
  • The state before the change (id_estado_origen, null for creation)
  • The state after the change (id_estado_destino)
  • The user who triggered the change (id_usuario)
  • The exact timestamp (cambiado_en)
This audit trail is immutable and cannot be modified through the API. It is included in order reports and is available to admins for dispute resolution or operational analysis.

​
Creating an Order — Full Flow Example

The following sequence walks through a complete order from placement to payment using curl. 
# 1. Create the order (mesero or admin role required)
curl -X POST http://localhost:8000/pedidos/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_mesa": 3,
    "detalles": [
      {"id_producto": 1, "cantidad": 2, "observacion": "sin azúcar"},
      {"id_producto": 5, "cantidad": 1}
    ]
  }'

# 2. Kitchen accepts the order — transition to en_preparacion (any authenticated role)
curl -X PATCH http://localhost:8000/pedidos/42/estado \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id_estado_nuevo": 2}'

# 3. Kitchen marks order ready — stock is deducted automatically (any authenticated role)
curl -X PATCH http://localhost:8000/pedidos/42/estado \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id_estado_nuevo": 3}'

# 4. Register payment — creates Venta and advances order to pagado (caja or admin role)
curl -X POST http://localhost:8000/ventas/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_pedido": 42,
    "id_metodo_pago": 1,
    "monto_recibido": 20.00
  }'
The id_estado_nuevo values correspond to the integer primary keys in the estados_pedido table. You can retrieve the full list of states and their IDs at any time by calling GET /pedidos/estados.

Build docs developers (and LLMs) love

Get started for freeTalk to us