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 tracks ingredient stock in real time. Each ingredient has a current stock level, a minimum threshold for low-stock alerts, and a unit cost. Products are linked to ingredients through recipe entries — when an order is marked listo, the API automatically deducts the ingredient quantities defined in each product’s recipe from stock_actual. This keeps your inventory accurate without any manual intervention after order preparation.

​
Ingredients

Each ingredient in the ingredientes table has the following fields:
FieldTypeDescription
nombrestringIngredient name (e.g., "Café molido", "Leche entera")
unidadstringUnit of measurement (e.g., "gramos", "litros", "unidades")
stock_actualdecimalCurrent quantity on hand; enforced >= 0 at the database level
stock_minimodecimalThreshold below which a low-stock alert is triggered
costo_unitariodecimalUnit cost used for product profitability margin calculations

​
Ingredient Endpoints

List all ingredients — GET /productos/ingredientes
Returns all ingredients ordered by ID ascending. Any authenticated user. Get a single ingredient — GET /productos/ingredientes/{id}
Returns one ingredient by ID. Any authenticated user. Low-stock alert list — GET /productos/ingredientes/stock-bajo
Returns every ingredient where stock_actual <= stock_minimo. Use this endpoint to drive reorder notifications. Any authenticated user. Create ingredient — POST /productos/ingredientes (admin, cocina)
All fields are required. Example: 
{
  "nombre": "Café molido",
  "unidad": "gramos",
  "stock_actual": 2000,
  "stock_minimo": 500,
  "costo_unitario": 0.08
}
Update ingredient — PATCH /productos/ingredientes/{id} (admin, cocina)
Accepts any subset of the ingredient fields. Only supplied fields are updated (exclude_none=True). Manual stock adjustment — PATCH /productos/ingredientes/{id}/ajustar-stock?cantidad=<float> (admin, cocina)
Adds cantidad to the ingredient’s current stock. Pass a positive value to increase stock and a negative value to decrease it. Returns 400 Bad Request if the resulting stock would go below zero. 
# Add 500 grams
PATCH /productos/ingredientes/1/ajustar-stock?cantidad=500

# Remove 100 grams
PATCH /productos/ingredientes/1/ajustar-stock?cantidad=-100
Response: {"message": "Stock actualizado", "stock_actual": <new_value>} Delete ingredient — DELETE /productos/ingredientes/{id} (admin only)
Blocked with 400 if the ingredient is referenced by any product recipe (producto_ingrediente) or purchase record (compras_suministros). Remove those associations first before deleting.

​
Product Recipes

A product’s recipe defines how much of each ingredient is consumed when one unit of that product is prepared. Recipes are set when creating a product via POST /productos/ using the ingredientes array. Roles: admin, cocina. 
{
  "nombre": "Café Americano",
  "precio": 25.00,
  "id_categoria": 1,
  "disponible": true,
  "ingredientes": [
    {"id_ingrediente": 1, "cantidad": 10},
    {"id_ingrediente": 3, "cantidad": 200}
  ]
}
Each recipe entry has two fields:
  • id_ingrediente — the ingredient to consume
  • cantidad — the amount of that ingredient consumed per single unit of the product
In the example above, making one Café Americano consumes 10 units of ingredient #1 and 200 units of ingredient #3. If a customer orders two, the deduction will be 20 and 400 respectively. To view an existing product’s full recipe, call GET /productos/{id} — it returns the ProductDetailOut schema which includes the ingredientes array with each ingredient’s name, unit, and quantity.

​
Automatic Stock Deduction

When an order is transitioned to the listo state via PATCH /pedidos/{id}/estado, the API automatically calls descontar_ingredientes() before committing the state change. The service works as follows:
  1. Aggregates requirements — for each line item in the order, it multiplies detalle.cantidad (units ordered) by each recipe ingredient’s cantidad (amount per unit). If the same ingredient appears in multiple products, its totals are summed.
  2. Validates stock — before touching any ingredient, it checks that every required ingredient has sufficient stock_actual. If any ingredient falls short, the entire transition is rejected with 400 Bad Request listing the ingredient name, available stock, and required amount.
  3. Applies deductions atomically — only after all ingredients pass the stock check are the deductions written to the database via db.flush(), ensuring no partial updates occur.
If descontar_ingredientes() raises a 400 error due to insufficient stock, the order state transition is also rejected. The order remains in en_preparacion until the stock issue is resolved (e.g., by recording a purchase or manually adjusting stock).

​
Registering Purchases

When you receive a supply delivery, record it with POST /compras/. This simultaneously creates an audit record in compras_suministros and increments the ingredient’s stock_actual by the purchased quantity. Roles: admin, cocina. 
{
  "id_ingrediente": 1,
  "cantidad": 500,
  "costo_total": 150.00,
  "fecha": "2024-01-15"
}
FieldTypeDescription
id_ingredienteintegerThe ingredient being restocked
cantidaddecimalUnits received (must be > 0)
costo_totaldecimalTotal purchase cost for this delivery
fechadateDate of the purchase (ISO 8601 date, not datetime)
The purchasing user is recorded automatically from the JWT token in id_usuario. To list all purchase history, call GET /compras/. Roles: admin, cocina.

​
Low-Stock Alerts

Two entry points surface low-stock information: Operational check: GET /productos/ingredientes/stock-bajo returns the full ingredient objects for all ingredients where stock_actual <= stock_minimo. Use this in dashboards or monitoring scripts. Dashboard KPI: GET /stats/dashboard returns a stock_bajo count — the number of ingredients currently at or below their minimum threshold — alongside today’s sales and active orders. Full inventory status: GET /stats/inventario-estado (admin, cocina) returns a comprehensive inventory snapshot including:
  • total_items — total number of ingredients
  • criticos — count of ingredients at or below minimum
  • ingredientes — array of all ingredients with an estado field set to either "Crítico" or "Ok"
  • movimientos — the 10 most recent purchase records with ingredient name, quantity, cost, and timestamp
Set meaningful stock_minimo values on all ingredients when initially configuring the system. Leaving stock_minimo at 0 (the default) means low-stock alerts will never trigger for those ingredients, even when they run out entirely.

Build docs developers (and LLMs) love

Get started for freeTalk to us