Documentation Index
Fetch the complete documentation index at: https://mintlify.com/EstefanoARG/FridgeRadar/llms.txt
Use this file to discover all available pages before exploring further.
The inventory is the heart of FridgeRadar. Each entry represents a specific product placed on a specific shelf inside a household, and is enriched with purchase date, expiry date, quantity, and a live freshness state. Whenever an item is added, edited, or removed the system automatically records a corresponding movement entry, giving you a complete audit trail of how your pantry stock has changed over time.
Inventory Item Fields
Every item in the pantry is represented by an InventarioResponse object.
| Field | Type | Description |
|---|
id_inventario | int | Auto-generated primary key |
id_hogar | int | The household this item belongs to |
id_producto | int | Reference to the product catalogue entry |
id_estante | int | The shelf where the item physically sits |
id_usuario_agrego | int | The user who added the item |
cantidad | float | Current quantity on hand |
fecha_compra | date | null | When the item was purchased |
fecha_vencimiento | date | null | Best-before or use-by date |
abierto | bool | Whether the package has been opened |
observaciones | str | null | Free-text notes (e.g. “half used”) |
estado_caducidad | str | Computed freshness state — see Semáforo |
fecha_registro | datetime | When the record was first created |
Adding an Item
When creating an item you supply only the fields you know; estado_caducidad is always computed server-side and never accepted as input.
POST /api/v1/inventario/hogar/{id_hogar}
Authorization: Bearer <token>
Content-Type: application/json
{
"id_producto": 42,
"id_estante": 7,
"cantidad": 2.0,
"fecha_compra": "2024-11-10",
"fecha_vencimiento": "2024-11-17",
"abierto": false,
"observaciones": "Comprado en oferta"
}
{
"id_inventario": 101,
"id_hogar": 1,
"id_producto": 42,
"id_estante": 7,
"id_usuario_agrego": 3,
"cantidad": 2.0,
"fecha_compra": "2024-11-10",
"fecha_vencimiento": "2024-11-17",
"abierto": false,
"observaciones": "Comprado en oferta",
"estado_caducidad": "amarillo",
"fecha_registro": "2024-11-10T14:22:00"
}
The estado_caducidad Field
estado_caducidad is a computed, read-only field on every inventory response. It is derived from fecha_vencimiento by the semáforo engine and can hold one of four values:
| Value | Meaning |
|---|
"verde" | Fresh — more than 7 days remaining, or no expiry date set |
"amarillo" | Use soon — 3 to 7 days remaining |
"rojo" | Use immediately — 0 to 2 days remaining |
"vencido" | Expired — past the expiry date |
The abierto Flag
Setting abierto: true signals that a package has been opened. An opened item may have a shorter effective shelf life than the printed expiry date, so the flag is surfaced prominently in the UI and can be used to filter or prioritise items.
PATCH /api/v1/inventario/{id_inventario}
Authorization: Bearer <token>
Content-Type: application/json
{
"abierto": true,
"observaciones": "Abierto el 12/11 — usar antes de 3 días"
}
Opening a package does not automatically change fecha_vencimiento. Update that field manually if the manufacturer’s guidance changes once opened.
Inventory Movements
Every write operation on an inventory item generates a MovimientoInventario record. This gives admins and household members a tamper-evident log of all stock changes.
| Field | Type | Description |
|---|
id_movimiento | int | Auto-generated primary key |
id_inventario | int | The inventory item that changed |
id_usuario | int | Who triggered the change |
tipo_movimiento | str | Type of change ("entrada", "salida", "ajuste", "eliminacion") |
cantidad | float | null | The quantity involved in the movement |
descripcion | str | null | Human-readable summary of what changed |
fecha_movimiento | datetime | Exact timestamp of the event |
Movements are created automatically by the service layer. You do not post to a movements endpoint directly — they appear as a side-effect of POST, PATCH, and DELETE calls on /api/v1/inventario/.
Fetching Movements
GET /api/v1/inventario/{id_inventario}/movimientos
Authorization: Bearer <token>
Filtering Inventory by Freshness State
The household inventory list endpoint accepts an optional estado query parameter so you can fetch only the items at a particular freshness level.
GET /api/v1/inventario/hogar/{id_hogar}?estado=rojo
Authorization: Bearer <token>
estado:
| Value | Returns |
|---|
verde | Items fresh with more than 7 days remaining |
amarillo | Items expiring in 3–7 days |
rojo | Items expiring in 0–2 days |
vencido | Items that are already past their expiry date |
estado parameter returns all items regardless of freshness state.
Combine the ?estado=amarillo and ?estado=rojo filters with the Tengo Hambre recipe engine to surface meals you can cook from items that need to be used up first.
API Overview
| Method | Path | Description |
|---|
POST | /api/v1/inventario/hogar/{id_hogar} | Add a new item |
GET | /api/v1/inventario/hogar/{id_hogar} | List all items (supports ?estado=) |
GET | /api/v1/inventario/{id_inventario} | Get a single item |
PATCH | /api/v1/inventario/{id_inventario} | Update quantity, shelf, expiry, or notes |
DELETE | /api/v1/inventario/{id_inventario} | Remove an item |
GET | /api/v1/inventario/{id_inventario}/movimientos | List movement history |