🔍 ¿Qué hace este endpoint?

Este endpoint permite crear un nuevo registro en el historial de cargos de un contrato específico de una persona en Aleluya. Un registro de historial de cargos representa un período durante el cual la persona tuvo una combinación específica** de cargo, sede y área dentro de su contrato.

Al crear un nuevo registro:

Se establece la nueva combinación de cargo, sede y área que aplica para la persona a partir de la fecha indicada.
El sistema ajusta automáticamente las fechas del registro anterior: la fecha final del historial previo se actualiza al día anterior a la fecha inicial del nuevo registro.
La fecha final del nuevo registro se establece automáticamente como la fecha final del contrato (si la tiene).
La fecha inicial se ajusta automáticamente al primer día del mes indicado. Si es el primer registro del contrato, se ajusta a la fecha inicial del contrato.
Si la empresa tiene nóminas electrónicas generadas que se ven afectadas por el cambio, se realiza un recalculo automático de las nóminas electrónicas en los períodos impactados.

🎯 ¿Cuándo usar este endpoint?

Para registrar un cambio de cargo, sede o área de una persona dentro de un contrato existente (por ejemplo: una promoción, un traslado de sede o un cambio de área).
Para asignar por primera vez un cargo, sede y/o área a un contrato que aún no tiene historial de cargos.
Cuando un administrador o contador necesita reflejar un movimiento organizacional que afecta la nómina electrónica o la información contractual de la persona.

📌 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 id debe corresponder a un historial de puesto de trabajo que pertenezca a un contrato de la empresa indicada; de lo contrario, se responde 404 Historial de puesto de trabajo no existe.

🛡️ Validaciones

Validaciones de fechas

La initial_day (fecha inicial) es obligatoria y debe tener un formato de fecha válido (YYYY-MM-DD). Si el formato es inválido, se retorna 422 con el error initial_day_invalid_format.
La end_day (fecha final) es opcional. Si se envía con formato inválido, se retorna 422 con el error end_day_invalid_format.
La fecha inicial se ajusta automáticamente al primer día del mes proporcionado. Si es el primer historial del contrato, se ajusta a la fecha inicial del contrato.
La fecha final se establece automáticamente como la fecha final del contrato; no es necesario enviarla.
La fecha inicial debe estar dentro del rango de fechas del contrato (entre la fecha inicial y la fecha final del contrato). De lo contrario, se retorna 422 con el error invalid_contract_position_history_range (código 4012).
La fecha inicial debe ser posterior a la fecha inicial del historial de cargo actual. De lo contrario, se retorna 422 con el error contract_position_history_initial_day (código 4011).
La fecha inicial 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.

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.
El nuevo registro no puede ser idéntico al historial de cargo actual. Si el area_id, location_id y position_id son iguales a los del registro actual, se retorna 422 con el error invalid_duplicate_contract_position_history (código 4016).

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 crear un nuevo historial de cargo, la fecha final del registro anterior se modifica automáticamente. Esto puede afectar nóminas electrónicas ya generadas, las cuales serán recalculadas de forma asíncrona.