Ausencias
Configura tipos y políticas de ausencia, gestiona las solicitudes y lee los saldos y el calendario de equipo sobre la API v1.
El dominio de ausencias tiene dos capas: una capa de configuración (qué se
puede solicitar y cuánto) y una capa de flujo (solicitudes, saldos y
calendario). Todo está acotado por absences:read / absences:write y gateado
por el módulo control_horario, bajo https://api.factuarea.com/v1.
Tipos de ausencia
Un tipo de ausencia es lo que un empleado puede solicitar — vacaciones, baja
por enfermedad, un día de asuntos propios. Cada tipo lleva: si es retribuido
(is_paid), si requiere aprobación (requires_approval), una unidad de
medida (days u hours), un color hex, una visibilidad (everyone o
managers_only) y un estado (active / archived). El nombre es único por
empresa. En cada empresa nueva se siembra un set de tipos españoles por
defecto, así que sueles arrancar con un catálogo funcional.
| Operación | Endpoint |
|---|---|
| Listar / detalle | GET /v1/absence-types, GET /v1/absence-types/{type} |
| Crear / actualizar | POST /v1/absence-types, PATCH /v1/absence-types/{type} |
| Archivar / desarchivar | POST /v1/absence-types/{type}/archive, .../unarchive |
curl -X POST https://api.factuarea.com/v1/absence-types \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Asuntos propios",
"is_paid": true,
"requires_approval": true,
"measurement_unit": "days",
"color": "#4F46E5",
"visibility": "everyone"
}'Políticas de ausencia
Una política de ausencia decide cuánto y para quién. Fija una
asignación de días — limited (un número positivo de días) o unlimited —,
un método de devengo (annual o monthly), el conjunto de tipos que
cubre y los empleados a los que se asigna. Asociar tipos es un reemplazo
total; una política se asigna y desasigna de empleados en lote.
| Operación | Endpoint |
|---|---|
| Listar / detalle | GET /v1/absence-policies, GET /v1/absence-policies/{policy} |
| Crear / actualizar | POST /v1/absence-policies, PATCH /v1/absence-policies/{policy} |
| Asignar / desasignar empleados | POST /v1/absence-policies/{policy}/assign, .../unassign |
| Listar asignaciones | GET /v1/absence-policies/{policy}/assignments |
| Arrastre | GET /v1/absence-policies/{policy}/carryover |
| Archivar / desarchivar | POST /v1/absence-policies/{policy}/archive, .../unarchive |
El arrastre expone cuánta asignación no consumida pasa al siguiente periodo de devengo por empleado. La asignación siempre resuelve al empleado dentro de la empresa autenticada, así que una política de la empresa A jamás se asigna a un empleado de la empresa B.
curl -X POST https://api.factuarea.com/v1/absence-policies \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Estándar 22 días",
"allowance": { "type": "limited", "days": 22 },
"accrual_method": "annual",
"absence_type_ids": ["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]
}'Solicitudes, saldos y calendario
Cuando existen tipos y políticas, los empleados solicitan ausencias y los managers las resuelven.
| Operación | Endpoint | Scope |
|---|---|---|
| Crear una solicitud | POST /v1/absence-requests | absences:write |
| Aprobar / rechazar | POST /v1/absence-requests/{request}/approve, .../reject | absences:write |
| Cancelar | POST /v1/absence-requests/{request}/cancel | absences:write |
| Listar / detalle | GET /v1/absence-requests, GET /v1/absence-requests/{request} | absences:read |
| Saldos | GET /v1/absence-balances, GET /v1/absence-balances/{employee} | absences:read |
| Calendario de equipo | GET /v1/absence-calendar | absences:read |
Un saldo es la asignación restante por empleado y tipo, derivada del devengo de la política menos las solicitudes aprobadas. El calendario devuelve las ausencias del equipo en un rango de fechas — la vista del manager de quién está fuera y cuándo.
curl -X POST https://api.factuarea.com/v1/absence-requests \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b",
"absence_type_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
"start_date": "2026-08-01",
"end_date": "2026-08-15"
}'Un tipo con requires_approval: false se concede al solicitarlo; uno con
requires_approval: true espera a que un manager lo apruebe o lo rechace antes
de descontar del saldo.
Flujo típico
- Revisa los tipos sembrados, o crea los tuyos.
- Crea políticas con una asignación de días y un devengo, y cubre los tipos pertinentes.
- Asigna cada política a sus empleados.
- Los empleados solicitan; los managers aprueban o rechazan.
- Lee saldos y el calendario, y consulta el arrastre al cierre del año.
Los festivos que afectan a las ausencias viven en su propio dominio de solo lectura — consulta la visión general y la referencia de festivos.
Próximos pasos
- Cierre mensual — las ausencias aprobadas alimentan el informe mensual.
- Navega la referencia de tipos, políticas y solicitudes.