Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juadariasmar/inventory_project/llms.txt

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

The Purchase Orders API lets you manage the full lifecycle of supplier orders within your tenant. Orders begin as BORRADOR (draft), where items can be set and reviewed. When goods arrive, you call the recibir endpoint, which atomically creates Movimiento (entrada) records for each line item and increments each product’s stock count. Orders can also be cancelled before receiving. A built-in PDF renderer generates a print-ready document for any order, and a suggestions endpoint surfaces products whose current stock has dropped at or below their configured minimum threshold. All write operations (POST) and the purchase-suggestion endpoint require the ADMIN role. Read operations are available to any active user belonging to the tenant.

​
Endpoints

MethodPathDescription
GET/api/ordenes-compraList all purchase orders for the tenant
POST/api/ordenes-compraCreate a new draft purchase order
GET/api/ordenes-compra/[id]Get a single purchase order with items and supplier
POST/api/ordenes-compra/[id]/recibirMark an order as received; creates stock movements
POST/api/ordenes-compra/[id]/cancelarCancel a draft order
GET/api/pdf/orden-compra/[id]Download a PDF of the purchase order
GET/api/compras/sugerenciasList products at or below their minimum stock level
POST/api/compras/sugerenciasCreate a draft order directly from suggestion data

​
GET /api/ordenes-compra

Returns all purchase orders for the authenticated user’s tenant, sorted newest first. Each record includes the supplier name and a count of line items.

​
Response fields

​
id
number
Unique identifier for the purchase order.
​
proveedorId
number
ID of the supplier linked to this order.
​
proveedor
object
Partial supplier object. Contains nombre (string).
​
estado
string
Current state of the order: BORRADOR, RECIBIDA, or CANCELADA.
​
total
number
Computed total cost of all line items (sum of cantidad × costoUnitario per item).
​
notas
string | null
Optional free-text notes on the order.
​
creadoEn
string
ISO 8601 timestamp of when the order was created.
​
recibidaEn
string | null
ISO 8601 timestamp of when the order was received. null if not yet received.
​
_count.items
number
Number of line items in the order.
curl -b 'session=...' \
  'https://your-domain.com/api/ordenes-compra'

​
POST /api/ordenes-compra

Creates a new purchase order with status BORRADOR. Requires ADMIN role. The total field is computed automatically from the submitted items.

​
Request body

​
proveedorId
number
required
ID of the supplier. Must belong to the same tenant.
​
items
array
required
Array of line items. Must contain at least one entry.
​
items[].productoId
number
required
ID of the product to order.
​
items[].cantidad
number
required
Integer quantity to order. Must be greater than 0.
​
items[].costoUnitario
number
required
Unit cost for the product. Must be a non-negative number.
​
notas
string
Optional free-text notes.

​
Response fields

Returns the created OrdenCompra object (HTTP 201), including all items and the linked proveedor.
​
id
number
Assigned order ID.
​
estado
string
Always BORRADOR on creation.
​
total
number
Sum of all item subtotals.
​
items
array
Array of OrdenCompraItem objects.
​
items[].productoId
number
Product ID.
​
items[].cantidad
number
Ordered quantity.
​
items[].costoUnitario
number
Unit cost.
​
items[].subtotal
number
Line subtotal (cantidad × costoUnitario).
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/ordenes-compra' \
  -H 'Content-Type: application/json' \
  -d '{
    "proveedorId": 3,
    "notas": "Urgente para semana de inventario",
    "items": [
      { "productoId": 12, "cantidad": 50, "costoUnitario": 4500 },
      { "productoId": 17, "cantidad": 20, "costoUnitario": 12000 }
    ]
  }'

​
GET /api/ordenes-compra/[id]

Returns a single purchase order identified by its numeric id, including all line items (with product nombre and codigo) and full supplier details.

​
Path parameters

​
id
number
required
Numeric purchase order ID.

​
Response fields

