Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/InnoDev69/StockManager/llms.txt

Use this file to discover all available pages before exploring further.

The Products API gives you full control over StockManager’s item catalog. You can retrieve paginated and filtered product lists, look up individual items, create new entries, make partial updates, soft-delete records by disabling them, and bring them back with the activate endpoint. All routes require an active session; write operations additionally require the admin or root role.

​
GET /api/products_all

Returns a paginated list of all products in the inventory, including disabled ones (status = 0). Designed for inventory management screens where administrators need visibility over the full catalog.
​
search
string
Full-text search applied simultaneously to name, barcode, and description fields.
​
view_mode
string
default:"all"
Stock-level filter. Accepted values: all · in_stock (quantity > min_stock) · low_stock (quantity > 0 and quantity ≤ min_stock) · out_of_stock (quantity = 0).
​
sort
string
default:"name"
Column to order results by. Accepted values: name · stock · price. Any other value silently falls back to name.
​
order
string
default:"asc"
Sort direction. Accepted values: asc · desc.
​
page
integer
default:"1"
1-based page number. Values below 1 are clamped to 1.
​
limit
integer
default:"50"
Number of records per page. Clamped between 1 and 250.

​
Response

​
data
array
Array of product objects for the current page.
​
total
integer
Total number of records matching the applied filters.
​
page
integer
Current page number.
​
pages
integer
Total number of pages given total and limit.
​
limit
integer
Records-per-page value used for this response.

​
GET /api/products

Returns a paginated list of active products only (status = 1). This is the primary endpoint used by point-of-sale and search screens where only sellable items should appear.
The view_mode filter for this endpoint does not include low_stock. Use GET /api/products_all if you need low-stock visibility.
​
search
string
Search by product name or barcode.
​
view_mode
string
default:"all"
Stock-level filter. Accepted values: all · in_stock (quantity > 0) · out_of_stock (quantity = 0).
​
sort
string
default:"name"
Column to order results by. Accepted values: name · stock · price.
​
order
string
default:"asc"
Sort direction. Accepted values: asc · desc.
​
page
integer
default:"1"
1-based page number.
​
limit
integer
default:"24"
Records per page. Clamped between 1 and 250. Default is 24, optimised for grid card layouts.

​
Response

Same structure as GET /api/products_all. The status field will always be 1 in results from this endpoint.
Example — list in-stock products, second page
curl -X GET "http://localhost:5000/api/products?view_mode=in_stock&page=2&limit=24" \
  -H "Cookie: session=<your-session-cookie>"
Response
{
  "data": [
    {
      "id": 7,
      "barcode": "7501234567890",
      "name": "Leche Entera 1L",
      "description": "Leche entera pasteurizada",
      "stock": 48,
      "min_stock": 10,
      "price": 22.5,
      "status": 1,
      "expiration_date": "2025-09-01",
      "created_at": "2024-11-03T10:22:00",
      "updated_at": "2025-01-15T08:30:00"
    }
  ],
  "total": 1,
  "page": 2,
  "pages": 2,
  "limit": 24
}

​
GET /api/products/:id

Returns the full details of a single product identified by its numeric ID. Unlike GET /api/products, this endpoint does not filter by status — it returns the product record regardless of whether it is active or disabled.

​
Path Parameter

​
id
integer
required
The unique integer ID of the product.

​
Response

​
id
integer
Unique product ID.
​
barcode
string
Product barcode.
​
name
string
Product name.
​
description
string
Product description.
​
stock
integer
Current quantity available.
​
min_stock
integer
Minimum stock alert threshold.
​
price
number
Unit sale price.
​
expiration_date
string
Expiration date (YYYY-MM-DD) or null.
​
created_at
string
Creation timestamp.
​
updated_at
string
Last update timestamp.
StatusMeaning
200Product found and returned.
401No active session.
404No product exists with the given ID.

​
POST /api/products

Creates a new product in the inventory. Requires the admin or root role.
1

Authenticate as admin or root

Ensure your session belongs to a user with role admin or root. A 403 is returned otherwise.
2

Submit product data

Send a JSON body with the required fields. Optional fields can be omitted entirely.
3

Receive confirmation

