Billing API — manage customers, products, and invoices

The Billing API covers the full invoicing workflow for La Oficina Nítida: customer management (with Colombian fiscal data), a product/service catalogue, and invoice lifecycle management. All data is strictly scoped to the authenticated tenant. The numero field on an invoice is provided by the client in the request body.

Enumerations

Customer status — `CustomerStatus`

Value	Description
`ACTIVE`	Active customer
`INACTIVE`	Inactive customer

Invoice status — `InvoiceStatus`

Value	Description
`DRAFT`	Draft — editable, not yet transmitted
`ISSUED`	Issued — transmitted and accepted
`CANCELLED`	Cancelled — terminal state, no further modification

Dashboard

Get billing dashboard

GET /billing/dashboard

Returns a summary of the tenant’s billing activity. Useful for building KPI cards in the front-end.

Response

clientesActivos

integer

Count of customers with status ACTIVE.

facturasEmitidas

integer

Count of invoices with status ISSUED.

facturasBorrador

integer

Count of invoices with status DRAFT.

ingresosEstimados

number

Sum of total across all ISSUED invoices (Colombian pesos).

totalFacturado

number

Equivalent to ingresosEstimados — total value of all issued invoices.

curl -X GET "https://api.example.com/billing/dashboard" \
  -H "Authorization: Bearer {accessToken}"

Customers

List customers

GET /billing/customers

Returns all customers for the tenant, ordered alphabetically by razonSocial.

Query parameters

string

Case-insensitive partial match against razonSocial or exact prefix match against nit.

curl -X GET "https://api.example.com/billing/customers?search=Acme" \
  -H "Authorization: Bearer {accessToken}"

Create a customer

POST /billing/customers

Creates a new billing customer. The nit must be unique within the tenant. Required roles: ADMIN, OPERADOR

Request body

Legal business name or full name of the customer.

nit

string

required

Colombian NIT (without check digit) or national ID number. Must be unique per tenant.

string

Contact email address. Used for automatic invoice delivery.

telefono

string

Contact phone number.

direccion

string

Postal address.

Response

Returns the created Customer object including the server-assigned id, status: "ACTIVE", and createdAt.

curl -X POST "https://api.example.com/billing/customers" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "razonSocial": "Empresa Ejemplo S.A.S.",
    "nit": "900123456",
    "email": "facturacion@empresa.com",
    "telefono": "6014567890",
    "direccion": "Calle 72 # 10-34, Bogotá"
  }'

Get a customer

GET /billing/customers/:id

Returns a single customer by UUID.

Path parameters

string

required

UUID of the customer.

curl -X GET "https://api.example.com/billing/customers/a1b2c3d4-0000-0000-0000-aabbccddeeff" \
  -H "Authorization: Bearer {accessToken}"

Update a customer

PATCH /billing/customers/:id

Partially updates a customer. Only the fields provided in the body are changed. Required roles: ADMIN, OPERADOR

Path parameters

string

required

UUID of the customer to update.

Request body

Updated legal name.

nit

string

Updated NIT. Must remain unique within the tenant.

string

Updated email address.

telefono

string

Updated phone number.

direccion

string

Updated postal address.

status

string

Customer lifecycle status. Accepted values: ACTIVE, INACTIVE.

curl -X PATCH "https://api.example.com/billing/customers/a1b2c3d4-0000-0000-0000-aabbccddeeff" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{"status": "INACTIVE"}'

Delete a customer

DELETE /billing/customers/:id

Permanently removes a customer record from the tenant. Required role: ADMIN

Path parameters

string

required

UUID of the customer to delete.

curl -X DELETE "https://api.example.com/billing/customers/a1b2c3d4-0000-0000-0000-aabbccddeeff" \
  -H "Authorization: Bearer {accessToken}"

Products & services

List products

GET /billing/products

Returns all active products and services for the tenant, ordered alphabetically by nombre.

Query parameters

string

Case-insensitive partial match against nombre.

curl -X GET "https://api.example.com/billing/products?search=consultoría" \
  -H "Authorization: Bearer {accessToken}"

Create a product

POST /billing/products

Adds a new product or service to the tenant’s catalogue. Required role: ADMIN

Request body

nombre

string

required

Display name of the product or service.

descripcion

string

Optional extended description.

precio

number

required

Base unit price in Colombian pesos (COP). Must be ≥ 0.

impuesto

number

Tax rate percentage to apply on this product (e.g. 19 for 19 % IVA). Must be ≥ 0.

Response

Returns the created product including id, activo: true, and createdAt.

curl -X POST "https://api.example.com/billing/products" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Consultoría de RRHH",
    "descripcion": "Servicio mensual de asesoría laboral",
    "precio": 2500000,
    "impuesto": 19
  }'

Get a product

GET /billing/products/:id

Returns a single product by UUID.

Path parameters

string

required

UUID of the product.

