Control Horario

Timeclock

El sistema de fichaje registra automáticamente las entradas y salidas de los empleados. Soporta tanto el modo kiosk (terminal de fichaje) como el fichaje manual.

Registro de fichaje (línea de tiempo)

interface TimeclockEntry {
  id: string;
  employee_id: string;
  date: string;              // YYYY-MM-DD
  check_in?: string;         // HH:mm
  check_out?: string;        // HH:mm
  check_in_method: 'kiosk' | 'manual' | 'plugin';
  check_out_method: 'kiosk' | 'manual' | 'plugin';
  break_minutes: number;     // Minutos de descanso descontados
  total_hours: number;        // Horas efectivas trabajadas
  shift_id?: string;
  notes?: string;
  status: 'open' | 'closed' | 'edited';
  created_at: string;
}

Endpoints

Método	Ruta	Descripción
POST	/api/hr/timeclock/check-in	Registrar entrada
POST	/api/hr/timeclock/check-out	Registrar salida
GET	/api/hr/timeclock	Listar registros
GET	/api/hr/timeclock/:id	Ver registro
PATCH	/api/hr/timeclock/:id	Editar registro
POST	/api/hr/timeclock/:id/close	Cerrar registro

Registrar entrada

POST /api/hr/timeclock/check-in
Authorization: Bearer <token>
Content-Type: application/json

{
  "employee_id": "emp_001",
  "date": "2026-05-08",
  "check_in": "09:00",
  "method": "kiosk"
}

Registrar salida

POST /api/hr/timeclock/check-out
Authorization: Bearer <token>
Content-Type: application/json

{
  "employee_id": "emp_001",
  "date": "2026-05-08",
  "check_out": "18:00",
  "method": "kiosk",
  "break_minutes": 30
}

Modo Kiosk

El modo kiosk es una pantalla dedicada para que los empleados fichen sin acceder al ERP completo.

URL de acceso: /hr/kiosk

Se configura en Ajustes > RRHH > Kiosk:

{
  "enabled": true,
  "auto_logout_minutes": 30,
  "show_department": true,
  "show_employee_photo": true,
  "allow_manual_entry": false,
  "kiosk_pin": "1234"
}

En el kiosk, el empleado:

1. Selecciona su nombre o introduce su PIN
2. Ve su último fichaje (si esta dentro)
3. Ficha entrada o salida con un solo toque
4. Ve un resumen de sus horas del día

Listar fichajes por empleado y mes

GET /api/hr/timeclock?employee_id=emp_001&from=2026-05-01&to=2026-05-31

Respuesta:

{
  "data": [
    {
      "id": "tc_001",
      "date": "2026-05-07",
      "check_in": "09:00",
      "check_out": "18:00",
      "break_minutes": 30,
      "total_hours": 8.5,
      "shift": { "name": "Manana" }
    },
    {
      "id": "tc_002",
      "date": "2026-05-08",
      "check_in": "09:00",
      "check_out": null,
      "total_hours": null,
      "status": "open"
    }
  ]
}

---

Calendario de tareas

Modelo

interface Task {
  id: string;
  title: string;
  description?: string;
  employee_id?: string;       // Asignado a
  department_id?: string;     // Asignado al departamento
  due_date: string;           // Fecha de vencimiento
  due_time?: string;          // Hora
  priority: 'low' | 'medium' | 'high' | 'urgent';
  status: 'pending' | 'in_progress' | 'completed' | 'cancelled';
  estimated_hours?: number;
  actual_hours?: number;
  tags?: string[];
  created_by: string;
  created_at: string;
  completed_at?: string;
}

Endpoints

Método	Ruta	Descripción
GET	/api/hr/tasks	Listar tareas
POST	/api/hr/tasks	Crear tarea
GET	/api/hr/tasks/:id	Ver tarea
PATCH	/api/hr/tasks/:id	Actualizar tarea
DELETE	/api/hr/tasks/:id	Eliminar tarea
POST	/api/hr/tasks/:id/complete	Marcar como completada

Crear tarea

POST /api/hr/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Revisar cierre del mes",
  "description": "Verificar que todas las facturas esten asentadas antes del cierre contable",
  "employee_id": "emp_003",
  "due_date": "2026-05-15",
  "priority": "high",
  "estimated_hours": 2
}

Vista de calendario

GET /api/hr/tasks/calendar?view=month&from=2026-05-01&to=2026-05-31

Devuelve las tareas estructuradas para renderizar en un calendario mensual o semanal.

---

Registro de horas (time slots)

Para casos donde se necesita registro granular de tiempo (proyectos, tareas concretas), existen los time slots.

interface TimeSlot {
  id: string;
  task_id?: string;
  employee_id: string;
  date: string;
  start_time: string;
  end_time: string;
  hours: number;
  notes?: string;
}

GET /api/hr/tasks/:taskId/time-slots
POST /api/hr/tasks/:taskId/time-slots

---

Resumen de horas

Informe mensual de horas

GET /api/hr/reports/labor-cost?from=2026-05-01&to=2026-05-31

{
  "period": "2026-05",
  "total_hours": 8400,
  "total_employees": 12,
  "employees": [
    {
      "employee_id": "emp_001",
      "name": "Maria Garcia",
      "total_hours": 168,
      "overtime_hours": 8,
      "absent_hours": 0
    }
  ],
  "by_department": [
    { "department": "Ventas", "total_hours": 3200 }
  ]
}

Partes de horas semanales

GET /api/hr/timeclock/weekly?from=2026-05-05&to=2026-05-11

Para exportación a sistemas de gestión de nóminas externos.

---

Resumen de endpoints

Método	Ruta	Descripción
POST	/api/hr/timeclock/check-in	Registrar entrada
POST	/api/hr/timeclock/check-out	Registrar salida
GET	/api/hr/timeclock	Listar fichajes
PATCH	/api/hr/timeclock/:id	Editar fichaje
POST	/api/hr/timeclock/:id/close	Cerrar registro
GET	/api/hr/tasks	Listar tareas
POST	/api/hr/tasks	Crear tarea
GET	/api/hr/tasks/:id	Ver tarea
PATCH	/api/hr/tasks/:id	Actualizar tarea
POST	/api/hr/tasks/:id/complete	Completar tarea
GET	/api/hr/tasks/calendar	Calendario de tareas
GET	/api/hr/reports/labor-cost	Informe de costes laborales