Visió general del control horari

El sistema de control horari sobre l'API v1 — el registre de jornada inalterable (RD-llei 8/2019), el rol d'empleat només-portal, l'add-on per plaça i els vuit dominis que el componen.

El control horari de Factuarea cobreix l'obligació legal de les empreses espanyoles segons el RD-llei 8/2019 (art. 34.9 de l'Estatut dels Treballadors): portar un registre objectiu, fiable i inalterable de la jornada diària de cada empleat, conservar-lo quatre anys i posar-lo a disposició de la Inspecció de Treball (ITSS). El registre es recolza en un ledger de només apèndix segellat per una cadena d'empremtes SHA-256 per empresa — el mateix patró antimanipulació que Factuarea aplica a la facturació VeriFactu. És, en resum, el VeriFactu del fitxatge: res no s'edita ni s'esborra mai, i qualsevol manipulació trenca la cadena.

Cada operació viu sota https://api.factuarea.com/v1 i comparteix el mateix embolcall d'error, paginació per cursor i scopes que la resta de l'API. Tota la superfície està gatejada pel mòdul control_horario; una empresa que no el tingui rep un 403 en aquestes rutes.

L'empleat, un rol només-portal

Un empleat és la persona treballadora que fitxa, té horari, sol·licita absències i merita saldos de jornada. És un rol només-portal: els empleats gestionen les seves pròpies dades des del portal i mai computen contra el límit de places users del pla. Donar d'alta empleats es factura en canvi mitjançant un add-on per plaça dedicat — consulta Facturació de places d'empleat.

Els vuit dominis

El sistema es reparteix en vuit dominis d'API. Comença per la guia de la tasca que tinguis entre mans; cadascuna enllaça als seus endpoints a la Referència d'API.

Domini	Què fa	Guia	Scope
Empleats	La plantilla: crear, editar, donar de baixa, reactivar.	—	`employees:read` / `employees:write`
Horaris	Hores setmanals esperades i assignacions efectiu-datades.	Horaris	`work_schedules:read` / `work_schedules:write`
Fitxatges	Entrada/sortida, pauses, fitxatges retroactius, correccions.	Fitxatges	`time_entries:read` / `time_entries:write`
Tancaments mensuals	Congelar, segellar, informar i exportar el registre.	Tancament mensual	`time_entries:read` / `time_entries:write`
Exportacions per a nòmines	Fitxer d'incidències per a A3, Sage o NominaSOL.	Tancament mensual	`payroll_exports:read`
Absències	Tipus, polítiques, sol·licituds, saldos i calendari.	Absències	`absences:read` / `absences:write`
Presència	Qui treballa ara, a l'oficina o en remot.	Presència	`presence:read`
Festius	Calendari nacional, autonòmic i local per comunitat.	—	`holidays:read`

Dos dominis són de només lectura a l'API: presència i festius exposen únicament lectures (presence:read, holidays:read). Declarar la presencialitat oficina/remot i crear festius locals propis són tasques només-portal — no existeix l'scope presence:write ni holidays:write.

Els empleats i la plantilla

L'empleat és l'entitat àncora de la qual depèn la resta del sistema. Cada empleat porta un nom, un email únic per empresa, un tax_id i un job_title opcionals, les hores setmanals contractades, una data d'alta i la comunitat autònoma (ccaa) que determina quins festius apliquen. La baixa és una baixa soft: l'empleat conserva el seu historial al ledger (la retenció de quatre anys prohibeix destruir-lo) i pot reactivar-se després.

curl -X POST https://api.factuarea.com/v1/employees \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Ruiz",
    "email": "ana.ruiz@acme.example",
    "employment_type": "full_time",
    "contract_hours": 40,
    "hire_date": "2026-01-07",
    "ccaa": "ES-MD"
  }'

Consulta els esquemes complets de l'empleat a la Referència d'API.

Scopes i MCP

Cada domini mapeja a un scope fi del catàleg tancat (employees:*, time_entries:*, work_schedules:*, absences:*, presence:read, holidays:read, payroll_exports:read), tots gatejats rere el mòdul control_horario. Revisa la llista completa a la pàgina de scopes i al catàleg de scopes MCP. Cada ruta v1 té la seva tool MCP mirall, així que un agent pot executar les mateixes operacions.

El ledger de jornada són dades de compliment, aïllades per disseny: mai referencia clients, factures ni projectes. Respon a una sola pregunta — quantes hores va treballar cada empleat — i manté aquesta evidència intacta.

Per on seguir

Fitxatges — entrada/sortida, pauses i el flux de correccions.
Tancament mensual — congelar, segellar i exportar el registre.
Absències — tipus, polítiques, sol·licituds, saldos i arrossegament.
Horaris — patrons setmanals i assignacions.
Presència — el panell d'equip en viu i la vista diària oficina/remot.
Facturació de places d'empleat — l'add-on per plaça i el seu cicle.