🔍 ¿Qué hace este endpoint?

Registra una nueva persona en una empresa. En una única solicitud es posible crear los datos personales de la persona junto con su contrato, salario, detalle de contrato, historial de posición (sede, área, cargo) y el usuario de acceso a la plataforma.

Al crear una persona regular, el sistema también elimina automáticamente las personas de prueba (demo_flag: true) que pudiera tener la empresa, dado que las personas de prueba son reemplazadas por personas reales.

Si se envía demo_flag: true, el sistema crea una persona de prueba con datos generados automáticamente y genera nóminas para los períodos del mes actual, lo que permite demostrar el funcionamiento de la plataforma sin datos reales.

🎯 ¿Cuándo usar este endpoint?

Vincular una nueva persona a la empresa: Cuando se contrata a alguien nuevo y se necesita registrarlo con su contrato, salario, cargo y sede en un solo paso.
Crear una persona con acceso a la plataforma: Enviando los campos email y active_user dentro del objeto worker para crear simultáneamente el usuario de acceso.

📌 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 crear 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.

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.

Datos adicionales a tener en cuenta:

Los parámetros del contrato, salario, detalle de contrato e historial de posición se envían todos dentro del objeto worker en el cuerpo de la solicitud (no hay objetos separados).
Si no se envían parámetros de contrato (category, initial_day, etc.), la persona se crea sin contrato y con finish_registration: false.
El campo email dentro de worker crea un usuario de acceso vinculado a la persona. Si ya existe un usuario con ese correo en la plataforma, se asocia.
El campo picture debe enviarse como un hash con los datos del archivo adjunto de Active Storage (no como Base64).

🛡️ 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 en blanco o muy corto/largo

Ocurre cuando name está vacío, tiene menos de 3 caracteres o más de 30 caracteres. Verifica que el nombre tenga entre 3 y 30 caracteres.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Nombre no puede estar en blanco.",
      "code": "0002",
      "object": "name",
      "index": 0
    }
  ]
}

❌ Nombre con caracteres inválidos

Ocurre cuando name contiene caracteres no permitidos. El nombre solo puede contener letras, números, apóstrofes, puntos, guiones y espacios. No puede contener <, >, $, ni \.

Ejemplo de respuesta:

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

❌ Apellido en blanco o muy corto/largo

Ocurre cuando last_name está vacío, tiene menos de 3 caracteres o más de 30 caracteres. Las mismas reglas aplican para caracteres inválidos que en el nombre.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Apellido no puede estar en blanco.",
      "code": "0002",
      "object": "last_name",
      "index": 0
    }
  ]
}

❌ Número de documento en blanco o con longitud inválida

Ocurre cuando id_number está vacío o tiene menos de 4 o más de 15 caracteres (para documentos pt/pt_no_pension el rango es 6..8). Verifica que el número de documento esté dentro del rango permitido para el tipo de documento.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Número de documento no puede estar en blanco.",
      "code": "0002",
      "object": "id_number",
      "index": 0
    }
  ]
}

❌ Número de documento duplicado

Ocurre cuando ya existe otra persona en la misma empresa con el mismo id_number. El número de documento debe ser único dentro de la empresa.

Ejemplo de respuesta:

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

❌ Fecha de nacimiento inválida

Ocurre cuando birthday corresponde a una persona menor de 14 años. La persona debe tener al menos 14 años de edad.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Fecha de nacimiento es inválido.",
      "code": "0101",
      "object": "birthday",
      "index": 0
    }
  ]
}

❌ Dirección con longitud o formato inválido

Ocurre cuando address tiene menos de 5 o más de 100 caracteres, contiene caracteres no permitidos (<>$\) o no cumple el formato de dirección válida.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Dirección es inválido.",
      "code": "0101",
      "object": "address",
      "index": 0
    }
  ]
}

❌ Número de cuenta inválido

Ocurre cuando se envía account_number pero no tiene entre 7 y 17 dígitos numéricos. Solo aplica cuando se envía el campo account_number.

Ejemplo de respuesta:

{
  "error": [
    {
      "message": "Número de cuenta es inválido. Este debe ser un número.",
      "code": "0101",
      "object": "account_number",
      "index": 0
    }
  ]
}

✅ Respuesta exitosa

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "active": true,
    "name": "Laura",
    "last_name": "Martínez",
    "picture": null,
    "payroll_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "affiliation_id": null,
    "document_type": "cc",
    "id_number": "1023456789",
    "email": "laura.martinez@empresa.ejemplo.com",
    "active_user": true,
    "phone": null,
    "address": null,
    "recurrent_concepts_incomes_total": 0,
    "recurrent_concepts_deductions_total": 0,
    "city_address": { "id": null, "name": null },
    "department_address": { "id": null, "name": null },
    "birthday": null,
    "payment_method": null,
    "pension_reform_2381_transition_regime": false,
    "bank": { "id": null, "name": null },
    "account_number": null,
    "account_type": null,
    "accumulated_holidays": 0.0,
    "rest_days": ["0"],
    "terminatable": false,
    "deleteable": true,
    "demo_flag": false,
    "multiple_contracts": false,
    "finish_registration": true,
    "finish_onboarding": false,
    "finish_onboarding_at": null,
    "retention_configuration": false,
    "payroll_retention": false,
    "city": "Bogotá D.C.",
    "department": "Cundinamarca",
    "area": { "id": "e6f7a8b9-c0d1-2345-efab-678901234567", "name": "Tecnología" },
    "compensation_fund": { "id": "a4b5c6d7-e8f9-0123-abcd-456789012345", "name": "Compensar" },
    "cost_center": { "id": "b5c6d7e8-f9a0-1234-bcda-567890123456", "name": "Centro de costos principal" },
    "location": { "id": "f7a8b9c0-d1e2-3456-fabc-789012345678", "name": "Bogotá" },
    "position": { "id": "a8b9c0d1-e2f3-4567-abcd-890123456789", "name": "Desarrolladora de software" },
    "social_security_branch": { "id": null, "name": null }
  }
}