Storage Zones and Shelves: Create and Manage Locations

FridgeRadar models physical storage as a two-level hierarchy: zones (zonas) represent distinct temperature or storage areas within a household — such as a refrigerator, freezer, or pantry — and shelves (estantes) are named subdivisions within a zone. Both resources are fully CRUD-capable, and their list endpoints accept a filter query parameter so clients can fetch only the items relevant to a given household or zone. Every request requires an Authorization: Bearer <token> header.

Zones — /api/v1/zonas

POST /api/v1/zonas

Creates a new storage zone inside the specified household. Authentication: Authorization: Bearer <token> required.

id_hogar

integer

required

Primary key of the household this zone belongs to.

nombre

string

required

Display name for the zone (e.g. "Refrigerador", "Despensa").

tipo

string

required

Category of storage area (e.g. "frio", "congelado", "ambiente").

icono

string

Icon identifier or emoji used in the UI (e.g. "🧊"). Optional.

temperatura_min

number

Minimum temperature in °C for this zone. Optional.

temperatura_max

number

Maximum temperature in °C for this zone. Optional.

Response — 201 Created

id_zona

integer

Auto-assigned primary key for the new zone.

id_hogar

integer

Household this zone belongs to.

nombre

string

Zone name as stored.

tipo

string

Zone type/category.

icono

string | null

Icon identifier, or null if not set.

temperatura_min

number | null

Minimum temperature in °C, or null.

temperatura_max

number | null

Maximum temperature in °C, or null.

curl -X POST http://localhost:8000/api/v1/zonas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_hogar": 3,
    "nombre": "Refrigerador",
    "tipo": "frio",
    "icono": "🧊",
    "temperatura_min": 2,
    "temperatura_max": 8
  }'

Status	Meaning
`201 Created`	Zone created; object returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	The referenced `id_hogar` does not exist.
`422 Unprocessable Entity`	Validation error — required fields missing.

GET /api/v1/zonas

Returns all zones, with an optional filter by household. Authentication: Authorization: Bearer <token> required.

id_hogar

integer

If provided, returns only zones belonging to this household. Omit to return all zones visible to the authenticated user.

Response — 200 OK

Returns a JSON array of ZonaResponse objects (same shape as the POST response above).

id_zona

integer

Zone primary key.

id_hogar

integer

Household this zone belongs to.

nombre

string

Zone name.

tipo

string

Zone type/category.

icono

string | null

Icon identifier, or null.

temperatura_min

number | null

Minimum temperature in °C, or null.

temperatura_max

number | null

Maximum temperature in °C, or null.

curl -X GET "http://localhost:8000/api/v1/zonas?id_hogar=3" \
  -H "Authorization: Bearer <token>"

Status	Meaning
`200 OK`	Array of zones returned (may be empty).
`401 Unauthorized`	Token missing, expired, or invalid.

GET /api/v1/zonas/`{id_zona}`

Fetches a single zone by its primary key. Authentication: Authorization: Bearer <token> required.

id_zona

integer

required

The primary key of the zone to retrieve.

Response — 200 OK

Returns a single ZonaResponse object.

curl -X GET http://localhost:8000/api/v1/zonas/11 \
  -H "Authorization: Bearer <token>"

Status	Meaning
`200 OK`	Zone object returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No zone with that ID.

PATCH /api/v1/zonas/`{id_zona}`

Partially updates a zone. Only fields present in the request body are changed. Authentication: Authorization: Bearer <token> required.

id_zona

integer

required

The primary key of the zone to update.

nombre

string

New display name. Optional.

tipo

string

Updated storage type. Optional.

icono

string

Updated icon identifier. Optional.

temperatura_min

number

Updated minimum temperature in °C. Optional.

temperatura_max

number

Updated maximum temperature in °C. Optional.

Response — 200 OK

Returns the full updated ZonaResponse object.

curl -X PATCH http://localhost:8000/api/v1/zonas/11 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "temperatura_min": 0,
    "temperatura_max": 5
  }'

Status	Meaning
`200 OK`	Updated zone returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No zone with that ID.
`422 Unprocessable Entity`	Validation error.

DELETE /api/v1/zonas/`{id_zona}`

Permanently deletes a zone and all its shelves. Authentication: Authorization: Bearer <token> required.

id_zona

integer

required

The primary key of the zone to delete.

curl -X DELETE http://localhost:8000/api/v1/zonas/11 \
  -H "Authorization: Bearer <token>"

Status	Meaning
`204 No Content`	Zone deleted; no response body.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No zone with that ID.

Shelves — /api/v1/estantes

GET /api/v1/estantes

Returns all shelves, with an optional filter by zone. Authentication: Authorization: Bearer <token> required.

id_zona

integer

If provided, returns only shelves that belong to this zone. Omit to return all shelves visible to the authenticated user.

Response — 200 OK

Returns a JSON array of EstanteResponse objects.

id_estante

integer

Shelf primary key.

id_zona

integer

Zone this shelf belongs to.

nombre

string

Shelf display name.

posicion_vertical

integer

Numeric vertical position within the zone (lower numbers = higher shelves, by convention).

color_ui

string | null

Optional color hint for UI rendering (e.g. "#A8D5BA"), or null.

curl -X GET "http://localhost:8000/api/v1/estantes?id_zona=11" \
  -H "Authorization: Bearer <token>"

