ControlTiempo: control horario de empleados para FacturaScripts

Plugin de código abierto · Versión 1.0 · Compatible con FacturaScripts 2025+ ControlTiempo es un plugin para FacturaScripts que añade una pieza que el ERP no trae de serie: un sistema completo de fichaje laboral para empleados, accesible desde el móvil, con cronómetro en tiempo real, historial personal y reportes para el administrador. Está pensado para sustituir hojas de Excel, apps externas o cuadernos en empresas pequeñas y medianas que ya usan FacturaScripts para facturación y contabilidad y quieren centralizar también el control de jornada. A diferencia de otros plugins de control horario disponibles en el catálogo oficial, no requiere usuarios adicionales de FacturaScripts (cada empleado tiene credenciales propias e independientes), no envía datos a servidores externos y cabe en menos de 20 KB de código.

Qué problema resuelve La normativa española de registro horario, vigente desde 2019, obliga a las empresas a llevar un control diario de la jornada de cada trabajador. Las opciones habituales son:

Apps especializadas como Anuko, Kimai o Factorial. Funcionan bien pero suponen un coste mensual, una herramienta más que gestionar y datos repartidos entre dos sistemas.
Hojas de cálculo manuales. Baratas pero propensas a errores, sin trazabilidad real y difíciles de auditar.
Otros plugins para FacturaScripts. Existen varios con buenas funciones registro horario con geolocalización, imputación de horas, recursos humanos completos, pero ninguno tan simple.

ControlTiempo cubre el caso de uso central — que cada empleado pueda fichar entrada y salida desde su móvil y que la empresa tenga un registro consultable y exportable — sin coste y sin dependencias externas.

Características principales

Para el empleado

Acceso por URL única desde cualquier navegador móvil, sin necesidad de instalar app.
Login con código de empleado y contraseña propios, independientes de los usuarios del ERP.
Botón único de fichaje que alterna entre ENTRADA (verde) y SALIDA (rojo).
Cronómetro en vivo que cuenta segundo a segundo mientras el fichaje está abierto.
Anclaje al reloj del servidor: aunque el móvil tenga la hora desajustada, el cronómetro es fiable.
Notas opcionales en cada fichaje para describir tarea, proyecto o cliente.
Resumen de horas trabajadas del día, la semana y el mes en curso.
Historial visible de los últimos 30 días con duración detallada de cada jornada.
Sesión persistente durante 30 días: el empleado no tiene que volver a introducir la contraseña cada vez.

Para el administrador

Gestión de empleados (alta, baja, edición, activación/desactivación) desde el menú habitual de FacturaScripts.
Listado consultable y filtrable de todos los fichajes de la empresa.
Filtros por empleado y por periodo (rango de fechas).
Búsqueda libre en notas de fichaje.
Ordenación por fecha, empleado o duración.
Exportación a PDF, Excel (XLSX) o CSV con un clic, usando los botones nativos de FacturaScripts.
Edición manual de fichajes en caso de errores o ausencias justificadas.

Para la empresa

Contraseñas almacenadas con hash bcrypt (PHP password_hash), nunca en claro.
Sesiones firmadas con HMAC + secreto derivado de la contraseña del empleado: al cambiar la contraseña, las sesiones antiguas quedan automáticamente invalidadas.
Registro de la IP de origen de cada fichaje para auditoría.
Sin dependencias externas: todo el código y los datos viven en tu instalación de FacturaScripts.
Sin tracking, sin telemetría, sin llamadas a APIs externas.

Modelo de datos El plugin crea dos tablas en la base de datos de FacturaScripts:

Tabla empleadosct — un registro por empleado dado de alta para fichar.

idempleado serial Clave primaria autoincremental
codigo varchar(20) Identificador único de login (NIF, alias, etc.)
nombre varchar(100) Nombre completo
email varchar(100) Email de contacto (opcional)
password varchar(255) Hash bcrypt de la contraseña
activo boolean Si está activo (puede iniciar sesión)
creado timestamp Fecha y hora de alta

Tabla fichajesct — un registro por cada par entrada-salida del empleado.

idfichaje serial Clave primaria autoincremental
idempleado int Referencia al empleado
inicio timestamp Momento de la entrada
fin timestamp Momento de la salida (NULL si está abierto)
segundos int Duración calculada al cerrar el fichaje
nota varchar(255) Nota o tarea (opcional)
ip varchar(45) IP del cliente que registró el fichaje
FacturaScripts crea automáticamente ambas tablas la primera vez que se activa el plugin, a partir de los archivos XML en la carpeta Table/.

Flujo de autenticación del empleado ControlTiempo implementa su propio sistema de sesiones para los empleados, completamente separado del de FacturaScripts. Esto permite que un empleado fiche sin tener una cuenta de usuario en el ERP. El flujo es:

