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.
Every employment relationship in La Oficina Nítida is backed by a Contrato record that captures the agreement type, dates, salary, and job title at the moment of signing. Contracts are isolated per tenant, linked to a specific employee, and serve as the anchor for document generation, expediente population, and automated expiration alerts. An employee may accumulate multiple contracts over time — renewals, role changes, and new engagements each produce a new record while the full history is preserved.
Contract Types
La Oficina Nítida supports the five contract modalities recognized by the Colombian labor code:
| Value | Contract type | Key characteristic |
|---|
TERMINO_FIJO | Fixed-term | Has a defined fechaFin; eligible for alert tracking |
TERMINO_INDEFINIDO | Indefinite term | No end date (fechaFin is null) |
OBRA_LABOR | Work-for-hire | Tied to completion of a specific project or task |
APRENDIZAJE | Apprenticeship | Training contract under SENA regulations |
PRESTACION_SERVICIOS | Services contract | Independent-contractor engagement (not an employment relationship under the labor code) |
Contract States and Lifecycle
Every contract starts in VIGENTE (active) and transitions through the following states:
| Transition | Trigger |
|---|
VIGENTE → VENCIDO | The contract’s fechaFin has passed without a renewal |
VIGENTE → TERMINADO | The contract was explicitly terminated before its end date |
VIGENTE → RENOVADO | The contract was renewed and a successor contract was created |
VENCIDO → RENOVADO | A lapsed contract is retroactively marked as renewed |
PATCH /contracts/:id/status (requires ADMIN role). The API enforces the allowed transitions listed above; any other state change returns 400 Bad Request.
RENOVADO is currently a terminal state. Automatic creation of a successor
contract upon renewal is planned for a future phase. For now, create the new
contract manually and then update the original to RENOVADO.
Creating a Contract
POST /contracts
Content-Type: application/json
{
"employeeId": "e1f2a3b4-...",
"tipo": "TERMINO_FIJO",
"fechaInicio": "2024-02-01",
"fechaFin": "2025-01-31",
"cargo": "Docente de Secundaria",
"salario": 2100000,
"sedeId": "a1b2c3d4-..."
}
ADMIN or OPERADOR role.
CreateContractDto fields
| Field | Type | Required | Description |
|---|
employeeId | UUID | ✅ | The employee this contract belongs to |
tipo | ContratoTipo | ✅ | One of the five contract types above |
fechaInicio | ISO date string | ✅ | Contract start date |
fechaFin | ISO date string | — | Contract end date. Omit for TERMINO_INDEFINIDO |
cargo | string | ✅ | Job title — stored as a snapshot |
salario | number | ✅ | Monthly salary in COP (minimum 0) |
sedeId | UUID | — | Branch this contract is associated with |
Historical snapshots
cargo and salario are stored directly on the Contrato record rather than being derived from the employee at query time. This design guarantees that a contract printed or audited months later reflects the terms agreed at signing — even if the employee was later promoted, transferred, or had their salary adjusted. The same immutability principle applies to the variablesSnapshot JSON field, which captures every template variable used during document generation.
Querying Contracts
List all contracts
GET /contracts?estado=VIGENTE&employeeId=e1f2a3b4-...&page=1&limit=20
ContractQueryDto filter parameters:
| Parameter | Type | Description |
|---|
estado | VIGENTE | VENCIDO | TERMINADO | RENOVADO | Filter by contract status |
employeeId | string | Return contracts for a specific employee |
search | string | Free-text search (matches employee name or document number) |
page | number | Page number (default 1) |
limit | number | Page size (default 10, max 100) |
data and meta (total, page, limit, totalPages).
Contracts for a specific employee
GET /contracts/employees/:id/contracts
Get a single contract
Returns the full contract record. Returns 404 if the contract does not exist within the authenticated tenant.
Updating Contract Status
PATCH /contracts/:id/status
Content-Type: application/json
{
"estado": "TERMINADO"
}
ADMIN role. The service validates the transition against the allowed state machine before persisting the change.
Contract Document Generation
Once a contract record exists, you can generate a PDF contract document using a linked document template:
POST /contracts/:id/generate-document
Content-Type: application/json
{
"templateId": "t9u8v7w6-..."
}
ADMIN or OPERADOR role.
The endpoint:
- Loads the contract and its associated employee record.
- Resolves all template variables (name fields, document number, cargo, salario, dates, sede, etc.) from the contract’s snapshot data.
- Renders the DOCX template with the resolved variables.
- Converts the result to PDF via the Gotenberg/LibreOffice service.
- Stores the PDF and creates a
GeneratedDocument record.
- Automatically adds an
ExpedienteDoc entry under the CONTRATO category in the employee’s digital file.
The response includes the generated document’s id and the URL to the resulting PDF.
Set up contract expiration alerts to stay ahead of upcoming renewals. Use
POST /alerts/generate-contract-alerts to scan all active contracts with
fechaFin within the next 30 days and create alerts at the 30-day, 15-day,
and 7-day thresholds. Schedule this endpoint to run daily via a cron job so
your team never misses a renewal window. See the Alerts
module for details.