A 201 response confirms creation. An in-app notification is also dispatched to the creating user.

​
Request Body

​
barcode
string
required
Product barcode. Maximum 20 characters.
​
name
string
required
Product name. Maximum 25 characters.
​
quantity
integer
required
Initial stock quantity. Maximum 10,000.
​
min_quantity
integer
required
Minimum stock threshold for low-stock alerts. Maximum 1,000.
​
price
number
required
Unit sale price. Maximum 1,000,000.
​
description
string
Optional product description. Maximum 200 characters.
​
expiration_date
string
Optional expiration date in YYYY-MM-DD format.

​
Response

201 Created
{
  "message": "Producto creado exitosamente"
}
StatusMeaning
201Product created successfully.
400Missing required fields or validation error.
401No active session.
403Authenticated user lacks admin or root role.
500Database or internal error.

Example — create a product
curl -X POST "http://localhost:5000/api/products" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -d '{
    "barcode": "7501234567890",
    "name": "Leche Entera 1L",
    "quantity": 100,
    "min_quantity": 10,
    "price": 22.50,
    "description": "Leche entera pasteurizada",
    "expiration_date": "2025-09-01"
  }'
Response
{
  "message": "Producto creado exitosamente"
}

​
PUT /api/products/:id

Partially updates an existing product. Only the fields present in the request body are modified; omitted fields retain their current values. Requires the admin or root role.

​
Path Parameter

​
id
integer
required
The unique integer ID of the product to update.

​
Request Body

All fields are optional. At least one field must differ from the current stored value; sending identical values returns 400.
​
name
string
New product name. Maximum 25 characters.
​
description
string
New description. Maximum 200 characters.
​
quantity
integer
Updated stock quantity. Maximum 10,000.
​
min_quantity
integer
Updated minimum stock threshold. Maximum 1,000.
​
price
number
Updated unit sale price. Maximum 1,000,000.
​
expiration_date
string
Updated expiration date in YYYY-MM-DD format.
​
status
integer
Explicit status override. 1 = active, 0 = disabled. Prefer the dedicated /activate and DELETE endpoints for lifecycle changes.

​
Response

200 OK
{
  "message": "Producto actualizado"
}
StatusMeaning
200Product updated successfully.
400No fields to update (all submitted values match current state).
401No active session.
403Authenticated user lacks admin or root role.
Low-stock checks run automatically after every update. If the updated quantity falls at or below min_quantity, the authenticated user receives an in-app notification.

​
DELETE /api/products/:id

Performs a soft delete by setting status = 0 on the product. The record is preserved in the database and can be reactivated at any time. Requires the admin or root role.

​
Path Parameter

​
id
integer
required
The unique integer ID of the product to disable.

​
Response

200 OK
{
  "message": "Producto deshabilitado"
}
StatusMeaning
200Product disabled successfully.
401No active session.
403Authenticated user lacks admin or root role.
Disabled products are hidden from GET /api/products and GET /api/items but remain fully visible in GET /api/products_all. Stock levels are preserved so re-enabling the product restores its full inventory state.

​
POST /api/products/:id/activate

Re-enables a previously disabled product by setting status = 1. Requires the admin or root role.

​
Path Parameter

​
id
integer
required
The unique integer ID of the product to reactivate.

​
Response

200 OK
{
  "message": "Producto activado"
}
StatusMeaning
200Product activated successfully.
401No active session.
403Authenticated user lacks admin or root role.
500Internal error during activation.

​
GET /api/items

Lightweight autocomplete endpoint that searches active products by name or barcode and returns up to 10 matches. Intended for typeahead inputs on sale and lookup screens.
​
q
string
required
Search term matched against both name and barcode. Returns an empty array if the parameter is missing or blank.

​
Response

Returns a JSON array of up to 10 product objects. An empty array [] is returned when no products match or the q parameter is empty — this is not an error condition.
​
id
integer
Unique product ID.
​
barcode
string
Product barcode.
​
name
string
Product name.
​
description
string
Product description.
​
stock
integer
Current quantity available.
​
price
number
Unit sale price.
StatusMeaning
200Search completed (may return empty array).
401No active session.

Build docs developers (and LLMs) love

Get started for freeTalk to us