El empleado abre la URL https://tu-erp.com/EmpleadoFichaje desde el móvil.
Si no tiene sesión activa, ve el formulario de login.
Introduce código y contraseña. El controlador busca al empleado por código, verifica el hash de la contraseña con password_verify y, si coincide, genera un token de sesión.
El token se construye como <id>|<sha256(id + password_hash + DB_NAME)> y se guarda como cookie HTTP-only, SameSite=Lax, con TTL de 30 días.
En cada visita posterior, el controlador lee la cookie, recalcula el hash esperado y lo compara con hash_equals (comparación en tiempo constante para evitar timing attacks). Si coinciden, la sesión es válida.

Como el secreto del token incluye el hash actual de la contraseña, cualquier cambio de contraseña invalida automáticamente todas las sesiones antiguas sin necesidad de tabla de sesiones ni mantenimiento.

Cronómetro en tiempo real El cronómetro de la vista móvil es probablemente la parte más delicada del plugin, porque tiene que ser preciso aunque el reloj del móvil esté desajustado o en una zona horaria distinta a la del servidor. La solución es:

El servidor calcula en PHP el timestamp Unix del momento de inicio del fichaje (fichajeAbiertoUnix) y el timestamp Unix actual del servidor.
Ambos valores se incrustan en el HTML como atributos data-* del contador.
El JavaScript del navegador calcula la diferencia entre su propio reloj y el reloj del servidor en el momento de la carga, y guarda ese offset.
En cada tick (cada segundo), aplica el offset al reloj local antes de calcular la diferencia con el inicio.

El resultado: el cronómetro corre anclado al reloj del servidor, independientemente del estado del móvil.

Instalación

FacturaScripts 2025 o superior (probado en 2026.1).
PHP 8.1+.
Descarga el ZIP del plugin e instala desde el gestor de plugins.
Entra a FacturaScripts como administrador.
Activa el plugin desde Administrador → Plugins. Las dos tablas (empleadosct y fichajesct) se crean automáticamente la primera vez.
Pulsa "Reconstruir" desde la misma pantalla por si la caché tiene datos antiguos.

Si todo ha ido bien, verás una nueva entrada en el menú Admin llamada "Empleados (control tiempo)".

Guía de uso Dar de alta empleados Como administrador:

Ve a Admin → Empleados (control tiempo).
Pulsa el botón Nuevo.
Rellena los campos:

Código: el identificador con el que el empleado iniciará sesión. Puede ser su NIF, un alias o un número interno. Debe ser único.
Nombre: nombre completo (aparecerá en su pantalla de fichaje).
Email: opcional, solo para tener un dato de contacto.
Contraseña: contraseña inicial en texto plano. Se hashea automáticamente al guardar; tras guardar, el campo muestra el hash y no la contraseña original.
Activo: marca esta casilla. Si la desactivas, el empleado no podrá iniciar sesión.

Pulsa Guardar.

Reparte la contraseña inicial al empleado por un canal seguro y pídele que la cambie. (Nota: el plugin actualmente no incluye una opción de "cambiar contraseña" desde la vista del empleado; tendrías que cambiársela tú desde el panel de admin. Está previsto añadirla en futuras versiones.)

Acceso del empleado Cada empleado solo necesita conocer una URL: https://tu-facturascripts.com/EmpleadoFichaje

Sugerencias prácticas:

Recomienda que añadan la URL a la pantalla de inicio de su móvil (en iOS: botón Compartir → "Añadir a pantalla de inicio"; en Android Chrome: menú → "Añadir a pantalla principal"). Funciona como una app nativa.
Si quieres simplificarlo aún más, puedes crear un código QR con esa URL y pegarlo en la entrada o en el office.

Al entrar:

Introduce código y contraseña y pulsa Entrar.
Si está dentro de su jornada laboral, pulsa Fichar ENTRADA. El cronómetro empieza a correr.
Al final de la jornada (o de un periodo de trabajo), opcionalmente escribe una nota describiendo lo trabajado y pulsa Fichar SALIDA. El fichaje queda cerrado y registrado.
Puede consultar los totales del día, la semana y el mes en cualquier momento, así como su historial reciente.

Consultar y exportar fichajes Como administrador, desde Admin → Empleados (control tiempo) → pestaña Fichajes:

Filtra por periodo seleccionando un rango de fechas (hoy, esta semana, este mes, personalizado).
Filtra por empleado seleccionando uno concreto.
Ordena la lista por inicio, empleado o duración.
Busca texto libre en las notas (útil si los empleados etiquetan tareas).
Exporta los resultados con los botones de exportación de FacturaScripts (PDF, XLSX, CSV).