​
id
number
Purchase order ID.
​
estado
string
Order state: BORRADOR, RECIBIDA, or CANCELADA.
​
total
number
Order total.
​
notas
string | null
Free-text notes.
​
creadoEn
string
Creation timestamp (ISO 8601).
​
recibidaEn
string | null
Reception timestamp, or null.
​
proveedor
object
Supplier details: id, nombre, nit, telefono, contacto, direccion, email.
​
items
array
Array of line items, each with productoId, cantidad, costoUnitario, subtotal, and a nested producto object containing nombre and codigo.
curl -b 'session=...' \
  'https://your-domain.com/api/ordenes-compra/42'

​
POST /api/ordenes-compra/[id]/recibir

Marks a BORRADOR order as RECIBIDA. This operation runs inside a database transaction and performs the following steps atomically:
  1. Acquires a row-level lock on all affected Producto rows (ordered by ID to prevent deadlocks).
  2. Creates one Movimiento of type entrada per line item, linked to the order.
  3. Increments each product’s cantidad by the ordered amount.
  4. Sets the order’s estado to RECIBIDA and records recibidaEn.
No request body is required. Requires ADMIN role. Returns 409 Conflict if the order is already received or cancelled.

​
Path parameters

​
id
number
required
Numeric purchase order ID.

​
Response fields

​
id
number
Order ID.
​
estado
string
Always RECIBIDA on success.
​
recibidaEn
string
Timestamp when reception was recorded (ISO 8601).
​
items
array
Updated array of line items.
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/ordenes-compra/42/recibir'

​
POST /api/ordenes-compra/[id]/cancelar

Cancels a purchase order. Only orders in BORRADOR state can be cancelled — calling this on a RECIBIDA or already CANCELADA order returns 409 Conflict. No request body is required. Requires ADMIN role.

​
Path parameters

​
id
number
required
Numeric purchase order ID.

​
Response fields

​
id
number
Order ID.
​
estado
string
Always CANCELADA on success.
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/ordenes-compra/42/cancelar'

​
GET /api/pdf/orden-compra/[id]

Generates and streams a PDF document for the specified purchase order directly in memory using pdf-lib. The document includes supplier details, order metadata (date, status), a formatted line-item table with product codes and names, and the order total formatted in Colombian pesos. The response content type is application/pdf with an inline content-disposition header.

​
Path parameters

​
id
number
required
Numeric purchase order ID.

​
Response

Returns a binary PDF stream. Save to a file using the -o flag or open directly in a browser. 
curl -b 'session=...' \
  'https://your-domain.com/api/pdf/orden-compra/42' \
  -o orden-compra-42.pdf

​
GET /api/compras/sugerencias

Returns a list of products whose current cantidad is at or below their stockMinimo threshold. This endpoint is intended to drive the “create order from suggestion” workflow. Requires ADMIN role. The response is generated by SugerenciasCompraService.generarSugerencias, which also computes a recommended purchase quantity based on 30-day consumption history.

​
Response fields

​
[].productoId
number
Product ID.
​
[].nombre
string
Product name.
​
[].codigo
string
Product SKU code.
​
[].cantidadActual
number
Current stock level.
​
[].stockMinimo
number
Configured minimum stock threshold.
​
[].consumoDiarioPromedio
number
Average daily consumption over the last 30 days (rounded to 2 decimal places).
​
[].sugerenciaCompra
number
Recommended reorder quantity calculated to cover 14 days of projected demand.
curl -b 'session=...' \
  'https://your-domain.com/api/compras/sugerencias'

​
POST /api/compras/sugerencias

Creates a draft OrdenCompra directly from suggestion data. Requires ADMIN role. Returns the created order (HTTP 201).

​
Request body

​
proveedorId
number
required
ID of the supplier to assign to the new draft order.
​
items
array
required
Array of line items to include. Each entry requires productoId, cantidad, and costoUnitario.
curl -b 'session=...' \
  -X POST 'https://your-domain.com/api/compras/sugerencias' \
  -H 'Content-Type: application/json' \
  -d '{
    "proveedorId": 3,
    "items": [
      { "productoId": 12, "cantidad": 50, "costoUnitario": 4500 }
    ]
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us