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 Sales API handles every part of the transaction lifecycle in StockManager. Authenticated users can record single-product sales or multi-item bulk transactions in one atomic call. The history endpoints expose paginated, filterable records with full product breakdowns. Admin and root users additionally have access to endpoints for retrieving sales in an edit-friendly format and applying corrections to previously recorded transactions.

​
POST /api/sales

Records a sale for a single product identified by its barcode. Stock is decremented immediately on success.

​
Request Body

​
barcode
string
required
The barcode of the product to sell. Must match an active product (status = 1).
​
quantity
integer
required
Number of units to sell. Must not exceed the product’s current stock.
​
payment_method
string
default:"Efectivo"
Payment method label (e.g. "Efectivo", "Tarjeta"). Defaults to "Efectivo" if omitted.

​
Response

​
message
string
Human-readable confirmation, e.g. "Venta registrada: Leche Entera 1L x2".
​
product
string
Name of the product sold.
​
quantity
integer
Number of units sold.
​
total
number
Total transaction amount (price × quantity).
201 Created
{
  "message": "Venta registrada: Leche Entera 1L x2",
  "product": "Leche Entera 1L",
  "quantity": 2,
  "total": 45.0
}
StatusMeaning
201Sale recorded successfully.
400Missing required fields, invalid quantity, or insufficient stock.
401No active session.
404No active product found for the given barcode.

​
POST /api/sales/bulk

Records a multi-product sale in a single atomic database transaction. All stock validations are performed before any inventory is decremented — if any item fails, the entire sale is rejected and no changes are persisted.
Stock validation is fully atomic. If even one item in the items array has insufficient stock or is disabled, the entire request is rejected with 400 and no products are decremented. Ensure all quantities are available before submitting.

​
Request Body

​
items
array
required
Array of one or more item objects to include in the sale. Must not be empty.
​
payment_method
string
default:"Efectivo"
Payment method label for the entire transaction. Defaults to "Efectivo" if omitted.

​
Response

​
ok
boolean
true when the sale was created successfully.
​
sale_id
integer
ID of the newly created sale record.
​
items
array
Array of line-item result objects, one per submitted item.
​
total
number
Grand total across all line items, rounded to 2 decimal places.
Example — bulk sale with two products
curl -X POST "http://localhost:5000/api/sales/bulk" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -d '{
    "items": [
      { "item_id": 7, "quantity": 2 },
      { "item_id": 12, "quantity": 1 }
    ],
    "payment_method": "Tarjeta"
  }'
201 Created
{
  "ok": true,
  "sale_id": 304,
  "items": [
    {
      "item_id": 7,
      "name": "Leche Entera 1L",
      "quantity": 2,
      "unit_price": 22.5,
      "subtotal": 45.0
    },
    {
      "item_id": 12,
      "name": "Pan Integral 500g",
      "quantity": 1,
      "unit_price": 18.0,
      "subtotal": 18.0
    }
  ],
  "total": 63.0
}
StatusMeaning
201All items sold and sale recorded.
400Invalid format, empty items array, insufficient stock, or disabled product.
401Session is missing or user ID could not be resolved.

​
GET /api/sales

Returns a paginated, filterable list of sales transactions sorted by date descending. Each record includes a breakdown of the products involved.
​
from
string
Start date filter (inclusive) in YYYY-MM-DD format. Filters on the sale’s local date.
​
to
string
End date filter (inclusive) in YYYY-MM-DD format.
​
product
string
Partial match filter on the product name. Returns sales that contain at least one product whose name matches the search string.
​
vendedor
string
Partial match filter on the vendor’s username or email. Case-insensitive.
​
page
integer
default:"1"
1-based page number.
​
limit
integer
default:"10"
Sales per page. Clamped between 1 and 100.

​
Response

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

​
GET /api/sales/:id

Returns the complete details of a single sale transaction by its ID.

​
Path Parameter

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

​
Response

​
id
integer
Unique sale ID.
​
date
string
Date and time the sale was recorded.
​
products
array
Array of product line items.
​
total
number
Grand total across all line items.
​
vendedor
string
Username of the vendor who recorded the sale.
​
vendor_id
integer
Numeric ID of the vendor user.
​
payment_method
string
Payment method used.
StatusMeaning
200Sale found and returned.
401No active session.
404No sale found with the given ID.

​
GET /api/sales/:id/edit

Returns sale data structured for editing. This endpoint is restricted to admin and root roles and is intended to power administrative correction workflows.

​
Path Parameter

​
id
integer
required
The unique integer ID of the sale to retrieve for editing.

​
Response

Returns the sale record as a JSON object suitable for pre-populating an edit form. Structure matches the response from GET /api/sales/:id with any additional edit-mode fields provided by the database layer.
StatusMeaning
200Sale data returned in edit format.
401No active session.
403Authenticated user lacks admin or root role.
404No sale found with the given ID.
500Internal error while retrieving sale.

​
PUT /api/sales/:id

Updates the items, vendor, and payment method of an existing sale. Requires the admin or root role. Stock levels are recalculated automatically after the update.

​
Path Parameter

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

​
Request Body

​
items
array
required
Replacement list of line items for the sale. Must be a non-empty array.
​
vendor_id
integer
required
ID of the vendor to associate with the sale.
​
payment_method
string
required
Updated payment method label.

​
Response

200 OK
{
  "message": "Venta actualizada exitosamente"
}
StatusMeaning
200Sale updated successfully.
400Invalid items format, missing vendor_id or payment_method, or a stock validation error.
401No active session.
403Authenticated user lacks admin or root role.
500Internal error during update.
Low-stock checks run automatically after every sale update. If any product’s remaining stock falls at or below its min_quantity, the acting admin receives an in-app notification.

Build docs developers (and LLMs) love

Get started for freeTalk to us