Corregir errores Si un empleado olvida fichar la salida (y por tanto su jornada quedó "abierta"), o si necesitas ajustar manualmente una hora, edita el fichaje directamente:

Desde la pestaña Fichajes, haz clic en el fichaje a editar.
Modifica inicio o fin según necesites.
Al guardar, el campo segundos se recalcula automáticamente.

Anota siempre el motivo del ajuste en el campo nota para que quede trazado.

Seguridad y privacidad ControlTiempo se diseñó pensando en empresas que toman en serio la protección de datos:

Contraseñas: nunca se almacenan en claro. Se hashean con password_hash(PASSWORD_DEFAULT), que usa bcrypt con coste adaptativo. Aunque alguien acceda a la base de datos, no obtendrá las contraseñas originales.
Sesiones: tokens firmados con HMAC-SHA256. No usamos sesiones PHP nativas para los empleados (que serían visibles en /tmp o en Redis y compartibles entre dominios mal configurados).
Cookies: marcadas como HttpOnly (no accesibles desde JavaScript, mitiga XSS), SameSite=Lax (mitiga CSRF) y Secure cuando se accede por HTTPS.
Comparación de tokens: con hash_equals, en tiempo constante, para no filtrar información por canal lateral.
Invalidación al cambiar contraseña: automática, sin necesidad de borrar nada manualmente.
Registro de IP: cada fichaje guarda la IP de origen para auditoría y detección de anomalías.
Cumplimiento RGPD: los datos personales tratados son mínimos (nombre, email opcional, IP). Como responsable del tratamiento debes informar a tus empleados de este registro y de su finalidad, y permitirles el acceso a sus datos (que el propio plugin ya facilita).

Limitaciones conocidas Lo que ControlTiempo no hace, al menos por ahora:

No tiene geolocalización (registro de coordenadas GPS al fichar). Si necesitas comprobar dónde fichó el empleado, hay plugins de pago que lo cubren.
No gestiona vacaciones, días libres ni ausencias justificadas como entidades propias. Solo registra fichajes.
No diferencia entre "horas facturables" y "horas no facturables", ni asocia fichajes a proyectos o clientes (más allá del campo libre de nota). Si necesitas eso, mira el plugin oficial ImputaciónHoras combinado con Proyectos.
No envía notificaciones automáticas (recordatorios para fichar, avisos de jornada cumplida).
No tiene cambio de contraseña por parte del empleado: lo hace el administrador.
No tiene reportes con gráficos: solo listados tabulares exportables.
No tiene API REST para integrarse con apps externas.

Todas estas funciones son técnicamente posibles y se pueden añadir como extensiones del plugin sin tocar el código base.

Resolución de problemas

El empleado ve la página de login de FacturaScripts en lugar de la pantalla de fichaje. La URL correcta es /EmpleadoFichaje (con E mayúscula). Si te lleva al login del ERP, comprueba que el plugin está activado y que has pulsado "Reconstruir".
Mensaje "Credenciales no válidas" aunque el código y la contraseña sean correctos. Verifica que el empleado está marcado como activo. Si lo está, prueba a editarlo y reintroducir la contraseña: a veces, contraseñas guardadas por otros medios no quedan correctamente hasheadas.
El cronómetro marca tiempos absurdos (cientos de miles de horas). Esto era un bug de la versión 0.x ya corregido. Asegúrate de tener la versión 1.0 o superior.
El fichaje no se guarda. Revisa MyFiles/Logs/ o el panel de logs de FacturaScripts. Los errores más habituales son de permisos de escritura en la base de datos o de configuración incorrecta de zona horaria de PHP.
Las exportaciones a PDF/XLSX salen vacías. Comprueba que tienes aplicado algún filtro razonable. Algunos exportadores limitan el número de filas a unas pocas centenas para evitar reventar la memoria.

Roadmap Funciones previstas para versiones futuras (sin compromiso de fecha):

v1.1: cambio de contraseña por parte del empleado y recuperación por email.
v1.2: panel de resumen mensual con gráficos para el administrador.
v1.3: notificaciones por email al cerrar el mes con el resumen de horas.
v1.4: API REST con autenticación por token, pensada para apps móviles propias.
v1.5: extensión opcional con geolocalización (coordenadas + reverse geocoding).
v2.0: integración con el plugin oficial Proyectos para imputar fichajes a proyectos.

Cualquier contribución (issue, pull request, idea) es bienvenida.

Créditos y licencia ControlTiempo es software libre. Puedes usarlo, modificarlo y redistribuirlo sin restricciones. Si te resulta útil y quieres colaborar, lo mejor que puedes hacer es probarlo, reportar bugs y proponer mejoras. Construido sobre FacturaScripts, un ERP open source español hecho con cariño por mucha gente desde 2013.