Horarios de trabajo
Define patrones semanales de trabajo, su modo de cumplimiento y las asignaciones efectivo-datadas a empleados sobre la API v1.
Un horario de trabajo modela las horas que una empresa espera de un
empleado: cuántas horas al día y a qué hora empieza la jornada. Alimenta dos
cálculos aguas abajo — las horas esperadas que usan los saldos, y la hora
planificada de entrada que usa la presencia para marcar
llegadas tarde. Los horarios están acotados por work_schedules:read /
work_schedules:write bajo https://api.factuarea.com/v1.
El horario semanal
Un horario semanal lleva un nombre, un patrón semanal de siete días —cada
día una lista de franjas HH:MM–HH:MM no solapadas—, un modo y un estado
(active / archived). Las horas semanales esperadas y la hora planificada se
derivan del patrón.
El modo fija cómo se mide el cumplimiento:
| Modo | Significado |
|---|---|
validated | Las horas esperadas se toman como trabajadas una vez validadas — el horario es la fuente de verdad. |
real_clocking | El cumplimiento se mide contra los fichajes reales del ledger. |
El modo por defecto es validated.
| Operación | Endpoint |
|---|---|
| Listar / detalle | GET /v1/work-schedules, GET /v1/work-schedules/{schedule} |
| Crear / actualizar | POST /v1/work-schedules, PATCH /v1/work-schedules/{schedule} |
| Archivar / desarchivar | POST /v1/work-schedules/{schedule}/archive, .../unarchive |
| Estadísticas | GET /v1/work-schedules/stats |
curl -X POST https://api.factuarea.com/v1/work-schedules \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Jornada completa 9 a 17",
"mode": "validated",
"week_pattern": {
"monday": [{ "start": "09:00", "end": "17:00" }],
"tuesday": [{ "start": "09:00", "end": "17:00" }],
"wednesday": [{ "start": "09:00", "end": "17:00" }],
"thursday": [{ "start": "09:00", "end": "17:00" }],
"friday": [{ "start": "09:00", "end": "17:00" }],
"saturday": [],
"sunday": []
}
}'Un día con lista vacía es un día de descanso. Consulta los esquemas en la Referencia de API.
Asignaciones
Un horario se aplica a un empleado mediante una asignación efectivo-datada: un
effective_from (inclusivo) y un effective_to (exclusivo) opcional. Asignar un
horario nuevo a un empleado cierra la asignación abierta anterior, así que un
empleado tiene un horario efectivo en cualquier fecha sin huecos ni solapamientos.
| Operación | Endpoint | Efecto |
|---|---|---|
| Asignar | POST /v1/work-schedules/{schedule}/assign | Abre una asignación desde effective_from, cerrando la anterior. |
| Desasignar | POST /v1/work-schedules/{schedule}/unassign | Cierra la asignación abierta del empleado a este horario. |
| Listar asignaciones | GET /v1/work-schedules/{schedule}/assignments | Los empleados asignados actualmente. |
| Resolver el horario del empleado | GET /v1/work-schedules/employee/{employee} | El horario efectivo de un empleado en una fecha dada. |
curl -X POST https://api.factuarea.com/v1/work-schedules/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/assign \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
"effective_from": "2026-01-07"
}'GET /v1/work-schedules/employee/{employee} es el contrato que consumen los
saldos y la presencia: devuelve el horario vigente del empleado en la fecha
pedida, del que se leen las horas esperadas y la hora planificada.
Las asignaciones son datadas por rango, no un campo suelto en el empleado.
Reasignar un horario nunca reescribe el historial — la asignación anterior se
cierra con un effective_to, y la nueva se abre desde su effective_from.
Flujo típico
- Crea un horario semanal con su patrón semanal y su modo.
- Asígnalo a los empleados desde una fecha
effective_from. - Aguas abajo, el horario alimenta las horas esperadas de los saldos y la hora planificada que usa la presencia para marcar llegadas tarde.
- Desasigna o reasigna a medida que cambian los contratos; archiva los horarios que ya no uses.
Próximos pasos
- Presencia — cómo la hora planificada activa la detección de llegadas tarde.
- Cierre mensual — dónde se informan las horas esperadas frente a las trabajadas.