ControlTiempo: control horario de empleados para FacturaScripts - Versión 1.3

ControlTiempo: control horario de empleados para FacturaScripts

Versión 1.3 · 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, pausas de descanso, horarios con avisos automáticos por email, vacaciones, 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) y no envía datos a servidores externos.

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, registrando el tiempo de trabajo efectivo. 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 fiche entrada, pausas y salida desde su móvil, que se le avise si se olvida, y que la empresa tenga un registro consultable y exportable de tiempo efectivo — sin dependencias externas.

Características principales

Para el empleado

Acceso por URL única desde cualquier navegador móvil, sin necesidad de instalar app. Añadida a la pantalla de inicio funciona como una app nativa, también en iPhone.
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 el tiempo de trabajo efectivo.
Pausas con motivo (descanso, almuerzo, médica, otros): el cronómetro se congela y el tiempo en pausa se descuenta automáticamente de la jornada.
Modo vacaciones: lo activa y desactiva él mismo, deja de recibir avisos mientras dura, y el periodo queda registrado en su ficha.
Cambio de contraseña desde su propia pantalla, y recuperación por email si la olvida (enlace seguro de un solo uso que caduca en 30 minutos).
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 y pausas de cada jornada.
Sesión persistente durante 30 días: 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.
Grupos de empleados con horario común, y horarios individuales para quien lo necesite. Si un empleado tiene horario propio para un día, ese día manda el suyo sobre el del grupo.
Alta rápida "Añadir horario semanal": días de la semana, hora de entrada y salida, segundo bloque opcional para horario partido (ej. L-V de 9:00 a 14:00 y de 16:00 a 19:00) y margen de aviso, todo creado de una vez.
Avisos automáticos por email: al empleado que no ha fichado la entrada pasado el margen configurable (15 minutos por defecto), y al que ha olvidado fichar la salida (su fichaje sigue abierto pasada su hora). Cada aviso se envía una sola vez y queda registrado.
Textos de los avisos editables en Administrador → Email → Notificaciones, con marcadores {nombre}, {fecha} y {hora}, y desactivables por separado.
Listado consultable y filtrable de todos los fichajes, con duración en horas y minutos y columna de pausas.
Pestañas de Grupos, Horarios y Vacaciones con sus filtros; ficha del empleado con sus horarios personales y su histórico de vacaciones.
Filtros por empleado y por periodo, búsqueda libre en notas, y 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 y de sus pausas en caso de errores: los totales se recalculan solos.

Para la empresa

Contraseñas almacenadas con hash bcrypt (PHP password_hash), nunca en claro.
Bloqueo automático de la cuenta tras 5 intentos fallidos (15 minutos) y límite de intentos por IP contra accesos masivos y enumeración de códigos.
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.
Registro de tiempo de trabajo efectivo: las pausas se descuentan y quedan trazadas con inicio, fin y motivo.
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 ocho 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 (necesario para recibir avisos y recuperar contraseña)
password varchar(255) · Hash bcrypt de la contraseña
activo boolean · Si está activo (puede iniciar sesión)
idgrupo int · Grupo al que pertenece (opcional)
intentosfallidos int / bloqueadohasta timestamp · Control del bloqueo por intentos
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 · Tiempo de trabajo EFECTIVO (fin − inicio − pausas), calculado automáticamente
segundos_pausa int · Total de pausas descontadas, mantenido automáticamente
nota varchar(255) · Nota o tarea (opcional)
ip varchar(45) · IP del cliente que registró el fichaje

Tabla pausasct — cada pausa dentro de un fichaje.

idpausa serial · Clave primaria
idfichaje int · Fichaje al que pertenece
inicio / fin timestamp · Fin en NULL = pausa en curso
motivo varchar(30) · descanso, almuerzo, medica u otros

Tabla gruposct — grupos de empleados (idgrupo, nombre único, descripcion).

Tabla horariosct — horas previstas por día de la semana.

idhorario serial · Clave primaria
idgrupo / idempleado int · Destino: un grupo O un empleado (exactamente uno)
dia_semana int · 1 = lunes … 7 = domingo
horaentrada / horasalida varchar(5) · Formato HH:MM; la salida es opcional
minutos_aviso int · Margen antes de avisar (por defecto 15)
activo boolean

Tabla avisosct — registro de cada aviso resuelto (idempleado, idhorario, fecha, tipo entrada/salida, hora_prevista, estado, enviado). Garantiza que ningún aviso se envía dos veces; se purga automáticamente a los 180 días.

Tabla vacacionesct — periodos de vacaciones (idempleado, fechainicio, fechafin — NULL = en curso —, nota, creado).

