Skip to main content

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.

The billing module in La Oficina Nítida lets each educational operator maintain a customer catalogue, a product/service catalogue, and a complete invoice ledger — all scoped to the authenticated tenant so data never crosses organisational boundaries. The module is implemented with three resource groups (customers, products, and invoices) backed by the Customer, ProductService, and Invoice Prisma models.

​
Billing Dashboard

GET /billing/dashboard returns a real-time snapshot of the tenant’s billing activity. The service resolves two parallel queries — a customer count and an invoice group-by — and returns the following fields:
FieldTypeDescription
clientesActivosnumberCount of customers with status = ACTIVE
facturasEmitidasnumberTotal number of invoices with status = ISSUED
facturasBorradornumberTotal number of invoices with status = DRAFT
ingresosEstimadosnumberSum of total across all ISSUED invoices
totalFacturadonumberGross billed amount — same source as ingresosEstimados
All monetary values are in Colombian pesos (COP) and are computed on demand from the invoices table — no cached counters are used.

​
Invoice Status Lifecycle

Every Invoice record moves through a linear state machine driven by the InvoiceStatus enum: 
DRAFT → ISSUED → CANCELLED
StatusMeaning
DRAFTThe invoice is editable and has not yet been confirmed.
ISSUEDThe invoice has been issued to the customer. Totals are finalised.
CANCELLEDThe invoice has been voided. A cancelled invoice cannot be modified — the server returns 400 Bad Request on any further status update.
Only ADMIN users may call PATCH /billing/invoices/:id/status to advance or change state.

​
Invoice Totals Calculation

When a new invoice is created, the server derives financial totals automatically from the submitted line items. You must not send subtotal, impuestos, or total in the request body — they will be ignored. The calculation applied per invoice is: 
subtotal   = Σ (cantidad × valorUnitario)  for all items
impuestos  = subtotal × 0.19
total      = subtotal + impuestos
Each line item also stores its own subtotal snapshot (cantidad × valorUnitario), so the invoice remains accurate even if the underlying product catalogue changes later.

​
Authentication and Authorisation

All billing endpoints require a valid JWT (JwtAuthGuard) and an active tenant (ActiveTenantGuard). Role requirements per operation are:
OperationMinimum Role
Read any resourceVIEWER, OPERADOR, or ADMIN
Create / update a customerADMIN or OPERADOR
Create an invoiceADMIN or OPERADOR
Create / update a productADMIN only
Delete a customerADMIN only
Update invoice statusADMIN only

​
Explore the Module

Customers

Create and manage billing customers with Colombian fiscal data: NIT and contact information.

Invoices

Create invoices with line items and manage their lifecycle from draft to issued or cancelled.

Build docs developers (and LLMs) love

Get started for freeTalk to us