Visión general del control horario
El sistema de control horario sobre la API v1 — el registro de jornada inalterable (RD-ley 8/2019), el rol de empleado solo-portal, el add-on por asiento y los ocho dominios que lo componen.
El control horario de Factuarea cubre la obligación legal de las empresas españolas según el RD-ley 8/2019 (art. 34.9 del Estatuto de los Trabajadores): llevar un registro objetivo, fiable e inalterable de la jornada diaria de cada empleado, conservarlo cuatro años y ponerlo a disposición de la Inspección de Trabajo (ITSS). El registro se apoya en un ledger de solo apéndice sellado por una cadena de huellas SHA-256 por empresa — el mismo patrón antimanipulación que Factuarea aplica a la facturación VeriFactu. Es, en resumen, el VeriFactu del fichaje: nada se edita ni se borra nunca, y cualquier manipulación rompe la cadena.
Cada operación vive bajo https://api.factuarea.com/v1 y comparte el mismo
envoltorio de error, paginación por cursor
y scopes que el resto de la API. Toda la
superficie está gateada por el módulo control_horario; una empresa que no lo
tenga recibe un 403 en estas rutas.
El empleado, un rol solo-portal
Un empleado es la persona trabajadora que ficha, tiene horario, solicita
ausencias y devenga saldos de jornada. Es un rol solo-portal: los empleados
gestionan sus propios datos desde el portal y nunca computan contra el límite
de asientos users del plan. Dar de alta empleados se factura en cambio mediante
un add-on por asiento dedicado — consulta
Facturación de asientos de empleado.
Los ocho dominios
El sistema se reparte en ocho dominios de API. Empieza por la guía de la tarea que tengas entre manos; cada una enlaza a sus endpoints en la Referencia de API.
| Dominio | Qué hace | Guía | Scope |
|---|---|---|---|
| Empleados | La plantilla: crear, editar, dar de baja, reactivar. | — | employees:read / employees:write |
| Horarios | Horas semanales esperadas y asignaciones efectivo-datadas. | Horarios | work_schedules:read / work_schedules:write |
| Fichajes | Entrada/salida, pausas, fichajes retroactivos, correcciones. | Fichajes | time_entries:read / time_entries:write |
| Cierres mensuales | Congelar, sellar, informar y exportar el registro. | Cierre mensual | time_entries:read / time_entries:write |
| Exportaciones para nóminas | Fichero de incidencias para A3, Sage o NominaSOL. | Cierre mensual | payroll_exports:read |
| Ausencias | Tipos, políticas, solicitudes, saldos y calendario. | Ausencias | absences:read / absences:write |
| Presencia | Quién trabaja ahora, en oficina o en remoto. | Presencia | presence:read |
| Festivos | Calendario nacional, autonómico y local por comunidad. | — | holidays:read |
Dos dominios son de solo lectura en la API: presencia y festivos
exponen únicamente lecturas (presence:read, holidays:read). Declarar la
presencialidad oficina/remoto y crear festivos locales propios son tareas
solo-portal — no existe el scope presence:write ni holidays:write.
Los empleados y la plantilla
El empleado es la entidad ancla de la que depende el resto del sistema. Cada
empleado lleva un nombre, un email único por empresa, un tax_id y un job_title
opcionales, las horas semanales contratadas, una fecha de alta y la comunidad
autónoma (ccaa) que determina qué festivos aplican. La baja es una baja
soft: el empleado conserva su historial en el ledger (la retención de cuatro
años prohíbe destruirlo) y puede reactivarse luego.
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 los esquemas completos del empleado en la Referencia de API.
Scopes y MCP
Cada dominio mapea a un scope fino del catálogo cerrado (employees:*,
time_entries:*, work_schedules:*, absences:*, presence:read,
holidays:read, payroll_exports:read), todos gateados tras el módulo
control_horario. Revisa la lista completa en la
página de scopes y en el
catálogo de scopes MCP. Cada ruta v1 tiene su
tool MCP espejo, así que un agente puede ejecutar las mismas
operaciones.
El ledger de jornada son datos de cumplimiento, aislados por diseño: nunca referencia clientes, facturas ni proyectos. Responde a una sola pregunta — cuántas horas trabajó cada empleado — y mantiene esa evidencia intacta.
Por dónde seguir
- Fichajes — entrada/salida, pausas y el flujo de correcciones.
- Cierre mensual — congelar, sellar y exportar el registro.
- Ausencias — tipos, políticas, solicitudes, saldos y arrastre.
- Horarios — patrones semanales y asignaciones.
- Presencia — el panel de equipo en vivo y la vista diaria oficina/remoto.
- Facturación de asientos de empleado — el add-on por asiento y su ciclo.