Obtener Saldo de Horas Banco

Consulta el saldo disponible de horas banco (tiempo extra acumulado) para un usuario en un año específico.

Endpoint

POST /api/v2/incidents/get_hour_bank

Headers

Authorization: Bearer {token}
Content-Type: application/json

Parámetros de Entrada

Campo	Tipo	Requerido	Descripción
`year`	integer	❌	Año a consultar (2000-2100, por defecto año actual)

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

Beneficio de Tiempo Extra

El sistema consulta automáticamente el beneficio con:

✅ Clave corta: TE (Tiempo Extra)
✅ Tipo: Relacionado con tiempo trabajado
✅ Acumulable: Permite formación de banco de horas

Ejemplo de Solicitud

POST /api/v2/incidents/get_hour_bank
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Content-Type: application/json

{
  "year": 2024
}

Con Año Actual (Por Defecto)

{}

Respuestas

✅ Saldo Encontrado (200)

{
  "success": true,
  "message": "Saldo de horas obtenido exitosamente",
  "data": {
    "hour_bank": 15.5,
    "year": 2024
  }
}

✅ Sin Beneficio Configurado (200)

{
  "success": true,
  "message": "No existe beneficio de tiempo extra",
  "data": {
    "hour_bank": 0,
    "year": 2024
  }
}

✅ Saldo Vacío (200)

{
  "success": true,
  "message": "Saldo de horas obtenido exitosamente",
  "data": {
    "hour_bank": 0,
    "year": 2024
  }
}

❌ Datos Inválidos (422)

{
  "success": false,
  "message": "Datos de entrada inválidos",
  "errors": {
    "year": ["El año debe estar entre 2000 y 2100"]
  },
  "data": null
}

❌ Token Inválido (401)

{
  "success": false,
  "message": "Token de autorización inválido o faltante",
  "data": null
}

Campos de Respuesta

Campo	Tipo	Descripción
`hour_bank`	float	Cantidad de horas disponibles en banco
`year`	integer	Año consultado

¿Qué es el Banco de Horas?

El banco de horas es un sistema de acumulación donde:

✅ Se acumulan: Horas extra trabajadas no pagadas
✅ Se pueden usar: Para faltantes, salida temprana, permisos
✅ Son flexibles: Pueden usarse parcialmente según necesidades
✅ Tienen vigencia: Generalmente por año fiscal

Creación Automática

El sistema crea automáticamente el registro si no existe:

INSERT INTO balances (
    year,
    benefit_id,
    user_id,
    amount: 0,
    pending: 0,
    until: null
)

Casos de Uso

Consulta de saldo: Usuario revisa horas disponibles
Programación de permisos: Antes de solicitar tiempo libre
Compensación de faltas y tardanzas: Usar horas para compensar
Aplicaciones móviles: Dashboard personal de beneficios
Reportes administrativos: Estado del banco por departamentos
Integración nómina: Cálculo de horas trabajadas vs salario

Validaciones

Rango de Año

✅ Mínimo: 2000 (año mínimo válido)
✅ Máximo: 2100 (año máximo válido)
✅ Por defecto: Año actual si no se especifica

Usuario Válido

✅ Debe existir en tabla users
✅ Se crea registro automático si no existe balance
✅ Manejo de casos donde no hay beneficio TE

Estados del Banco

Estado	Descripción
`pending: 0`	Sin horas acumuladas
`pending: > 0`	Con horas disponibles
`benefit: null`	Beneficio no configurado

Ejemplos de Saldo

Con Horas Disponibles

{
  "hour_bank": 24.5,
  "year": 2024
}

Interpretación: 24 horas y 30 minutos disponibles

Con Horas Fraccionarias

{
  "hour_bank": 0.5,
  "year": 2024
}

Interpretación: 30 minutos disponibles

Sin Saldo

{
  "hour_bank": 0,
  "year": 2024
}

Interpretación: No hay horas disponibles en el banco

Migración y Configuración

Se requiere configuración inicial:

Beneficio TE debe existir en tabla benefits
Tipo de beneficio debe ser time
Clave corta debe ser TE (Tiempo Extra)

El sistema maneja:

✅ Creación automática de registros de balance
✅ Inicialización con valores cero
✅ Consulta sin configuración previa