🔍 ¿Qué hace este endpoint?

Registra una nueva persona en la empresa. Este endpoint permite crear:

Personas regulares: Trabajadores con contrato completo, incluyendo información de seguridad social, salario y centro de trabajo.
Personas demo: Trabajadores de prueba para demostración del sistema, con datos simplificados.

Al crear una persona regular, el sistema automáticamente:

Genera el contrato laboral con las condiciones pactadas.
Configura el detalle del contrato (subtipo de cotizante, centro de trabajo).
Establece el salario y beneficios (auxilio de transporte, trabajo remoto).
Genera las nóminas para los períodos vigentes.
Opcionalmente, crea un usuario con acceso a la plataforma.

🎯 ¿Cuándo usar este endpoint?

Cuando se requiere crear una nueva persona (empleado o contratista) en la empresa.
Cuando se desea crear una persona de prueba (demo) para conocer el funcionamiento del sistema.

📌 Consideraciones importantes

Permisos y autenticación

Requiere autenticación mediante token JWT (Bearer token).
Usuarios permitidos: administradores y contadores.
Retorna 403 No autorizado si el usuario tiene rol de persona (worker_user).

Suscripción y plan

Requiere que la empresa tenga una suscripción activa.
Retorna 402 Pago requerido si la empresa no tiene suscripción activa.
Retorna 402 Pago requerido si se excede el número máximo de personas del plan contratado.

Información bancaria

Si el método de pago es transferencia (wire_transfer), se requiere banco, número de cuenta y tipo de cuenta.
El número de cuenta debe tener entre 7 y 17 dígitos numéricos.

Trabajador demo

Al crear una persona demo (demo_flag: true), solo se requieren: nombre, apellido, salario base y fecha inicial.
Las personas demo se eliminan automáticamente cuando se crea la primera persona regular.

🛡️ Validaciones

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

❌ Formato de fecha inválido

Se devuelve cuando los campos initial_day o end_day no tienen el formato correcto YYYY-MM-DD (ISO 8601).

Ejemplo de respuesta (fecha inicial inválida):

{
  "error": [
    {
      "message": "El formato de la fecha inicial es inválido.",
      "code": "0409",
      "object": "initial_day",
      "index": 0
    }
  ]
}

Ejemplo de respuesta (fecha final inválida):

{
  "error": [
    {
      "message": "El formato de la fecha final es inválido.",
      "code": "0410",
      "object": "end_day",
      "index": 0
    }
  ]
}

❌ Pensión de alto riesgo sin Colpensiones

Se devuelve cuando se configura high_risk_pension: true pero el fondo de pensiones (pension_provider_id) no corresponde a Colpensiones. Según la Resolución 6072 de 2024, solo Colpensiones puede administrar pensiones de alto riesgo.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "La pensión de alto riesgo requiere Colpensiones como administradora de pensiones (Resolución 6072 de 2024).",
      "code": "4009",
      "object": "contract_detail",
      "index": 0
    }
  ]
}

❌ Nombre o apellido inválido

Se devuelve cuando el campo name o last_name no cumple con las validaciones:

Longitud menor a 3 caracteres o mayor a 30 caracteres
Contiene caracteres no permitidos (scripts, símbolos especiales como <, >, $, \)

Ejemplo de respuesta (muy corto):

{
  "error": [
    {
      "message": "Nombre es demasiado corto (3 caracteres mínimo).",
      "code": "0201",
      "object": "name",
      "index": 0
    }
  ]
}

Ejemplo de respuesta (caracteres inválidos):

{
  "error": [
    {
      "message": "Nombre contiene uno o más de los siguientes caracteres inválidos: '<>$\\'.",
      "code": "0118",
      "object": "name",
      "index": 0
    }
  ]
}

❌ Número de documento duplicado

Se devuelve cuando ya existe otra persona en la misma empresa con el mismo número de documento (id_number).

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Número de identificación ya está en uso.",
      "code": "0003",
      "object": "id_number",
      "index": 0
    }
  ]
}

❌ Fecha de nacimiento inválida

Se devuelve cuando la fecha de nacimiento (birthday) indica que la persona tiene menos de 15 años o más de 100 años.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Cumpleaños es inválido.",
      "code": "0101",
      "object": "birthday",
      "index": 0
    }
  ]
}

❌ Número de cuenta inválido

Se devuelve cuando el número de cuenta bancaria (account_number) no cumple con el formato requerido: debe tener entre 7 y 17 dígitos numéricos.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "El número de cuenta es demasiado corto (7 caracteres mínimo).",
      "code": "0201",
      "object": "account_number",
      "index": 0
    }
  ]
}

❌ Imagen de perfil inválida

Se devuelve cuando el campo picture contiene una imagen en formato no válido. Los formatos permitidos son PNG y JPG codificados en base64.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Foto debe ser una imagen en formato png o jpg.",
      "code": "0307",
      "object": "picture",
      "index": 0
    }
  ]
}

❌ Dirección inválida

Se devuelve cuando el campo address no cumple con la longitud requerida: debe tener entre 5 y 100 caracteres.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Dirección es demasiado corta (5 caracteres mínimo).",
      "code": "0201",
      "object": "address",
      "index": 0
    }
  ]
}

❌ Vacaciones acumuladas fuera de rango

Se devuelve cuando el campo accumulated_holidays está fuera del rango permitido: entre -30 y 90 días.

Ejemplo de respuesta (valor muy bajo):

{
  "error": [
    {
      "message": "Vacaciones acumuladas debe ser mayor o igual a -30.",
      "code": "0305",
      "object": "worker",
      "index": 0
    }
  ]
}

Ejemplo de respuesta (valor muy alto):

{
  "error": [
    {
      "message": "Vacaciones acumuladas debe ser menor o igual a 90.",
      "code": "0303",
      "object": "worker",
      "index": 0
    }
  ]
}