Status	Meaning
`200 OK`	Array of shelves returned (may be empty).
`401 Unauthorized`	Token missing, expired, or invalid.

POST /api/v1/estantes

Creates a new shelf inside a zone. Authentication: Authorization: Bearer <token> required.

id_zona

integer

required

Primary key of the zone this shelf belongs to.

nombre

string

required

Display name for the shelf (e.g. "Cajón superior", "Bandeja de lácteos").

posicion_vertical

integer

required

Numeric position of the shelf within the zone. Used to render shelves in physical order.

color_ui

string

Optional hex color or color token for UI display. Optional.

Response — 201 Created

id_estante

integer

Auto-assigned primary key for the new shelf.

id_zona

integer

Zone this shelf belongs to.

nombre

string

Shelf name as stored.

posicion_vertical

integer

Vertical position as stored.

color_ui

string | null

Color hint, or null if not set.

curl -X POST http://localhost:8000/api/v1/estantes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_zona": 11,
    "nombre": "Bandeja de lácteos",
    "posicion_vertical": 1,
    "color_ui": "#A8D5BA"
  }'

Status	Meaning
`201 Created`	Shelf created; object returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	The referenced `id_zona` does not exist.
`422 Unprocessable Entity`	Validation error — required fields missing.

GET /api/v1/estantes/`{id_estante}`

Fetches a single shelf by its primary key. Authentication: Authorization: Bearer <token> required.

id_estante

integer

required

The primary key of the shelf to retrieve.

Response — 200 OK

Returns a single EstanteResponse object.

curl -X GET http://localhost:8000/api/v1/estantes/42 \
  -H "Authorization: Bearer <token>"

Status	Meaning
`200 OK`	Shelf object returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No shelf with that ID.

PATCH /api/v1/estantes/`{id_estante}`

Partially updates a shelf. Only fields present in the request body are modified. Authentication: Authorization: Bearer <token> required.

id_estante

integer

required

The primary key of the shelf to update.

nombre

string

New display name. Optional.

posicion_vertical

integer

Updated vertical position. Optional.

color_ui

string

Updated UI color hint. Optional.

Response — 200 OK

Returns the full updated EstanteResponse object.

curl -X PATCH http://localhost:8000/api/v1/estantes/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Cajón de verduras",
    "posicion_vertical": 3
  }'

Status	Meaning
`200 OK`	Updated shelf returned.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No shelf with that ID.
`422 Unprocessable Entity`	Validation error.

DELETE /api/v1/estantes/`{id_estante}`

Permanently deletes a shelf. Authentication: Authorization: Bearer <token> required.

id_estante

integer

required

The primary key of the shelf to delete.

curl -X DELETE http://localhost:8000/api/v1/estantes/42 \
  -H "Authorization: Bearer <token>"

Status	Meaning
`204 No Content`	Shelf deleted; no response body.
`401 Unauthorized`	Token missing, expired, or invalid.
`404 Not Found`	No shelf with that ID.

Overview

Endpoints

Storage Zones and Shelves: Create and Manage Locations

Zones — /api/v1/zonas

POST /api/v1/zonas

Response — 201 Created

GET /api/v1/zonas

Response — 200 OK

GET /api/v1/zonas/`{id_zona}`

Response — 200 OK

PATCH /api/v1/zonas/`{id_zona}`

Response — 200 OK

DELETE /api/v1/zonas/`{id_zona}`

Shelves — /api/v1/estantes

GET /api/v1/estantes

Response — 200 OK

POST /api/v1/estantes

Response — 201 Created

GET /api/v1/estantes/`{id_estante}`

Response — 200 OK

PATCH /api/v1/estantes/`{id_estante}`

Response — 200 OK

DELETE /api/v1/estantes/`{id_estante}`

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Zones — /api/v1/zonas

​POST /api/v1/zonas

​Response — 201 Created

​GET /api/v1/zonas

​Response — 200 OK

​GET /api/v1/zonas/{id_zona}

​Response — 200 OK

​PATCH /api/v1/zonas/{id_zona}

​Response — 200 OK

​DELETE /api/v1/zonas/{id_zona}

​Shelves — /api/v1/estantes

​GET /api/v1/estantes

​Response — 200 OK

​POST /api/v1/estantes

​Response — 201 Created

​GET /api/v1/estantes/{id_estante}

​Response — 200 OK

​PATCH /api/v1/estantes/{id_estante}

​Response — 200 OK

​DELETE /api/v1/estantes/{id_estante}

Build docs developers (and LLMs) love

Zones — /api/v1/zonas

POST /api/v1/zonas

Response — 201 Created

GET /api/v1/zonas

Response — 200 OK

GET /api/v1/zonas/`{id_zona}`

Response — 200 OK

PATCH /api/v1/zonas/`{id_zona}`

Response — 200 OK

DELETE /api/v1/zonas/`{id_zona}`

Shelves — /api/v1/estantes

GET /api/v1/estantes

Response — 200 OK

POST /api/v1/estantes

Response — 201 Created

GET /api/v1/estantes/`{id_estante}`

Response — 200 OK

PATCH /api/v1/estantes/`{id_estante}`

Response — 200 OK

DELETE /api/v1/estantes/`{id_estante}`