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 two financial flows: sales (revenue from completed orders) and expenses (operational costs such as supplies, utilities, or miscellaneous costs). The cashier role processes payments and logs expenses; the admin role can view all financial data and export reports. Both flows are time-stamped and filterable by date range, making end-of-day reconciliation and monthly reporting straightforward.

​
Processing a Sale

To charge an order, a cashier calls POST /ventas/. The order must already be in either listo or entregado state — the API rejects payment attempts on orders in any other state. What happens internally:
  1. The API validates that the order exists and is in listo or entregado
  2. It checks that the order has not already been paid (no existing ventas record)
  3. It validates the provided id_metodo_pago
  4. monto_total is calculated by summing all line item subtotal values from the order
  5. A Venta record is created in the ventas table
  6. The order state is automatically transitioned to pagado and recorded in historial_estados_pedido
{
  "id_pedido": 42,
  "id_metodo_pago": 1,
  "monto_recibido": 50.00
}
FieldTypeDescription
id_pedidointegerThe order being charged
id_metodo_pagointegerPayment method ID (see GET /ventas/metodos-pago)
monto_recibidodecimal(optional) Amount handed over by the customer
The response includes cambio (change due) calculated as monto_recibido - monto_total. If monto_recibido is not provided (common for card or digital payments), cambio will be null. A successful response returns 201 Created with the full sale record.

​
Payment Methods

Available payment methods are seeded into the metodos_pago table during setup. To retrieve the current list, call: 
GET /ventas/metodos-pago
Returns an array of objects: 
[
  {"id": 1, "nombre": "Efectivo", "descripcion": "Pago en efectivo"},
  {"id": 2, "nombre": "Tarjeta", "descripcion": "Tarjeta de crédito o débito"},
  {"id": 3, "nombre": "Transferencia", "descripcion": "Transferencia bancaria"}
]
Use the id value in POST /ventas/. This endpoint is accessible to any authenticated user.

​
Listing Sales

GET /ventas/ returns the sales history, ordered newest-first. Roles: admin, caja. Optional query parameters:
ParameterTypeDescription
fecha_iniciostringISO date string — include sales on or after this date
fecha_finstringISO date string — include sales on or before this date
Each sale record in the response includes:
  • Order ID
  • Cashier name
  • Payment method name
  • monto_total — calculated order total
  • monto_recibido — amount provided by the customer
  • cambio — change returned
  • fecha — payment timestamp
To retrieve a single sale, use GET /ventas/{venta_id} (any authenticated user).

​
Recording Expenses

POST /gastos/ records an operational expense such as a gas purchase, utility payment, or supply cost. Roles: admin, caja. 
{
  "descripcion": "Compra de gas",
  "monto": 350.00,
  "id_categoria": 2,
  "fecha": "2024-01-15"
}
FieldTypeDescription
descripcionstringFree-text description of the expense
montodecimalAmount spent (must be > 0)
id_categoriainteger(optional) Category ID for grouping in reports
fechadateDate the expense occurred (ISO date string)
The user who created the expense is recorded automatically from the JWT token (id_usuario). The category is optional but recommended — categorized expenses produce more meaningful breakdowns in financial reports.
Expense categories come from the same categorias table used for products. The tipo column on each category ('producto', 'gasto', or 'ambos') is informational — the API does not enforce that only 'gasto' or 'ambos' categories are used for expenses. It only checks that the category ID exists. Ask your admin to create dedicated expense categories and use them consistently for accurate report breakdowns.
GET /gastos/ lists all recorded expenses, ordered newest-first, and accepts the same fecha_inicio / fecha_fin query parameters as the sales list. Roles: admin, caja.

​
Financial Summary

Several stats endpoints aggregate sales and expense data for dashboards and reports. GET /stats/dashboard (admin, caja)
Returns today’s key performance indicators: 
{
  "ventas_hoy": 1250.00,
  "pedidos_activos": 3,
  "stock_bajo": 2,
  "gastos_hoy": 350.00,
  "productos_mas_vendidos": [...]
}
GET /stats/resumen-mes (admin, caja)
Returns month-to-date financial totals, calculated from the first day of the current month through today: 
{
  "total_ventas": 28500.00,
  "total_pedidos": 312,
  "ticket_promedio": 91.35,
  "gastos_totales": 8200.00,
  "ganancia_neta": 20300.00,
  "fecha_inicio": "2024-01-01",
  "fecha_fin": "2024-01-15"
}
GET /stats/ventas-diarias?dias=7 (admin, caja)
Returns an array of daily sales totals for the past dias days (default: 7). Each item has fecha (formatted as DD/MM) and total. Useful for rendering sales trend charts. GET /stats/gastos-diarios?dias=7 (admin, caja)
Same structure as ventas-diarias but for operational expenses. Both endpoints accept any integer value for dias.

Build docs developers (and LLMs) love

Get started for freeTalk to us