Documentación: Nodo Obtener Horas Trabajadas (Get Worked Hours)¶

Descripción General¶

El Nodo Obtener Horas Trabajadas (Get Worked Hours) es un nodo de acción de consulta que calcula las horas trabajadas por el personal a partir de los eventos de entrada y salida registrados en puntos de control de acceso (lectores, torniquetes, puertas), dentro de un rango de fechas determinado.

Combina el control de acceso con la gestión de personal: cruzando los registros de acceso de los objetos de entrada y de salida, el nodo determina cuánto tiempo permaneció cada empleado en las instalaciones y lo compara con la jornada esperada, generando un reporte de horas trabajadas, útil para nómina, asistencia o auditoría.

¿Cuándo usar este nodo?¶

Utiliza este nodo cuando necesites:

Calcular las horas trabajadas de empleados a partir de sus accesos (entrada/salida) en torniquetes o lectores.
Generar reportes de asistencia automáticos para un periodo (turno, día, semana).
Detectar diferencias entre las horas esperadas y las efectivamente trabajadas.
Alimentar procesos posteriores (nómina, notificaciones de ausentismo, dashboards de RR.HH.).

Configuración del Nodo¶

El nodo cuenta con dos pestañas de configuración en la parte superior: Formulario (Form) y Editor de JSON (JSON Editor).

Configuración vacía del nodo Obtener horas trabajadas

Vista Formulario¶

1. Objetos de Entrada (Entry Object IDs) *Requerido¶

Los objetos de control de acceso que registran las entradas (por ejemplo, el lector/torniquete de ingreso). Haz clic en el campo para abrir el modal selector, busca y marca los objetos.

Modal de selección de objetos de entrada

2. Objetos de Salida (Exit Object IDs) *Requerido¶

Los objetos de control de acceso que registran las salidas (por ejemplo, el lector/torniquete de egreso). Se selecciona igual que los de entrada.

3. Hora de Inicio (Start Time) *Requerido¶

La fecha y hora de inicio del periodo a evaluar (selector de fecha y hora).

4. Hora de Fin (End Time) *Requerido¶

La fecha y hora de fin del periodo a evaluar.

5. Horas Esperadas de Trabajo (Expected Work Hours) *Requerido¶

El número de horas que se espera que el personal trabaje en la jornada (por defecto 8). Se usa para comparar contra las horas efectivamente trabajadas.

6. Tipos de Evento de Entrada/Salida (Entry/Exit Event Types) *Opcional¶

Permite afinar qué tipos de evento se consideran como entrada/salida (mediante el selector de tipos de evento). Útil cuando un mismo lector genera varios tipos de evento.

7. IDs de Empleados (Employee IDs) *Opcional¶

Lista (en formato JSON) de identificadores de empleados a los que limitar el cálculo. Si se deja vacío, se consideran todos los empleados con accesos en el periodo.

Formulario configurado del nodo Obtener horas trabajadas

Vista Editor de JSON¶

En la pestaña Editor de JSON (JSON Editor) puedes visualizar y editar directamente toda la consulta:

Vista JSON Editor del nodo Obtener horas trabajadas

Estructura JSON (Parámetros de entrada)¶

A continuación se muestra la estructura del JSON que se genera al configurar el nodo:

{
  "entry_object_ids": [
    "virtual.670cfb830fee4e7a92f2ce5fc4523bdf"
  ],
  "exit_object_ids": [
    "virtual.bb724db310544890b96a560a2fe1d903"
  ],
  "start_time": "",
  "end_time": "",
  "expected_work_hours": 8,
  "entry_exit_event_ids": [],
  "employee_ids": [
    "EMP-001",
    "EMP-002"
  ]
}

Campos del JSON¶

Campo	Tipo	Descripción
`entry_object_ids`	array (string)	IDs de los objetos que registran las entradas.
`exit_object_ids`	array (string)	IDs de los objetos que registran las salidas.
`start_time`	string	Fecha/hora de inicio del periodo (formato ISO 8601).
`end_time`	string	Fecha/hora de fin del periodo (formato ISO 8601).
`expected_work_hours`	number	Horas esperadas de la jornada (por defecto `8`).
`entry_exit_event_ids`	array (string)	(Opcional) Tipos de evento considerados como entrada/salida.
`employee_ids`	array (string)	(Opcional) IDs de empleados a los que limitar el cálculo.

Output: Dónde viene la data del nodo¶

Cuando la consulta se ejecuta correctamente, el nodo devuelve en su Output (Salida) el cálculo de horas trabajadas por empleado dentro del periodo, comparado contra las horas esperadas. Esta salida puede utilizarse en nodos posteriores para generar reportes, registrar en hojas de cálculo o notificar inconsistencias.

Para referenciar el resultado en nodos posteriores, utiliza la clave del nodo:

{{node_key}}

(Recuerda sustituir node_key por la clave asignada automáticamente al nodo en el lienzo.)

Ejemplos de uso¶

Ejemplo 1: Reporte diario de horas trabajadas¶

Caso de uso: Cada día a las 23:00, calcular las horas trabajadas por el personal entre los torniquetes de entrada y salida de la planta, y compararlas con la jornada de 8 horas.

Entry Object IDs: Torniquete de entrada.
Exit Object IDs: Torniquete de salida.
Expected Work Hours: 8
Start/End Time: El día en curso.

JSON de configuración:

{
  "entry_object_ids": ["virtual.670cfb830fee4e7a92f2ce5fc4523bdf"],
  "exit_object_ids": ["virtual.bb724db310544890b96a560a2fe1d903"],
  "start_time": "2026-06-18T00:00:00Z",
  "end_time": "2026-06-18T23:59:59Z",
  "expected_work_hours": 8,
  "employee_ids": []
}

Ejemplo 2: Cálculo para empleados específicos¶

Caso de uso: Calcular las horas de un subconjunto de empleados (por ejemplo, para una auditoría puntual).

Employee IDs: ["EMP-001", "EMP-002"]

Validación y errores¶

Condición	Causa / Solución habitual
Sin objetos de entrada/salida	Selecciona al menos un objeto de entrada y uno de salida; son obligatorios para el cálculo.
Resultado vacío	No hay eventos de acceso en el periodo, o los objetos seleccionados no corresponden a puntos de control con registros.
Rango de fechas inválido	Asegúrate de que `start_time` sea anterior a `end_time`.

Buenas prácticas¶

Definir bien entrada y salida: Asocia correctamente los objetos de entrada y de salida; un cruce incorrecto produce cálculos erróneos.
Acotar el periodo: Usa rangos de fechas razonables (por turno o por día) para obtener resultados claros y un buen rendimiento.
Combinar con reportes: Encadena la salida con un nodo de Google Sheets/Excel o de notificación para distribuir el reporte de asistencia.
Nombrar el nodo descriptivamente: Cambia el nombre del nodo en el lienzo (ej. "Horas trabajadas turno mañana") para identificarlo en el flujo.