Horaris de treball
Defineix patrons setmanals de treball, el seu mode de compliment i les assignacions efectiu-datades a empleats sobre l'API v1.
Un horari de treball modela les hores que una empresa espera d'un empleat:
quantes hores al dia i a quina hora comença la jornada. Alimenta dos càlculs aigües
avall — les hores esperades que usen els saldos, i l'hora planificada
d'entrada que usa la presència per marcar arribades tard.
Els horaris estan acotats per work_schedules:read / work_schedules:write sota
https://api.factuarea.com/v1.
L'horari setmanal
Un horari setmanal porta un nom, un patró setmanal de set dies —cada dia
una llista de franges HH:MM–HH:MM no solapades—, un mode i un estat
(active / archived). Les hores setmanals esperades i l'hora planificada es
deriven del patró.
El mode fixa com es mesura el compliment:
| Mode | Significat |
|---|---|
validated | Les hores esperades es prenen com a treballades un cop validades — l'horari és la font de veritat. |
real_clocking | El compliment es mesura contra els fitxatges reals del ledger. |
El mode per defecte és validated.
| Operació | Endpoint |
|---|---|
| Llistar / detall | GET /v1/work-schedules, GET /v1/work-schedules/{schedule} |
| Crear / actualitzar | POST /v1/work-schedules, PATCH /v1/work-schedules/{schedule} |
| Arxivar / desarxivar | POST /v1/work-schedules/{schedule}/archive, .../unarchive |
| Estadístiques | 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 dia amb llista buida és un dia de descans. Consulta els esquemes a la Referència d'API.
Assignacions
Un horari s'aplica a un empleat mitjançant una assignació efectiu-datada: un
effective_from (inclusiu) i un effective_to (exclusiu) opcional. Assignar un
horari nou a un empleat tanca l'assignació oberta anterior, així que un empleat
té un horari efectiu en qualsevol data sense buits ni solapaments.
| Operació | Endpoint | Efecte |
|---|---|---|
| Assignar | POST /v1/work-schedules/{schedule}/assign | Obre una assignació des d'effective_from, tancant l'anterior. |
| Desassignar | POST /v1/work-schedules/{schedule}/unassign | Tanca l'assignació oberta de l'empleat a aquest horari. |
| Llistar assignacions | GET /v1/work-schedules/{schedule}/assignments | Els empleats assignats actualment. |
| Resoldre l'horari de l'empleat | GET /v1/work-schedules/employee/{employee} | L'horari efectiu d'un empleat en una data donada. |
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} és el contracte que consumeixen els
saldos i la presència: retorna l'horari vigent de l'empleat a la data demanada,
del qual es llegeixen les hores esperades i l'hora planificada.
Les assignacions són datades per rang, no un camp solt a l'empleat. Reassignar
un horari mai reescriu l'historial — l'assignació anterior es tanca amb un
effective_to, i la nova s'obre des del seu effective_from.
Flux típic
- Crea un horari setmanal amb el seu patró setmanal i el seu mode.
- Assigna'l als empleats des d'una data
effective_from. - Aigües avall, l'horari alimenta les hores esperades dels saldos i l'hora planificada que usa la presència per marcar arribades tard.
- Desassigna o reassigna a mesura que canvien els contractes; arxiva els horaris que ja no facis servir.
Pròxims passos
- Presència — com l'hora planificada activa la detecció d'arribades tard.
- Tancament mensual — on s'informen les hores esperades enfront de les treballades.