🔍 ¿Qué hace este endpoint?

Actualiza de forma parcial los datos de una persona registrada en una empresa. En una única solicitud es posible modificar cualquier combinación de datos personales, del contrato activo, del salario, del detalle de contrato, del historial de posición y del usuario de acceso.

Solo se actualizan los campos enviados en la solicitud. Los campos omitidos conservan su valor actual.

Dependiendo de los parámetros enviados, el sistema ejecuta distintas acciones de forma automática:

Si se envían parámetros del contrato (category, initial_day, term, etc.), se actualiza el contrato completo y se regeneran las nóminas afectadas.
Si solo se envían parámetros del salario (base_salary, wage_category, etc.) sin parámetros de contrato, se crea un nuevo registro de salario y se recalculan las nóminas del período actual.
Si se cambia el detalle de contrato (contributor_subtype, work_center_id, etc.) sin cambiar el salario, se recalculan las nóminas en el rango del detalle.
Si se desactiva la persona (active: false), se envía automáticamente una notificación de cambio al correo de la empresa si corresponde.
Si se marca finish_onboarding: true y la persona no lo había completado, se registra la fecha de finalización del onboarding.

🎯 ¿Cuándo usar este endpoint?

Actualizar el salario de una persona: Cuando hay un aumento o ajuste salarial. El sistema crea un nuevo registro de salario y recalcula las nóminas del período actual.
Cambiar la sede, cargo o área de una persona: Para reasignar a la persona a una nueva ubicación organizacional sin cambiar el contrato completo.
Activar o desactivar una persona: Cuando un empleado regresa de una ausencia prolongada o debe suspenderse temporalmente del procesamiento de nómina.
Actualizar la información de seguridad social: Para cambiar la EPS, el fondo de pensiones o el fondo de cesantías asignados al contrato.
Vincular o actualizar el usuario de acceso: Para asignar o modificar el correo de acceso a la plataforma de la persona.

📌 Consideraciones importantes

Permisos y autenticación:

El usuario debe estar autenticado.
El usuario debe tener acceso a la empresa especificada en {company_id} con rol administrador (admin) o contador (accountant). Los revisores (reviewer) no pueden actualizar personas.
Retorna 401 Credenciales inválidas si la autenticación no es válida o ha expirado.
Retorna 403 No tienes permisos para realizar esta acción si el usuario no tiene el rol requerido.
Retorna 404 Empresa no existe si el company_id no corresponde a una empresa registrada.
Retorna 404 Persona no existe si el id de la persona no existe en la empresa.

Requisitos previos:

Esta acción requiere una suscripción activa o estar en período de prueba. Retorna 402 si la empresa no tiene una suscripción válida.
Retorna 402 si se intenta reactivar una persona (active: true) y la empresa ha superado el número máximo de personas permitidas por su plan.
No es posible editar una persona de prueba (demo_flag: true) cambiando su nombre, apellido o número de documento fuera del entorno de stage. Retorna 422 si se intenta.
No es posible editar la persona si su contrato activo ya tiene una liquidación registrada. Retorna 422 si se intenta.

Datos adicionales a tener en cuenta:

Si se intenta reactivar (active: true) una persona cuyo contrato tiene fecha final anterior al período actual, la operación es rechazada con 422.
Los parámetros de contrato, salario, detalle e historial de posición se envían todos bajo la llave worker.
Si se envía email como cadena vacía y la persona tiene usuario, el usuario y su acceso son eliminados.

🛡️ Validaciones

Cuando alguna de estas validaciones no se cumple, el endpoint responde 422 Datos inválidos o no procesables con el detalle del error:

❌ Nombre con formato inválido

Ocurre cuando name tiene menos de 3 o más de 30 caracteres, o contiene caracteres no permitidos (<>$\).

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Nombre solo puede contener números, letras y los siguientes caracteres: '-_'.",
      "code": "0116",
      "object": "name",
      "index": 0
    }
  ]
}

❌ Apellido con formato inválido

Ocurre cuando last_name tiene menos de 3 o más de 30 caracteres, o contiene caracteres no permitidos.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Apellido solo puede contener números, letras y los siguientes caracteres: '-_'.",
      "code": "0116",
      "object": "last_name",
      "index": 0
    }
  ]
}

❌ Contrato fuera del período actual

Ocurre cuando se intenta reactivar una persona (active: true) cuyo contrato activo tiene fecha final anterior al período de nómina actual. Debes actualizar la fecha del contrato o crear un nuevo contrato antes de reactivar a la persona.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "La fecha final del contrato es menor a las fechas del periodo actual, por lo que no se puede activar.",
      "code": "0706",
      "object": "contract",
      "index": 0
    }
  ]
}

❌ Contrato ya liquidado

Ocurre cuando se intenta editar una persona cuyo contrato activo ya tiene una liquidación registrada. No es posible editar personas con contratos liquidados; primero elimina la liquidación si corresponde.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "El contrato ya ha sido liquidado, por lo cual no puedes editarlo.",
      "code": "3105",
      "object": "contract",
      "index": 0
    }
  ]
}

❌ Intento de editar persona de prueba

Ocurre cuando se intenta actualizar el nombre, apellido o número de documento de una persona de prueba (demo_flag: true) fuera del entorno de stage.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Esta es una persona de prueba. No puedes actualizar nombres, apellidos o número de identificación.",
      "code": "0106",
      "object": "worker",
      "index": 0
    }
  ]
}