Tabla intentosloginct — intentos de login por IP para el límite de accesos; se purga automáticamente.

FacturaScripts crea y actualiza automáticamente todas las tablas al activar 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 aplica primero el límite de intentos por IP, después el bloqueo por cuenta (5 fallos = 15 minutos), y verifica el hash con password_verify.
Si coincide, genera un token de sesión firmado (HMAC-SHA256 con secreto derivado del hash de la contraseña) y lo guarda como cookie HTTP-only, SameSite=Lax, con TTL de 30 días.
En cada visita posterior, el controlador valida el token con hash_equals (comparación en tiempo constante). Como el secreto incluye el hash actual de la contraseña, cualquier cambio de contraseña invalida automáticamente todas las sesiones antiguas.

En las "apps" de pantalla de inicio de iPhone, donde WebKit puede perder la cookie al cerrar la app, el plugin rehidrata la sesión automáticamente con el mismo token: el empleado abre y ficha, sin volver a identificarse.

Si el empleado olvida la contraseña, el enlace "¿Has olvidado tu contraseña?" del login le envía por email un enlace de restablecimiento que caduca a los 30 minutos y deja de valer en cuanto la contraseña cambia (un solo uso). Restablecerla desbloquea la cuenta si estaba bloqueada por intentos fallidos. El mensaje en pantalla es siempre el mismo, exista o no el código, para que nadie pueda usar el formulario para adivinar códigos válidos.

Cronómetro en tiempo real El cronómetro de la vista móvil 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:

El servidor incrusta en el HTML el timestamp Unix del inicio del fichaje, el suyo propio actual, el total de pausas ya descontadas y, si hay pausa en curso, su inicio.
El JavaScript calcula el desfase entre el reloj del móvil y el del servidor al cargar, y lo aplica en cada tick.
El tiempo mostrado es el efectivo: descuenta las pausas cerradas y, durante una pausa, queda congelado.

El resultado: el cronómetro corre anclado al reloj del servidor y muestra tiempo de trabajo real, independientemente del estado del móvil.

Horarios y avisos automáticos Para que el plugin avise a quien se olvida de fichar:

(Opcional) Crea grupos en Admin → Empleados (control tiempo) → pestaña Grupos, y asigna cada empleado a su grupo desde su ficha.
Crea los horarios con el botón "Añadir horario semanal" (en la pestaña Horarios o en la ficha del grupo/empleado): marca los días, indica entrada y salida, añade el segundo bloque si el horario es partido, y el margen de aviso. Para casos complejos, crea o edita filas una a una desde la pestaña Horarios.
Asegúrate de tres cosas: que cada empleado tiene email en su ficha, que el email saliente de FacturaScripts está configurado (Administrador → Email) y que el cron de FacturaScripts se ejecuta periódicamente (php index.php -cron). Con un cron cada 5 minutos los avisos son puntuales; con uno horario llegan en la siguiente pasada, y se descartan si han pasado más de 4 horas (para no avisar tardísimo).

Reglas que conviene conocer:

El aviso de entrada llega si, pasada la hora prevista más el margen, no consta fichaje. En horarios partidos, el fichaje de la mañana no silencia el aviso del turno de tarde.
El aviso de salida llega si, pasada la hora de salida más el margen, el fichaje sigue abierto (también si el empleado se quedó "en pausa" y se fue a casa).
No se avisa a empleados inactivos ni de vacaciones. Cada aviso se envía una sola vez por día, horario y tipo, y queda registrado con su estado.
Los textos de los dos avisos (y el de recuperación de contraseña) se editan en Administrador → Email → Notificaciones, y cada uno se puede desactivar por separado.

Instalación

FacturaScripts 2025 o superior. PHP 8.1+.
Descarga el ZIP del plugin e instala desde el gestor de plugins.
Activa el plugin desde Administrador → Plugins. Las ocho tablas se crean automáticamente; al actualizar desde versiones anteriores, las tablas existentes se amplían sin perder datos.
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: necesario si quieres que reciba avisos de fichaje y pueda recuperar su contraseña.
Grupo: opcional, para heredar los horarios del grupo.
Contraseña: contraseña inicial en texto plano. Se hashea automáticamente al guardar.
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: él mismo puede cambiarla después desde su pantalla de fichaje (icono de la llave), y recuperarla por email si la olvida.

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 y la sesión se mantiene.
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.
Al empezar la jornada, pulsa Fichar ENTRADA. El cronómetro empieza a correr.
Para el almuerzo o un descanso, elige el motivo y pulsa Pausa; al volver, Reanudar trabajo. El tiempo en pausa no cuenta.
Al final de la jornada, opcionalmente escribe una nota y pulsa Fichar SALIDA. El fichaje queda cerrado con su tiempo efectivo.
Antes de irse de vacaciones, pulsa el icono de la sombrilla para activar el modo vacaciones (no recibirá avisos); al volver, el mismo icono las finaliza.

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

