Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Glemynart/SaaS/llms.txt
Use this file to discover all available pages before exploring further.
Invoices in La Oficina Nítida are Invoice records that capture a complete billing transaction: the customer’s identity, one or more line items with quantities and unit prices, and server-calculated totals. Every invoice is tenant-scoped and its line items are stored as immutable subtotal snapshots — if a product’s price changes after the invoice is issued, the invoice retains the original values. Status transitions (DRAFT → ISSUED → CANCELLED) are enforced server-side and only ADMIN users may change invoice status.
Products
Products and services available for invoicing are managed through the ProductService catalogue.
List Products
Returns all active products for the authenticated tenant, ordered by nombre ascending. Inactive products are excluded automatically.
Query parameters
| Parameter | Description |
|---|
search | Optional free-text filter on nombre (case-insensitive) |
Create a Product
Roles allowed: ADMIN only.
Request body — CreateProductDto
| Field | Type | Required | Description |
|---|
nombre | string | ✅ | Product or service name |
descripcion | string | — | Optional longer description |
precio | number | ✅ | Base price in COP (must be ≥ 0) |
impuesto | number | — | Default tax percentage (e.g. 19). Defaults to 19 in the database. |
Get a Single Product
GET /billing/products/:id
404 Not Found if the product does not belong to the authenticated tenant.
Update a Product
PATCH /billing/products/:id
ADMIN only.
Request body — UpdateProductDto (all fields optional)
| Field | Type | Description |
|---|
nombre | string | Updated name |
descripcion | string | Updated description |
precio | number | Updated base price (must be ≥ 0) |
impuesto | number | Updated tax percentage (must be ≥ 0) |
activo | boolean | Set to false to deactivate the product |
Creating an Invoice
Roles allowed: ADMIN, OPERADOR.
The server validates that the referenced customerId exists within the tenant before creating the invoice. The subtotal, impuestos, and total fields are calculated server-side from the line items — do not send them in the request body.
Request Body — CreateInvoiceDto
| Field | Type | Required | Description |
|---|
customerId | string (UUID) | ✅ | ID of the Customer record to invoice |
numero | string | ✅ | Invoice number (e.g. "FV-0001"). Must be unique within the tenant. |
items | InvoiceItemDto[] | ✅ | Array of line items. Must contain at least one item. |
Line Items — InvoiceItemDto
Each element in the items array represents a single product or service line on the invoice.
| Field | Type | Required | Description |
|---|
productServiceId | string (UUID) | — | Optional reference to a ProductService catalogue entry |
descripcion | string | ✅ | Text description of the product or service |
cantidad | number | ✅ | Quantity (minimum 0.001, up to three decimal places) |
valorUnitario | number | ✅ | Unit price in COP (must be ≥ 0) |
subtotal as cantidad × valorUnitario and derives the invoice-level subtotal, impuestos (19 %), and total automatically.
Example Request
curl -X POST "https://api.example.com/billing/invoices" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"customerId": "c1d2e3f4-a1b2-4c3d-8e9f-0a1b2c3d4e5f",
"numero": "FV-0001",
"items": [
{
"productServiceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"descripcion": "Servicio de matrícula – Grado 5°",
"cantidad": 1,
"valorUnitario": 850000
},
{
"descripcion": "Material didáctico",
"cantidad": 3,
"valorUnitario": 45000
}
]
}'
Invoice object with status: "DRAFT", the server-calculated subtotal, impuestos, and total, and all line items including their computed subtotal values. The response also includes the customer’s razonSocial and nit.
Querying Invoices
List Invoices
Returns all invoices for the authenticated tenant, ordered by createdAt descending. Each result includes the customer’s razonSocial and nit, and a count of line items.
Query parameters
| Parameter | Description |
|---|
status | Filter by invoice state: DRAFT, ISSUED, or CANCELLED |
Get a Single Invoice
GET /billing/invoices/:id
items and the complete customer record. Returns 404 Not Found if the invoice does not belong to the authenticated tenant.
Invoice State Management
PATCH /billing/invoices/:id/status
ADMIN only.
Updates the status of an invoice. The server enforces the state machine — a CANCELLED invoice cannot be modified and will return 400 Bad Request.
Request body — UpdateInvoiceStatusDto
| Field | Type | Required | Description |
|---|
status | InvoiceStatus | ✅ | The new status: DRAFT, ISSUED, or CANCELLED |
Once an invoice is set to CANCELLED, it cannot be modified further. The server returns 400 Bad Request on any subsequent status update to a cancelled invoice.