The suppliers API manages the list of suppliers and records goods reception (recepción de mercancía) which automatically updates branch stock levels when new inventory arrives.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.
When a goods reception is created, each item in the
items array triggers an atomic upsert on StockSucursal — incrementing the cantidad in the specified branch if a record already exists, or creating a new one if it does not. The overall stockActual on the product is also recalculated after the transaction commits.GET /api/proveedores
Returns all active suppliers ordered alphabetically by name. Roles: All authenticated usersResponse
Returns an array ofProveedor records.
POST /api/proveedores
Creates a new supplier. Thenit field must be unique — the request fails if another supplier already has the same NIT.
Roles: ADMIN, BODEGA
Body
Supplier name. Minimum 2 characters.
Tax ID. Must be unique across all suppliers.
Contact phone number.
Contact email address. Must be a valid email format.
Physical address.
Response 201
Confirmation message:
"Proveedor creado".The newly created
Proveedor record.Errors
| Status | Condition |
|---|---|
| 400 | Validation failed (e.g., nombre too short, invalid email, or duplicate nit). |
PUT /api/proveedores/:id
Updates an existing supplier. All fields are optional — only provided fields are changed. Roles: ADMIN, BODEGAPath parameters
ID of the supplier to update.
Body
All body fields are optional (partial update).Updated supplier name. Minimum 2 characters.
Updated tax ID.
Updated phone number.
Updated email address. Must be valid format.
Updated address.
Response 200
Confirmation message:
"Proveedor actualizado".The updated
Proveedor record.DELETE /api/proveedores/:id
Soft-deletes a supplier by settingactivo = false. The supplier’s historical reception records are preserved.
Roles: ADMIN
Path parameters
ID of the supplier to deactivate.
Response 200
Confirmation message:
"Proveedor desactivado".POST /api/proveedores/recepcion
Registers a goods reception from a supplier and atomically increments stock for each item in the specified branch. Roles: ADMIN, BODEGA Non-ADMIN users can only receive goods for their assigned branch. Passing asucursalId that differs from the user’s assigned branch returns a 403.
Body
ID of the supplier delivering the goods. Must be active.
ID of the branch receiving the goods.
Optional supplier invoice number for reference.
Optional free-text notes about this reception.
List of products being received. Must contain at least one entry.
Response 201
Always
true on success.The created
RecepcionMercancia record with full relations.Errors
| Status | Condition |
|---|---|
| 400 | Validation failed (missing required fields or invalid values). |
| 403 | Non-ADMIN user attempted to receive goods in a different branch, or has no branch assigned. |
| 404 | Supplier or one or more products not found or inactive. |
GET /api/proveedores/recepciones
Lists goods receptions. ADMIN users see all receptions; other roles see only receptions for their assigned branch. Returns up to 100 records ordered by creation date descending. Roles: All authenticated usersResponse
Returns an array ofRecepcionMercancia records.
GET /api/proveedores/recepciones/:id
Returns a single goods reception with full detail, including all received items and their products. Roles: All authenticated usersPath parameters
ID of the reception to retrieve.
Response
The fullRecepcionMercancia record including all relations.
Reception ID.
Full supplier record.
Branch name.
User name.
Errors
| Status | Condition |
|---|---|
| 403 | Non-ADMIN user attempted to view a reception belonging to a different branch. |
| 404 | Reception not found. |