La duración se muestra en horas y minutos, junto al total de pausas de cada jornada.
Filtra por periodo o por empleado, ordena por inicio, empleado o duración, y busca texto libre en las notas.
Exporta los resultados con los botones de exportación de FacturaScripts (PDF, XLSX, CSV).

Corregir errores Si un empleado olvida fichar la salida, o hay que ajustar una hora:

Desde la pestaña Fichajes, haz clic en el fichaje a editar.
Modifica inicio o fin según necesites; las pausas se corrigen en su propia pestaña dentro de la ficha del fichaje (puedes cerrar una pausa olvidada o ajustar sus horas).
Al guardar, la duración efectiva y el total de pausas se recalculan automáticamente. Por eso el campo de segundos no es editable: corrige las horas, no el total.

Anota siempre el motivo del ajuste en el campo nota para que quede trazado. Las vacaciones también pueden crearse o corregirse desde la ficha del empleado (por ejemplo, cerrar unas que olvidó finalizar).

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 (bcrypt con coste adaptativo).
Fuerza bruta: bloqueo por cuenta (5 intentos, 15 minutos) y límite por IP; el historial de intentos se purga automáticamente.
Sesiones: tokens firmados con HMAC-SHA256, cookies HttpOnly + SameSite=Lax + Secure bajo HTTPS, comparación en tiempo constante con hash_equals, e invalidación automática al cambiar la contraseña.
Recuperación de contraseña: enlaces de un solo uso con caducidad de 30 minutos y mensajes que no permiten enumerar códigos de empleado.
Registro de IP: cada fichaje guarda la IP de origen para auditoría.
Cumplimiento RGPD: los datos personales tratados son mínimos (nombre, email, IP, jornadas, pausas y vacaciones). Como responsable del tratamiento debes informar a tus empleados de este registro y de su finalidad. Ten en cuenta que el motivo de pausa "médica" puede considerarse dato relativo a la salud: su uso es opcional y el empleado siempre puede elegir un motivo genérico.

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

No tiene geolocalización (registro de coordenadas GPS al fichar).
No diferencia entre "horas facturables" y "no facturables", ni asocia fichajes a proyectos o clientes más allá del campo libre de nota.
No tiene reportes con gráficos: solo listados tabulares exportables (previsto para la 1.4).
No tiene API REST para integrarse con apps externas.
Los avisos no soportan turnos que crucen la medianoche (la salida debe ser posterior a la entrada del mismo día).
Los avisos requieren tener configurado el email saliente de FacturaScripts y el cron en ejecución periódica.

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, y que la cuenta no está bloqueada por intentos fallidos (espera 15 minutos, restablece la contraseña por email, o edítala desde el panel).
No llegan los avisos de fichaje. Comprueba, por este orden: que el empleado tiene email en su ficha, que el email saliente de FacturaScripts funciona (Administrador → Email, botón de prueba), que el cron se está ejecutando, que el horario está activo y asignado al grupo o empleado correcto, y que la notificación no está desactivada en Administrador → Email → Notificaciones. Cada aviso resuelto queda registrado con su estado, lo que ayuda a diagnosticar.
El enlace de recuperación de contraseña "no es válido o ha caducado". Los enlaces caducan a los 30 minutos y dejan de valer en cuanto la contraseña cambia. Solicita uno nuevo desde el login.
La duración de un fichaje no coincide con fin menos inicio. Es lo esperado si hubo pausas: la duración es tiempo de trabajo efectivo. Revisa la pestaña Pausas de la ficha del fichaje.
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.

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

v1.4: panel de resumen con gráficos para el administrador.
Futuras: API REST con autenticación por token, extensión opcional con geolocalización, integración con el plugin oficial Proyectos para imputar fichajes.

Cualquier sugerencia o aviso de error es bienvenido a través del botón de contacto de la ficha del plugin.

Licencia ControlTiempo se distribuye a través de la ficha oficial del plugin en facturascripts.com, con licencia de uso por instalación y 12 meses de actualizaciones incluidas (ver condiciones en la propia ficha). Construido sobre FacturaScripts, un ERP open source español hecho con cariño por mucha gente desde 2013.