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 Contracts API manages the full lifecycle of employment agreements within a tenant. A contract record stores a snapshot of the employee’s cargo and salario at the moment of creation so that later edits to the employee profile do not alter historical contract data. Contracts move through four states — VIGENTE, VENCIDO, TERMINADO, and RENOVADO — and state transitions are restricted to the ADMIN role. Document generation from a contract produces a GeneratedDocument that is automatically linked to the employee’s expediente. All endpoints require a valid JWT. 
Authorization: Bearer {accessToken}

​
List contracts

GET /contracts
Roles: ADMIN, OPERADOR, VIEWER
​
page
number
Page number, minimum 1. Defaults to 1.
​
limit
number
Records per page, minimum 1, maximum 100. Defaults to 10.
​
search
string
Free-text search across contract cargo, employee first name, first family name, and document number (cédula).
​
employeeId
string (UUID)
Restrict results to contracts belonging to a specific employee.
​
estado
string
Filter by contract state. One of VIGENTE, VENCIDO, TERMINADO, RENOVADO.
​
data
Contrato[]
Page of contract objects matching the query.
​
meta.total
number
Total matching contracts across all pages.
​
meta.page
number
Current page.
​
meta.limit
number
Page size.
​
meta.totalPages
number
Total number of pages.

​
Create contract

POST /contracts
Roles: ADMIN, OPERADOR
​
employeeId
string (UUID)
required
UUID of the employee for whom this contract is being created.
​
cargo
string
required
Job title as it should appear on the contract. Stored as an immutable snapshot.
​
salario
number
required
Monthly salary as it should appear on the contract (≥ 0). Stored as an immutable snapshot.
​
tipo
string
required
Contract type. One of TERMINO_FIJO, TERMINO_INDEFINIDO, OBRA_LABOR, APRENDIZAJE, PRESTACION_SERVICIOS.
​
fechaInicio
string (ISO 8601)
required
Contract start date (e.g. "2024-04-01").
​
fechaFin
string (ISO 8601)
Contract end date. Required for TERMINO_FIJO and OBRA_LABOR contracts. Omit for indefinite agreements.
​
sedeId
string (UUID)
Branch office associated with this contract.
​
id
string (UUID)
Newly created contract identifier.
​
estado
string
Initial state; always VIGENTE.
​
createdAt
string (ISO 8601)
Timestamp of record creation.
cargo and salario are snapshot fields captured at contract creation time. If the employee’s profile is later updated, already-created contracts retain the original values.
curl -X POST https://api.oficinaclear.com/contracts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "a1b2c3d4-0000-0000-0000-000000000001",
    "cargo": "Desarrolladora Backend",
    "salario": 5800000,
    "tipo": "TERMINO_INDEFINIDO",
    "fechaInicio": "2024-04-01"
  }'

​
Get contract

GET /contracts/:id
Roles: ADMIN, OPERADOR, VIEWER
​
id
string (UUID)
required
Contract identifier.
​
id
string (UUID)
Contract identifier.
​
empleadoId
string (UUID)
Associated employee identifier.
​
tipo
string
Contract type enum value.
​
estado
string
Current lifecycle state.
​
cargo
string
Snapshot job title.
​
salario
number
Snapshot monthly salary.
​
fechaInicio
string (ISO 8601)
Contract start date.
​
fechaFin
string (ISO 8601) | null
Contract end date, or null for indefinite contracts.
​
pdfKey
string | null
R2 storage key for the generated PDF, if available.
​
docxKey
string | null
R2 storage key for the generated DOCX, if available.
​
variablesSnapshot
object
JSON object with the template variable values used at document generation time.

​
Update contract status

PATCH /contracts/:id/status
Roles: ADMIN
Transitions a contract to a new lifecycle state. Only valid transitions are accepted; invalid transitions return 400 Bad Request.
​
id
string (UUID)
required
Contract identifier.
​
estado
string
required
Target state. One of VIGENTE, VENCIDO, TERMINADO, RENOVADO.
​
id
string (UUID)
Contract identifier.
​
estado
string
Updated lifecycle state.
​
updatedAt
string (ISO 8601)
Timestamp of the transition.

​
State transition table

Current stateAllowed target states
VIGENTEVENCIDO, TERMINADO, RENOVADO
VENCIDORENOVADO
TERMINADO(no further transitions)
RENOVADO(no further transitions)
curl -X PATCH https://api.oficinaclear.com/contracts/c9d8e7f6-0000-0000-0000-000000000002/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estado": "TERMINADO"}'

​
Generate contract document

POST /contracts/:id/generate-document
Roles: ADMIN, OPERADOR
Renders a GeneratedDocument from a DocumentTemplate using the contract’s snapshot data as replacement context. If templateId is omitted, the service selects the tenant’s default CONTRACT-type template.
​
id
string (UUID)
required
Contract identifier.
​
templateId
string (UUID)
UUID of the DocumentTemplate to use. When omitted, the platform resolves the default active CONTRACT template for the tenant.
​
id
string (UUID)
Identifier of the created GeneratedDocument record.
​
nombre
string
Name assigned to the generated document.
​
tipo
string
Template type used (CONTRACT, CERTIFICATION, LETTER, or MEMO).
​
contenidoFinal
string
Immutable HTML snapshot with all {{VARIABLE}} placeholders replaced.
​
pdfUrl
string | null
URL of the rendered PDF after calling POST /generated-documents/:id/generate-pdf. null until PDF rendering is triggered.
curl -X POST https://api.oficinaclear.com/contracts/c9d8e7f6-0000-0000-0000-000000000002/generate-document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "t1e2m3p-0000-0000-0000-000000000003"}'

​
List contracts for an employee

GET /contracts/employees/:id/contracts
Roles: ADMIN, OPERADOR, VIEWER
Returns the complete contract history for a specific employee in reverse chronological order, with no pagination.
​
id
string (UUID)
required
Employee identifier.
​
[*]
Contrato[]
Flat array of all contract records for the employee, ordered by createdAt descending.
curl https://api.oficinaclear.com/contracts/employees/a1b2c3d4-0000-0000-0000-000000000001/contracts \
  -H "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us