Skip to main content
Ingredients are raw materials consumed when a dish (plato) that contains them is ordered in a transaction. Each ingredient tracks its current quantity (cantidad) and a minimum threshold (cantidad_minima) used to trigger low-stock alerts in the dashboard.
Soft delete is used throughout. Deleting an ingredient sets borrado_en to the current timestamp. The record is never physically removed from the database and will no longer appear in any list or detail response.
Ingredient stock (cantidad) is automatically deducted when a plato that uses the ingredient is added to a transaction. You can also adjust stock directly via the update endpoint.

​
POST /api/ingredientes

Create a new ingredient. Authentication: Bearer JWT required
Required role: admin

​
Request body

​
nombre
string
required
Ingredient name. Max 100 characters.
​
unidad
string
required
Unit of measure (e.g. kg, litro, unidad). Max 20 characters.
​
cantidad
number
required
Current available quantity. Float, must be >= 0.
​
cantidad_minima
number
required
Minimum required quantity for low-stock alerts. Float, must be >= 0. When cantidad falls below this value the dashboard flags the ingredient.

​
Response

Returns the created ingredient object (201 Created).
​
id
string
Unique identifier generated with nanoid (10 characters).
​
nombre
string
Ingredient name.
​
unidad
string
Unit of measure.
​
cantidad
number
Current quantity (float).
​
cantidad_minima
number
Minimum quantity threshold (float).
​
creado_en
string (ISO 8601)
Creation timestamp.
​
actualizado_en
string (ISO 8601)
Last update timestamp.
​
borrado_en
string (ISO 8601) | null
Soft-delete timestamp. null for active ingredients.

​
Example

curl -X POST http://localhost:3000/api/ingredientes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Tomate",
    "unidad": "kg",
    "cantidad": 50.5,
    "cantidad_minima": 10
  }'

{
  "id": "cK9mN2pQrS",
  "nombre": "Tomate",
  "unidad": "kg",
  "cantidad": 50.5,
  "cantidad_minima": 10,
  "creado_en": "2026-03-18T14:00:00.000Z",
  "actualizado_en": "2026-03-18T14:00:00.000Z",
  "borrado_en": null
}

​
GET /api/ingredientes

Return all active ingredients. Authentication: Bearer JWT required
Required role: any authenticated user

​
Request parameters

No parameters.

​
Response

Returns an array of ingredient objects (200 OK). Only records where borrado_en IS NULL are included.

​
Example

curl http://localhost:3000/api/ingredientes \
  -H "Authorization: Bearer <token>"

[
  {
    "id": "cK9mN2pQrS",
    "nombre": "Tomate",
    "unidad": "kg",
    "cantidad": 50.5,
    "cantidad_minima": 10,
    "creado_en": "2026-03-18T14:00:00.000Z",
    "actualizado_en": "2026-03-18T14:00:00.000Z",
    "borrado_en": null
  }
]

​
GET /api/ingredientes/:id

Return a single active ingredient by ID. Authentication: Bearer JWT required
Required role: any authenticated user

​
Request parameters

​
id
string
required
The nanoid of the ingredient.

​
Response

Returns the ingredient object (200 OK), or 404 Not Found if the ingredient does not exist or has been soft-deleted.

​
Example

curl http://localhost:3000/api/ingredientes/cK9mN2pQrS \
  -H "Authorization: Bearer <token>"

​
PATCH /api/ingredientes/:id

Partially update an ingredient. All body fields are optional; only the fields you send are updated. Authentication: Bearer JWT required
Required role: admin

​
Request parameters

​
id
string
required
The nanoid of the ingredient to update.
​
nombre
string
New ingredient name. Max 100 characters.
​
unidad
string
New unit of measure. Max 20 characters.
​
cantidad
number
Updated quantity. Float, must be >= 0. Use this field to manually adjust stock.
​
cantidad_minima
number
Updated minimum threshold. Float, must be >= 0.

​
Response

Returns the updated ingredient object (200 OK). actualizado_en is always refreshed.

​
Example

curl -X PATCH http://localhost:3000/api/ingredientes/cK9mN2pQrS \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cantidad": 35.0, "cantidad_minima": 8}'

​
DELETE /api/ingredientes/:id

Soft-delete an ingredient. Authentication: Bearer JWT required
Required role: admin
This operation sets borrado_en and actualizado_en to the current timestamp. The ingredient record is retained in the database and will no longer appear in list or detail responses.

​
Request parameters

​
id
string
required
The nanoid of the ingredient to delete.

​
Response

Returns a confirmation message (200 OK).
​
message
string
Confirmation string, e.g. "Ingrediente con ID cK9mN2pQrS eliminado exitosamente (soft delete)".

​
Example

curl -X DELETE http://localhost:3000/api/ingredientes/cK9mN2pQrS \
  -H "Authorization: Bearer <token>"

{
  "message": "Ingrediente con ID cK9mN2pQrS eliminado exitosamente (soft delete)"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us