Inventory API endpoints

Manage the product catalog, track warehouse stock levels, and receive automatic low-stock alerts when inventory falls below your configured thresholds.

The inventory service (ms-inventario) owns the product catalog for SmartLogix. Each product has a unique SKU, a unit price, a current stock count, and a minimum threshold. When stockActual drops below umbralMinimo, the product appears in the /alertas feed. The stock-check endpoint (/{id}/stock) is also used internally by the orders service via a Resilience4j circuit breaker.

All endpoints require a valid JWT token in the Authorization header.

---

GET /api/inventario

Return the full list of products in the catalog.

Status codes

Code	Meaning
200	Success. Returns an array of ProductDTO objects.

Response fields

id · number · required

Auto-generated product identifier.

sku · string · required

Unique product code used across SmartLogix services.

nombre · string · required

Human-readable product name.

precioUnitario · number · required

Unit price. Must be ≥ 0.0.

stockActual · number · required

Current units in stock. Must be ≥ 0.

umbralMinimo · number · required

Minimum stock threshold. When stockActual is below this value, the product appears in /alertas.

bodega · string

Physical warehouse location identifier.

descripcion · string

Optional product description.

Example

List all products

curl --request GET \
  --url http://localhost:8080/api/inventario \
  --header 'Authorization: Bearer <token>'

---

POST /api/inventario

Create a new product. The sku must be unique. Returns 201 Created with the persisted ProductDTO.

Request body

sku · string · required

Unique product code. Cannot be blank.

nombre · string · required

Product name. Cannot be blank.

precioUnitario · number · required

Unit price. Must be ≥ 0.0.

stockActual · number · required

Initial stock quantity. Must be ≥ 0.

umbralMinimo · number · required

Low-stock alert threshold. Must be ≥ 0.

bodega · string

Warehouse location (optional).

descripcion · string

Product description (optional).

Status codes

Code	Meaning
201	Product created. Response body contains the new ProductDTO.
400	Validation failed (e.g. blank SKU, negative price).

Example

Create a product

curl --request POST \
  --url http://localhost:8080/api/inventario \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sku": "SL-BOX-001",
    "nombre": "Caja de cartón reforzada",
    "precioUnitario": 2.50,
    "stockActual": 500,
    "umbralMinimo": 50,
    "bodega": "BODEGA-A",
    "descripcion": "Caja para envíos nacionales"
  }'

---

GET /api/inventario/

Retrieve a single product by its numeric ID.

Path parameters

id · number · required

The product’s auto-generated identifier.

Status codes

Code	Meaning
200	Product found. Returns a ProductDTO.
404	No product with the given ID.

Example

Get product by ID

curl --request GET \
  --url http://localhost:8080/api/inventario/42 \
  --header 'Authorization: Bearer <token>'

---

PUT /api/inventario/

Replace all fields of an existing product. The request body follows the same schema as POST /api/inventario. Returns the updated ProductDTO.

Path parameters

id · number · required

The product’s auto-generated identifier.

Request body

sku · string · required

Unique product code. Cannot be blank.

nombre · string · required

Product name. Cannot be blank.

precioUnitario · number · required

Unit price. Must be ≥ 0.0.

stockActual · number · required

Updated stock quantity. Must be ≥ 0.

umbralMinimo · number · required

Low-stock alert threshold. Must be ≥ 0.

bodega · string

Warehouse location (optional).

descripcion · string

Product description (optional).

Status codes

Code	Meaning
200	Update successful. Returns the updated ProductDTO.
400	Validation failed.
404	No product with the given ID.

Example

Update a product

curl --request PUT \
  --url http://localhost:8080/api/inventario/42 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sku": "SL-BOX-001",
    "nombre": "Caja de cartón reforzada XL",
    "precioUnitario": 3.00,
    "stockActual": 480,
    "umbralMinimo": 50,
    "bodega": "BODEGA-A"
  }'

---

DELETE /api/inventario/

Permanently delete a product. Returns no response body on success.

This operation is irreversible. Deleting a product that is referenced by open orders may cause inconsistencies in downstream services.

Path parameters

id · number · required

The product’s auto-generated identifier.

Status codes

Code	Meaning
204	Deleted successfully. No response body.
404	No product with the given ID.

Example

Delete a product

curl --request DELETE \
  --url http://localhost:8080/api/inventario/42 \
  --header 'Authorization: Bearer <token>'

---

GET /api/inventario//stock

Check whether a product has sufficient stock for a given quantity. Returns a JSON boolean (true or false). This endpoint is called internally by ms-pedidos through a Resilience4j circuit breaker.

Path parameters

id · number · required

The product’s auto-generated identifier.

Query parameters

cantidad · number · required

The number of units to check against stockActual.

Response

(response body) · boolean · required

true if stockActual >= cantidad; false otherwise.

Status codes

Code	Meaning
200	Check complete. Response body is true or false.
404	No product with the given ID.

Example

Check if 100 units are available

curl --request GET \
  --url 'http://localhost:8080/api/inventario/42/stock?cantidad=100' \
  --header 'Authorization: Bearer <token>'

Example response (200)

true

---

GET /api/inventario/alertas

Return all products whose stockActual is strictly below their umbralMinimo. Use this feed to trigger restocking workflows.

Status codes

Code	Meaning
200	Success. Returns an array of ProductDTO objects (may be empty).

Example

List low-stock products

curl --request GET \
  --url http://localhost:8080/api/inventario/alertas \
  --header 'Authorization: Bearer <token>'