Skip to content
SepankaPlus

Calcular Horas Laboradas

Calcular Horas Laboradas

Section titled “Calcular Horas Laboradas”

Calcula el tiempo trabajado basado en los registros de checadas del usuario para una fecha específica.

Endpoint

Section titled “Endpoint”
POST /api/v2/incidents/get_hours_labor

Headers

Section titled “Headers”
Authorization: Bearer {token}
Content-Type: application/json

Parámetros de Entrada

Section titled “Parámetros de Entrada”
CampoTipoRequeridoDescripción
datestring❌Fecha específica en formato Y-m-d (ej: 2024-01-15)

Nota: El user_id se obtiene automáticamente del token de autorización. No es necesario enviarlo como parámetro.

Cálculo Automático

Section titled “Cálculo Automático”

El sistema calcula automáticamente basado en:

  • ✅ Entrada y Salida: Registros tipo in y out
  • ✅ Comida: Registros tipo break_out y break_in (opcional)
  • ✅ Horario de Trabajo: Horas esperadas vs horas trabajadas
  • ✅ Tiempo Configurado: Horarios rígidos vs flexibles

Lógica de Cálculo

Section titled “Lógica de Cálculo”

Horario Normal (Sin Comida)

Section titled “Horario Normal (Sin Comida)”

Para usuarios sin tiempo de comida:

Tiempo Laborado = Hora Salida - Hora Entrada

Horario con Comida

Section titled “Horario con Comida”

Para usuarios con tiempo de comida:

Tiempo Trabajo 1 = Hora Salida Comida - Hora Entrada
Tiempo Trabajo 2 = Hora Salida Final - Hora Entrada Comida
Tiempo Laborado Total = Tiempo Trabajo 1 + Tiempo Trabajo 2

Ejemplo de Solicitud

Section titled “Ejemplo de Solicitud”
POST /api/v2/incidents/get_hours_labor
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Content-Type: application/json


{
  "date": "2024-01-15"
}

Sin Fecha Específica

Section titled “Sin Fecha Específica”
{}

Respuestas

Section titled “Respuestas”

✅ Cálculo Exitoso (200)

Section titled “✅ Cálculo Exitoso (200)”
{
  "success": true,
  "message": "Horas laboradas calculadas exitosamente",
  "data": {
    "hours_info": "08:30 horas de un total de 08:00"
  }
}

Para horario con comida:

{
  "success": true,
  "message": "Horas laboradas calculadas exitosamente",
  "data": {
    "hours_info": "08:15 horas de un total de 08:00"
  }
}

❌ Token Inválido (401)

Section titled “❌ Token Inválido (401)”
{
  "success": false,
  "message": "Token de autorización inválido o faltante",
  "data": null
}

❌ Horario No Válido (400)

Section titled “❌ Horario No Válido (400)”
{
  "success": false,
  "message": "Horario no válido para el usuario",
  "data": {
    "hours_info": "Faltan registros de checada"
  }
}

Interpretación del Resultado

Section titled “Interpretación del Resultado”

Formato del Campo hours_info

Section titled “Formato del Campo hours_info”
"HH:MM horas de un total de HH:MM"

Donde:

  • Primer tiempo: Horas realmente trabajadas (calculadas)
  • Segundo tiempo: Horas esperadas según horario

Ejemplos de Interpretación

Section titled “Ejemplos de Interpretación”
ResultadoSignificado
"08:30 horas de un total de 08:00"Se trabajaron 30 minutos extras
"07:45 horas de un total de 08:00"Faltaron 15 minutos de trabajo
"08:00 horas de un total de 08:00"Horario cumplido exactamente

Estados de Cálculo

Section titled “Estados de Cálculo”

Registros Completos

Section titled “Registros Completos”
  • ✅ 2 registros: Entrada y salida (sin comida)
  • ✅ 4 registros: Entrada, salida comida, entrada comida, salida final

Registros Incompletos

Section titled “Registros Incompletos”
  • ❌ 1 registro: Solo entrada (falta salida)
  • ❌ 3 registros: Entrada, salida comida, entrada comida (falta salida final)
  • ❌ 0 registros: Ninguna checada registrada

Casos de Uso

Section titled “Casos de Uso”
  1. Cálculo de nómina: Horas trabajadas vs horas pagadas
  2. Reportes de asistencia: Análisis de cumplimiento de horarios
  3. Dashboard personal: Usuario ve sus horas trabajadas
  4. Tiempo extra: Detectar horas adicionales trabajadas
  5. Compensaciones: Identificar tiempo faltante o excedente

Validaciones del Sistema

Section titled “Validaciones del Sistema”
  • Usuario debe tener empleado asociado
  • Usuario debe tener horario configurado
  • Horario debe ser tipo “rigid” para cálculo automático
  • Registros deben tener fechas válidas en la fecha consultada

Horarios Especiales

Section titled “Horarios Especiales”

Horarios Nocturnos

Section titled “Horarios Nocturnos”

El sistema maneja checadas que cruzan medianoche automáticamente.

Horarios Rotativos

Section titled “Horarios Rotativos”

Para horarios que cambian por día, el cálculo se adapta al día específico consultado.

Días de Descanso

Section titled “Días de Descanso”

Si el usuario no debe trabajar el día consultado, el sistema indica la situación.

Mensajes Típicos

Section titled “Mensajes Típicos”
  • "Faltan registros de checada": No hay suficientes checadas
  • "Falta un registro de checada": Solo hay entrada o salida
  • "Horario cumplido exactamente": Horas trabajadas = horas esperadas
  • Tiempo específico: Cálculo preciso en formato HH:MM