curl -X GET "https://api.example.com/billing/products/b2c3d4e5-0000-0000-0000-112233445566" \
  -H "Authorization: Bearer {accessToken}"

Update a product

PATCH /billing/products/:id

Partially updates a product. Only supplied fields are modified. Required role: ADMIN

Path parameters

string

required

UUID of the product to update.

Request body

nombre

string

Updated product name.

descripcion

string

Updated description.

precio

number

Updated unit price. Must be ≥ 0.

impuesto

number

Updated tax rate percentage. Must be ≥ 0.

activo

boolean

Set to false to deactivate a product from the catalogue.

curl -X PATCH "https://api.example.com/billing/products/b2c3d4e5-0000-0000-0000-112233445566" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{"precio": 2800000}'

Invoices

List invoices

GET /billing/invoices

Returns all invoices for the tenant, ordered by createdAt descending. Each result includes the customer’s razonSocial and nit, and a count of line items.

Query parameters

status

string

Filter by invoice status. Accepted values: DRAFT, ISSUED, CANCELLED.

curl -X GET "https://api.example.com/billing/invoices?status=ISSUED" \
  -H "Authorization: Bearer {accessToken}"

Create an invoice

POST /billing/invoices

Creates a new invoice and calculates subtotal, impuestos, and total server-side. The customerId must belong to the same tenant. Required roles: ADMIN, OPERADOR

Request body

customerId

string

required

UUID of an existing customer within the tenant.

numero

string

required

Invoice number string (e.g. "FV-0042"). See the warning below regarding numbering.

items

InvoiceItemDto[]

required

One or more line items. Must not be empty.

Show InvoiceItemDto fields

descripcion

string

required

Line item description. Shown on the printed invoice.

cantidad

number

required

Quantity. Must be > 0. Supports up to three decimal places (e.g., 2.5).

valorUnitario

number

required

Unit price in COP. Must be ≥ 0.

productServiceId

string

UUID of a product from the catalogue. When provided, the line is linked to the product for reporting purposes. The price and description are still taken from this request (snapshot semantics).

Response

Returns the created invoice object including computed subtotal, impuestos, total, embedded items, and the customer’s razonSocial and nit.

curl -X POST "https://api.example.com/billing/invoices" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "a1b2c3d4-0000-0000-0000-aabbccddeeff",
    "numero": "FV-0042",
    "items": [
      {
        "descripcion": "Consultoría de RRHH — Enero 2025",
        "cantidad": 1,
        "valorUnitario": 2500000,
        "productServiceId": "b2c3d4e5-0000-0000-0000-112233445566"
      }
    ]
  }'

The numero field is a client-supplied string (e.g. "FV-0042"). Ensure your client generates unique, non-conflicting invoice numbers — the server does not auto-assign or validate uniqueness of this field.

Get an invoice

GET /billing/invoices/:id

Returns a single invoice by UUID, including all line items and full customer details.

Path parameters

string

required

UUID of the invoice.

curl -X GET "https://api.example.com/billing/invoices/c3d4e5f6-0000-0000-0000-223344556677" \
  -H "Authorization: Bearer {accessToken}"

Update invoice status

PATCH /billing/invoices/:id/status

Transitions an invoice to a new lifecycle state. A CANCELLED invoice cannot be modified further and will return 400 Bad Request. Required role: ADMIN

Path parameters

string

required

UUID of the invoice.

Request body

status

string

required

Target status. Accepted values: DRAFT, ISSUED, CANCELLED.

curl -X PATCH "https://api.example.com/billing/invoices/c3d4e5f6-0000-0000-0000-223344556677/status" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{"status": "ISSUED"}'

Authentication

People & Contracts

Operations

Documentation Index

​Enumerations

​Customer status — CustomerStatus

​Invoice status — InvoiceStatus

​Dashboard

​Get billing dashboard

​Response

​Customers

​List customers

​Query parameters

​Create a customer

​Request body

​Response

​Get a customer

​Path parameters

​Update a customer

​Path parameters

​Request body

​Delete a customer

​Path parameters

​Products & services

​List products

​Query parameters

​Create a product

​Request body

​Response

​Get a product

​Path parameters

​Update a product

​Path parameters

​Request body

​Invoices

​List invoices

​Query parameters

​Create an invoice

​Request body

​Response

​Get an invoice

​Path parameters

​Update invoice status

​Path parameters

​Request body

Build docs developers (and LLMs) love

Enumerations

Customer status — `CustomerStatus`

Invoice status — `InvoiceStatus`

Dashboard

Get billing dashboard

Response

Customers

List customers

Query parameters

Create a customer

Request body

Response

Get a customer

Path parameters

Update a customer

Path parameters

Request body

Delete a customer

Path parameters

Products & services

List products

Query parameters

Create a product

Request body

Response

Get a product

Path parameters

Update a product

Path parameters

Request body

Invoices

List invoices

Query parameters

Create an invoice

Request body

Response

Get an invoice

Path parameters

Update invoice status

Path parameters

Request body