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.

The /ventas/ endpoints handle payment processing for the cafeteria. A sale (venta) is created when a cashier collects payment for a completed order. Each sale record stores the cashier who processed it, the payment method used, the server-calculated total, and the amount received along with computed change. Registering a sale automatically transitions the linked order to pagado status and writes an entry to the order status history — no separate order update call is needed.

​
Endpoints

​
List payment methods

​
Authorization
string
required
Bearer <token> — Any authenticated user.

GET /ventas/metodos-pago
Returns all payment methods configured in the system. These IDs are used in the id_metodo_pago field when registering a sale. Example response 
[
  {
    "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 o pago digital"
  }
]
​
id
integer
Payment method ID. Used as id_metodo_pago when registering a sale.
​
nombre
string
Human-readable payment method name (e.g. "Efectivo", "Tarjeta").
​
descripcion
string | null
Optional description of the payment method.

​
List sales

​
Authorization
string
required
Bearer <token> — Roles: admin, caja.

GET /ventas/
Returns a list of all sales, ordered by fecha descending (most recent first). Optionally filtered by date range. Both fecha_inicio and fecha_fin are inclusive boundaries applied against the fecha timestamp on each sale. Query parameters
​
fecha_inicio
string
Start of the date range filter (ISO date string, e.g. "2024-01-01"). Inclusive.
​
fecha_fin
string
End of the date range filter (ISO date string, e.g. "2024-01-31"). Inclusive.
Example request 
GET /ventas/?fecha_inicio=2024-01-01&fecha_fin=2024-01-31
Example response 
[
  {
    "id": 101,
    "id_pedido": 42,
    "id_cajero": 3,
    "cajero": { "id": 3, "nombre": "Ana García", "email": "[email protected]", "activo": true, "created_at": "2023-11-01T09:00:00", "role": { "id": 2, "nombre": "caja", "descripcion": null } },
    "metodo_pago": { "id": 1, "nombre": "Efectivo", "descripcion": "Pago en efectivo" },
    "monto_total": 95.50,
    "monto_recibido": 100.00,
    "cambio": 4.50,
    "fecha": "2024-01-15T14:32:00"
  }
]

​
Get a single sale

​
Authorization
string
required
Bearer <token> — Any authenticated user.

GET /ventas/{venta_id}
​
venta_id
integer
required
Internal ID of the sale to retrieve.
Error responses
StatusDetail
404"Venta no encontrada"

​
Register a sale

​
Authorization
string
required
Bearer <token> — Roles: admin, caja.

POST /ventas/
Processes payment for a completed order. The endpoint:
  1. Validates the order exists and is in listo or entregado state.
  2. Confirms the order has not already been paid ("Este pedido ya fue cobrado").
  3. Validates the payment method ID.
  4. Calculates monto_total server-side by summing subtotal across all order line items — the value supplied by the client is ignored.
  5. Computes cambio as monto_recibido - monto_total (stored in the model, null if monto_recibido is null).
  6. Transitions the order to pagado and appends a row to OrderStatusHistory.
Request body
​
id_pedido
integer
required
ID of the order being paid. The order must be in listo or entregado state.
​
id_metodo_pago
integer
required
ID of the payment method. Must match an existing record from GET /ventas/metodos-pago.
​
monto_recibido
float
Amount of cash (or equivalent) tendered by the customer. Optional for card or digital payment methods where no cash counting is needed. When provided, cambio is calculated automatically.
{
  "id_pedido": 42,
  "id_metodo_pago": 1,
  "monto_recibido": 100.00
}
Response — 201 Created 
{
  "id": 101,
  "id_pedido": 42,
  "id_cajero": 3,
  "cajero": {
    "id": 3,
    "nombre": "Ana García",
    "email": "[email protected]",
    "activo": true,
    "created_at": "2023-11-01T09:00:00",
    "role": { "id": 2, "nombre": "caja", "descripcion": null }
  },
  "metodo_pago": {
    "id": 1,
    "nombre": "Efectivo",
    "descripcion": "Pago en efectivo"
  },
  "monto_total": 95.50,
  "monto_recibido": 100.00,
  "cambio": 4.50,
  "fecha": "2024-01-15T14:32:00"
}
Error responses
StatusDetail
404"Pedido no encontrado"
400"El pedido está en estado '{nombre}'. Debe estar 'listo' o 'entregado' para cobrar."
400"Este pedido ya fue cobrado"
400"Método de pago no válido"

​
The SaleOut object

​
id
integer
Internal sale ID.
​
id_pedido
integer
ID of the order that was paid.
​
id_cajero
integer
ID of the user who processed the payment (taken from the JWT token automatically).
​
cajero
object
Full user object for the cashier: {id, nombre, email, activo, created_at, role}.
​
metodo_pago
object
Payment method used: {id, nombre, descripcion}.
​
monto_total
float
Total amount due, calculated server-side from the sum of order item subtotals. Client-supplied values are ignored.
​
monto_recibido
float | null
Amount tendered by the customer. null for card or digital payments where this is not applicable.
​
cambio
float | null
Change due to the customer (monto_recibido - monto_total). null when monto_recibido is null. Not stored as a column — computed at the application level as a Python property on the model.
​
fecha
datetime
Timestamp when the sale was registered (set by the database, not the client).

​
Notes on payment flow

The /ventas/ endpoint is the authoritative way to close an order as paid. For emergency situations where an order needs to be cleared without going through the full payment process, PATCH /mesas/{mesa_id}/liberar will force the order to pagado directly — but it creates no Sale record and the transaction will not appear in sales reports. 
Order (listo or entregado)
       │
       ▼
POST /ventas/   ──────────────────────────────▶  Sale created (201)
       │                                          Order → pagado
       │                                          Status history written
       ▼
GET /ventas/{id}  →  full SaleOut with cashier, payment method, change

Build docs developers (and LLMs) love

Get started for freeTalk to us