Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Carlos-Gnd/FERRED-Inventario-y-Ventas/llms.txt

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

The products API manages the merchandise catalog. Products can be searched by name or barcode, created with automatic price calculation (cost + margin = sale price + IVA), and operated offline with automatic sync. All write endpoints require the ADMIN or BODEGA role, while read endpoints are accessible to all authenticated roles. Base URL: https://server-production-3252.up.railway.app
When the server cannot reach the cloud database, read operations fall back to the local SQLite replica transparently. For creates and updates, the operation is saved locally with a temporary negative ID and synced automatically when connectivity is restored.

​
GET /api/productos

Returns an array of active products, optionally filtered and including per-branch stock. Required role: Any authenticated user (ADMIN, CAJERO, BODEGA)

​
Query parameters

​
buscar
string
Free-text search. Matches against nombre (case-insensitive) and codigoBarras.
​
categoriaId
number
Filter to products belonging to this category ID.
​
criticos
boolean
When true, returns only products where current stock is at or below the minimum threshold (stockActual <= stockMinimo, or per-branch stock when sucursalId is provided).
​
sucursalId
number
Include per-branch stock (cantidad, minimo) for this branch. Defaults to the authenticated user’s own sucursalId. Users can only query their own branch.

​
Response

Array of product objects.
​
id
number
Unique product ID.
​
nombre
string
Product name.
​
codigoBarras
string | null
Barcode (unique).
​
tipoUnidad
string | null
Unit type: UNIDAD, CAJA, PESO, MEDIDA, or LOTE.
​
categoriaId
number | null
ID of the associated category.
​
categoria
object | null
​
precioCompra
number | null
Purchase cost.
​
porcentajeGanancia
number | null
Margin percentage used to calculate sale price.
​
precioVenta
number | null
Sale price before IVA.
​
precioConIva
number | null
Sale price including 13% IVA (when tieneIva is true).
​
tieneIva
boolean
Whether IVA applies. Defaults to true.
​
stockActual
number
Aggregate stock across all branches.
​
stockMinimo
number
Minimum stock threshold for low-stock alerts.
​
activo
boolean
Whether the product is active. Always true in list results.
​
stocks
object[]
Present only when sucursalId is resolved. Per-branch stock entry.
list products
curl --request GET \
  --url 'https://server-production-3252.up.railway.app/api/productos?buscar=tornillo&criticos=false' \
  --header 'Authorization: Bearer <token>'

​
GET /api/productos/barcode/:codigo

Look up a single active product by its barcode. Useful at point of sale when a scanner reads a barcode. Required role: Any authenticated user

​
Path parameters

​
codigo
string
required
The barcode string to look up. Must match the codigoBarras field exactly.

​
Response

Single product object with categoria included (same shape as the list response), or 404 if not found.

​
GET /api/productos/:id/stock/:sucursalId

Returns the stock record for a specific product at a specific branch. Required role: ADMIN, CAJERO, or BODEGA
Users can only query stock for their own branch. Requests for a different branch’s stock return 403.

​
Path parameters

​
id
number
required
Product ID.
​
sucursalId
number
required
Branch ID.

​
Response

​
productoId
number
Product ID.
​
sucursalId
number
Branch ID.
​
cantidad
number
Current stock quantity at this branch. Returns 0 if no stock record exists yet.
​
minimo
number
Minimum threshold at this branch. Returns 0 if no stock record exists yet.

​
POST /api/productos

Creates a new product. If precioCompra and porcentajeGanancia are both provided, precioVenta and precioConIva are calculated automatically. Required role: ADMIN or BODEGA Price calculation:
  • precioVenta = precioCompra × (1 + porcentajeGanancia / 100) (rounded to 2 decimal places)
  • precioConIva = precioVenta × 1.13 when tieneIva is true, otherwise equals precioVenta

​
Request body

​
nombre
string
required
Product name. Minimum 2 characters.
​
categoriaId
number
ID of the category to associate. Must be a positive integer.
​
codigoBarras
string
Barcode string. Must be globally unique.
​
tipoUnidad
string
Unit type. One of: UNIDAD, CAJA, PESO, MEDIDA, LOTE.
​
precioCompra
number
Purchase cost. Must be ≥ 0.
​
porcentajeGanancia
number
Margin percentage (e.g. 30 for 30%). Must be ≥ 0. Used with precioCompra for automatic price calculation.
​
precioVenta
number
Sale price before IVA. Overridden by automatic calculation when precioCompra and porcentajeGanancia are both provided.
​
tieneIva
boolean
default:"true"
Whether 13% IVA applies to this product.
​
stockActual
number
default:"0"
Initial stock quantity. Must be a non-negative integer.
​
stockMinimo
number
default:"0"
Minimum stock threshold for low-stock alerts. Must be a non-negative integer.

​
Response

​
mensaje
string
Confirmation message: "Producto creado".
​
producto
object
The newly created product (same shape as list response, with categoria included).
create product
curl --request POST \
  --url https://server-production-3252.up.railway.app/api/productos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nombre": "Tornillo hexagonal 1/4\"",
    "categoriaId": 3,
    "codigoBarras": "7501234567890",
    "tipoUnidad": "UNIDAD",
    "precioCompra": 0.50,
    "porcentajeGanancia": 40,
    "tieneIva": true,
    "stockActual": 200,
    "stockMinimo": 20
  }'

​
PUT /api/productos/:id

Partially updates an existing product. Only the fields included in the request body are updated. Price recalculation applies when both precioCompra and porcentajeGanancia are present in the update payload. Required role: ADMIN or BODEGA

​
Path parameters

​
id
number
required
ID of the product to update.

​
Request body

All fields are optional (partial update). See POST /api/productos for field definitions.

​
Response

​
mensaje
string
Confirmation: "Producto actualizado" (or "Producto actualizado offline" in offline mode).
​
producto
object
The updated product object. Not present in offline mode.

​
DELETE /api/productos/:id

Soft-deletes a product by setting activo = false. The product is hidden from all list and barcode endpoints but its data is preserved for historical invoice records. Required role: ADMIN only

​
Path parameters

​
id
number
required
ID of the product to deactivate. If the ID is negative (a locally-pending offline product), the pending local record is removed entirely instead.

​
Response

​
mensaje
string
"Producto desactivado" (online) or "Producto eliminado offline" / "Producto eliminado localmente" (offline).

​
POST /api/productos/:id/descontar-stock

Decrements stock for a product at a specific branch. Used at point of sale when processing a sale. Runs in a database transaction to prevent overselling. Required role: ADMIN or CAJERO

​
Path parameters

​
id
number
required
ID of the product whose stock to decrement.

​
Request body

​
cantidad
number
required
Quantity to deduct. Must be a positive number.
​
sucursalId
number
required
Branch from which to deduct stock.

​
Response

​
mensaje
string
Confirmation: "Stock descontado" (or "Stock actualizado offline").
​
stockRestante
number
Remaining stock at the branch after the deduction. Not present in offline mode.

​
Error responses

StatusCondition
400cantidad is missing or ≤ 0, or sucursalId is missing.
409Insufficient stock. Response includes disponible, solicitado, and sucursalId.

Build docs developers (and LLMs) love

Get started for freeTalk to us