Documentación de Clocki

Glosario de Conceptos

Conceptos Básicos

Fichaje / Marcaje

Registro de entrada o salida en el sistema. Cada fichaje incluye fecha, hora exacta y tipo (entrada/salida).

Jornada Laboral

Tiempo que transcurre entre el primer fichaje de entrada y el último fichaje de salida en un día. Puede incluir pausas no trabajadas.

Horas Trabajadas

Total de tiempo registrado entre entradas y salidas. Se calcula automáticamente sumando todos los períodos trabajados del día.

Planificación

Horario

Definición de un turno de trabajo con franjas horarias específicas. Ejemplos: "Mañana 8-15", "Tarde 15-22", "Partido 8-13 y 16-20".

Tipo de Semana

Patrón semanal que define qué horario se aplica cada día de la semana y qué días son libres.

Período de Calendario

Rango de fechas durante el cual se aplica un tipo de semana a un empleado. Permite cambiar horarios en fechas específicas.

Ubicación

Centro de trabajo (oficina, almacén, delegación). Permite asignar festivos específicos por ubicación.

Eventos

Evento de Día Completo

Ausencia que abarca días completos. Ejemplos: vacaciones, baja médica, día personal. No se trabaja durante estos días.

Evento por Horas

Ausencia de duración específica dentro de una jornada. Ejemplos: permiso de 2 horas, cita médica. Se trabaja el resto del día.

Tipos de Eventos Comunes

• Vacaciones: Días libres anuales (normalmente 22 días)
• Baja médica: Ausencia por enfermedad o accidente
• Permiso: Ausencia por asuntos personales (horas o días)
• Formación: Tiempo dedicado a capacitación
• Festivo: Días no laborables oficiales

Métricas y Cálculos

Horas Planificadas

Horas que deberías trabajar según tu horario asignado, sin descontar eventos.

Horas Planificadas Efectivas

Horas que realmente deberías trabajar después de descontar eventos aprobados (vacaciones, permisos, etc.).

Saldo de Horas

Diferencia entre horas trabajadas y horas planificadas efectivas. Puede ser positivo (trabajaste más) o negativo (trabajaste menos).

Vacaciones Planeadas

Total de días de vacaciones solicitados y aprobados para todo el año (pasados y futuros), excluyendo festivos.

Vacaciones Realizadas

Días de vacaciones ya disfrutados (hasta hoy), excluyendo festivos.

Saldo de Vacaciones

Días de vacaciones que aún puedes solicitar.

Bloques del Dashboard

El dashboard está organizado en bloques que muestran información específica. Aquí detallamos cada uno:

📊 Horas Mensuales

Muestra el resumen de horas del mes hasta ayer (no incluye el día actual).

Métrica	Descripción	Color
Horas Planificadas	Total de horas según tu horario (sin descontar eventos)	Gris
Horas Efectivas	Horas planificadas menos eventos (vacaciones, permisos, etc.)	Gris
Horas Realizadas	Total de horas trabajadas según fichajes	Azul
Saldo	Diferencia entre realizadas y efectivas	Verde (+) / Rojo (-)

✏️ Últimos Marcajes

Lista de los últimos 15 días con marcajes registrados, ordenados del más reciente al más antiguo.

• Muestra entradas y salidas de cada día
• Indica horas trabajadas del día
• Color según saldo diario (verde/azul/naranja)
• Clickeable para editar marcajes pasados

📅 Próximos 15 Días

Visualización de la planificación futura (a partir de pasado mañana).

🎫 Eventos (Acumulado Anual)

Resumen completo de eventos del año actual. Siempre muestra el año en curso, independiente del mes seleccionado en el calendario.

Métrica	Descripción
Vacaciones Planeadas	Días de vacaciones solicitados para todo el año (aprobados + pendientes)
Vacaciones Asignadas	Total de días de vacaciones anuales (típicamente 22 días)
Saldo Vacaciones	Días que aún puedes solicitar (Asignadas - Planeadas)
Vacaciones Realizadas	Días de vacaciones ya disfrutados (hasta hoy)
Días de Baja	Total de días de baja médica en el año
Horas de Permiso	Total de horas de permisos solicitados (eventos por horas)

📆 Calendario Interactivo

Vista mensual con navegación sin recarga de página (AJAX).

• Flechas de navegación: Cambian de mes sin recargar la página
• Click en día: Abre modal para crear evento o marcaje
• Festivos marcados: Con color rojo distintivo
• Eventos visibles: Con color del tipo de evento
• Horarios mostrados: Tramos horarios del día
• Exportar a PDF: Genera informe del mes visible

📈 Gráfico de Eventos del Año

Visualización gráfica de todos los eventos a lo largo del año con diferentes colores por tipo.

Definición de Cálculos

Horas Trabajadas del Día

Suma de todos los períodos entre entradas y salidas:

Horas Planificadas del Mes

Suma de las horas teóricas de todos los días laborables del mes según el horario asignado:

Horas Efectivas del Mes

Horas que realmente deberías trabajar después de descontar eventos:

Saldo de Horas

Diferencia entre lo trabajado y lo esperado:

Cálculo de Vacaciones

Vacaciones Planeadas (Año completo)

Ejemplo de Exclusión de Festivos

Saldo Diario (Código de Colores)

Cada día tiene un saldo calculado que determina su color:

Condición	Color	Significado
Saldo = 0	Azul (#0e258f)	Trabajaste exactamente las horas planificadas
Saldo > 0	Verde (#16a34a)	Trabajaste más de lo planificado (horas extras)
Saldo < 0	Naranja (#f59e0b)	Trabajaste menos de lo planificado

Guía para Empleados 👨‍💼

1. Fichaje Diario

2. Consultar Tus Horas

Desde tu dashboard puedes ver en tiempo real:

Estado Actual

• Si estás dentro o fuera de jornada
• Hora de tu último fichaje
• Horas acumuladas hoy (si ya fichaste salida)

Resumen del Mes

• Horas Realizadas: Total trabajado hasta ayer
• Horas Planificadas: Total según tu horario
• Horas Efectivas: Descontando vacaciones/permisos
• Saldo: Diferencia (verde si positivo, rojo si negativo)

Últimos Marcajes

• Lista de tus últimos 15 días con fichajes
• Detalle de cada entrada y salida
• Horas trabajadas por día
• Color según rendimiento (verde/azul/naranja)

3. Solicitar Vacaciones

4. Solicitar Permiso por Horas

Para ausencias de solo unas horas (cita médica, gestión personal):

5. Ver Tu Balance de Vacaciones

En el bloque "Eventos (Acumulado Anual)" puedes ver:

• Vacaciones Asignadas: Tus días anuales (normalmente 22)
• Vacaciones Planeadas: Días solicitados para todo el año
• Saldo: Días que aún puedes solicitar
• Vacaciones Realizadas: Días ya disfrutados

Guía para Administradores 👔

1. Configuración Inicial

A. Crear Ubicaciones

B. Configurar Festivos

C. Crear Horarios

D. Crear Tipos de Semana

2. Gestión de Personal

Dar de Alta un Empleado

Asignar Calendario a Empleado

3. Aprobación de Solicitudes

4. Editar Fichajes de Empleados

Si un empleado olvidó fichar o fichó mal:

5. Ver Estadísticas del Equipo

Dashboard Vista Admin

• Horas Semanales por Usuario: Ranking de horas trabajadas esta semana
• Horas Mensuales por Usuario: Total del mes por empleado
• Gantt de Asistencias: Vista semanal de quién trabaja cada día/hora

Vista de Usuario Individual

Desde el dashboard, usa el selector de usuario para ver el dashboard de cualquier empleado y analizar:

• Sus horas del mes
• Su saldo acumulado
• Sus próximos turnos
• Su balance de vacaciones

6. Exportar Datos

API REST de Clocki

Clocki ofrece una API REST completa para integrar con PowerBI, Excel, sistemas de nóminas y otras herramientas.

1. Generar Token de API

2. Endpoints Disponibles

Tablas Maestras (Dimensiones)

Endpoint	Descripción	Campos Clave
/api/export/users.php	Usuarios de la empresa	user_id, user_name, location_id
/api/export/locations.php	Ubicaciones/centros de trabajo	location_id, location_name
/api/export/schedules.php	Horarios configurados	schedule_id, schedule_name
/api/export/week_types.php	Tipos de semana	week_type_id, week_type_name
/api/export/companies.php	Datos de la empresa	company_id, company_name

Tablas de Hechos

Endpoint	Descripción	Rango por Defecto
/api/export/analytics.php	Datos diarios detallados por empleado	Año anterior → Hoy
/api/export/punches.php	Fichajes de entrada/salida	Año anterior → Hoy
/api/export/events.php	Eventos (vacaciones, bajas, permisos)	Año anterior → Hoy
/api/export/holidays.php	Festivos configurados	Año anterior → Fin año actual
/api/export/statistics.php	Estadísticas mensuales agregadas	Requiere parámetro month

3. Autenticación

Pasa el token como parámetro GET en la URL:

/api/export/users.php?token=TU_TOKEN_AQUI

4. Formatos de Salida

• JSON (por defecto): ?token=XXX
• CSV: ?token=XXX&format=csv
• XML: ?token=XXX&format=xml

5. Ejemplo de Uso

Obtener analítica diaria:

GET /api/export/analytics.php?token=abc123xyz

Response:
{
  "success": true,
  "count": 450,
  "data": [
    {
      "user_id": 5,
      "user_name": "Juan Pérez",
      "user_email": "juan@empresa.es",
      "location_id": 1,
      "date": "2025-01-02",
      "day_of_week": "Jueves",
      "schedule_id": 3,
      "schedule_name": "Turno Mañana",
      "week_type_id": 1,
      "is_holiday": 0,
      "is_free_day": 0,
      "planned_hours": 7.00,
      "worked_hours": 7.25,
      "balance_hours": 0.25
    },
    ...
  ]
}

Obtener usuarios con ubicación:

GET /api/export/users.php?token=abc123xyz

Response:
{
  "success": true,
  "count": 15,
  "data": [
    {
      "user_id": 5,
      "email": "juan@empresa.es",
      "first_name": "Juan",
      "last_name": "Pérez",
      "user_name": "Juan Pérez",
      "role": "user",
      "location_id": 1,
      "location_name": "Oficina Central",
      "active": 1
    },
    ...
  ]
}

6. Integración con PowerBI

7. Probador de API Integrado

El panel de admin (Admin → API y Exportación) incluye un probador visual donde puedes:

• Probar cada endpoint con un clic
• Ver la respuesta JSON en tiempo real
• Generar código Power Query (M) para copiar en Excel/PowerBI
• Exportar directamente a CSV o XML