Skip to main content
Items represent individual products or menu dishes (platos) within a transaction. Each item belongs to exactly one transaction and must reference either a producto_id or a plato_id — never both.

​
POST /api/transacciones/:id/items

Adds a product or dish to the transaction. The server automatically resolves precio_unitario from the current price on the product or dish record — you do not pass it in the request body. If the transaction is cerrado, it is reopened automatically before the item is added. Adding a plato_id item also sets estado_cocina to pendiente and broadcasts the update to the kitchen via WebSocket. Authentication: Required Required role: Any authenticated user

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer <token>Yes
Content-Typeapplication/jsonYes

​
Path parameters

ParameterTypeDescription
idnumberThe transaction ID

​
Body

​
producto_id
string
ID of the product to add. Mutually exclusive with plato_id.
​
plato_id
string
ID of the dish to add. Mutually exclusive with producto_id.
You must provide exactly one of producto_id or plato_id. Providing both or neither returns a 400 error.
​
cantidad
number
required
Quantity to add. Must be ≥ 0.01.
​
notas
string
Free-text preparation notes for this item (e.g. "Sin cebolla, punto medio").
​
extras
array
Optional list of extras to attach at creation time. Each extra follows the AddExtraDto schema.

​
Extra object shape

FieldTypeRequiredDescription
ingrediente_idstring—Inventory ingredient ID. Mutually exclusive with descripcion.
descripcionstring—Free-text description (e.g. "Extra queso"). Mutually exclusive with ingrediente_id.
precionumberYesPrice of the extra.
cantidadnumber—Quantity. Defaults to 1.

​
Response

​
Success (201)

​
id
number
Auto-generated item ID.
​
transaccion_id
number
Parent transaction ID.
​
producto_id
string | null
Associated product ID.
​
plato_id
string | null
Associated dish ID.
​
cantidad
string
Quantity as a decimal string.
​
precio_unitario
string
Unit price resolved from the product or dish.
​
subtotal
string
Line total (precio_unitario × cantidad + extras). Recalculated whenever extras change.
​
notas
string | null
Preparation notes.

​
Error responses

StatusDescription
400Both producto_id and plato_id provided, or neither provided
401Unauthorized
404Transaction, product, or dish not found

​
GET /api/transacciones/:id/items

Returns all active (non-deleted) items for the specified transaction, enriched with the product or dish name. Authentication: Required Required role: Any authenticated user

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer <token>Yes

​
Path parameters

ParameterTypeDescription
idnumberThe transaction ID

​
Response

​
Success (200)

An array of item objects:
​
[].id
number
Item ID.
​
[].transaccion_id
number
Parent transaction ID.
​
[].producto_id
string | null
Product ID.
​
[].plato_id
string | null
Dish ID.
​
[].nombre
string
Resolved product or dish name.
​
[].cantidad
string
Quantity.
​
[].precio_unitario
string
Unit price.
​
[].subtotal
string
Line total.
​
[].notas
string | null
Preparation notes.

​
DELETE /api/transacciones/:id/items/:itemId

Soft-deletes an item from the transaction. The transaction’s monto_total is recalculated automatically after deletion. Authentication: Required Required role: Any authenticated user

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer <token>Yes

​
Path parameters

ParameterTypeDescription
idnumberThe transaction ID
itemIdnumberThe item ID

​
Response

​
Success (200)

​
message
string
Confirmation message.

​
Error responses

StatusDescription
401Unauthorized
404Transaction or item not found

​
Example

# Add a dish to transaction 42
curl -X POST http://localhost:3000/api/transacciones/42/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plato_id": "plato_abc123", "cantidad": 2, "notas": "Sin cebolla"}'

{
  "id": 7,
  "transaccion_id": 42,
  "producto_id": null,
  "plato_id": "plato_abc123",
  "cantidad": "2",
  "precio_unitario": "35.00",
  "subtotal": "70.00",
  "notas": "Sin cebolla",
  "creado_en": "2026-03-18T14:31:00.000Z",
  "actualizado_en": "2026-03-18T14:31:00.000Z",
  "borrado_en": null
}

# List all items
curl http://localhost:3000/api/transacciones/42/items \
  -H "Authorization: Bearer $TOKEN"

# Remove item 7
curl -X DELETE http://localhost:3000/api/transacciones/42/items/7 \
  -H "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us