🔍 ¿Qué hace este endpoint?

Este endpoint permite actualizar un registro específico del historial de cargos de un contrato en Aleluya, utilizando el identificador único de la empresa (company_id) y del historial de puesto de trabajo (id) indicados en la ruta. Se pueden actualizar:

Cargo (position_id): Cambiar el cargo asignado a la persona en ese período.
Sede (location_id): Cambiar la sede donde está asignada la persona.
Área (area_id): Cambiar el área a la que pertenece la persona.
Fechas (initial_day, end_day): Modificar el rango de fechas del período.

Al actualizar las fechas, el sistema ajusta automáticamente las fechas de los registros adyacentes para mantener la continuidad de la línea de tiempo del historial.

🎯 ¿Cuándo usar este endpoint?

Para corregir un cargo, sede o área asignada incorrectamente en un período del historial.
Para ajustar las fechas de un período cuando hubo un cambio de cargo, sede o área en una fecha distinta a la registrada.
Cuando se necesita modificar un registro histórico intermedio y el sistema debe recalcular automáticamente las fechas de los registros anterior y siguiente.

📌 Consideraciones importantes

Permisos y autenticación

Solo usuarios con acceso a la empresa y rol administrador (admin), contador (accountant) u organizador (organizer) pueden ejecutar este endpoint.
Los usuarios con rol revisor (reviewer) también tienen acceso de solo lectura.
Retorna 401 No autenticado si el token es inválido o el usuario no pertenece a la empresa.
Retorna 403 No autorizado si el usuario no tiene un rol autorizado (por ejemplo, usuarios con rol worker o external_organizer).

Requisitos previos

El campo company_id debe corresponder a una empresa existente; de lo contrario, se responde 404 Empresa no existe.
El campo contract_id debe corresponder a un contrato que pertenezca a la empresa indicada; de lo contrario, se responde 404 Historial de puesto de trabajo no existe.

🛡️ Validaciones

Validaciones de fechas

La initial_day y end_day deben tener formato de fecha válido (YYYY-MM-DD). Si el formato es inválido, se retorna 422 con el error initial_day_invalid_format o end_day_invalid_format respectivamente.
La fecha inicial se ajusta automáticamente al primer día del mes proporcionado. Si es el primer o único historial del contrato, se ajusta a la fecha inicial del contrato.
La fecha final se ajusta automáticamente: si es el último registro, se establece como la fecha final del contrato; si es un registro intermedio, se ajusta al último día del mes.
La initial_day no puede ser superior a la fecha final del período de nómina actual más 15 días. De lo contrario, se retorna 422 con el error contract_initial_day.
Las fechas deben estar dentro del rango del contrato (entre la fecha inicial y la fecha final). De lo contrario, se retorna 422 con el error invalid_contract_position_history_range.
Las fechas no pueden solaparse con otros registros del historial del mismo contrato. Si hay solapamiento, se retorna 422 con el error duplicated_contract_position_history_dates.

Validaciones de datos

Los campos area_id, location_id y position_id son opcionales. Se puede crear un registro con solo algunos de estos campos o incluso sin ninguno.

Validación de sede (location)

La sede solo puede asignarse en fechas específicas: la fecha inicial del contrato o el primer día de un mes. Si se intenta asignar en otra fecha, se retorna 422 con el error invalid_contract_position_history_location_update (código 4015).

📘
Al actualizar las fechas de un historial de puesto de trabajo, las fechas de los registros adyacentes se modifican automáticamente para mantener la continuidad. Esto puede afectar nóminas electrónicas ya generadas, las cuales serán recalculadas de forma asíncrona.