🔍 ¿Qué hace este endpoint?

Este endpoint permite gestionar de forma masiva los conceptos recurrentes asociados a una persona, entendidos como valores periódicos que impactan automáticamente cada período de nómina.

Mediante una única solicitud, el sistema recibe un conjunto de conceptos y define de forma explícita la acción a ejecutar sobre cada uno —crear, actualizar o eliminar— con base en la información enviada. Estos conceptos corresponden a ingresos salariales, ingresos no salariales y deducciones, los cuales inciden directamente en el cálculo y la liquidación de la nómina.

Una vez finalizado el procesamiento, el sistema recalcula automáticamente los conceptos recurrentes de la persona para el período de nómina vigente, garantizando que los ajustes realizados se reflejen de forma inmediata y consistente en la nómina.

🎯 ¿Cuándo usar este endpoint?

Configurar conceptos recurrentes iniciales: Al vincular a una persona a la empresa, cuando necesita conceptos de nómina que se aplicarán de forma recurrente (por ejemplo, bonos, descuentos, préstamos, auxilios, entre otros).
Actualizar valores de conceptos existentes: Cuando cambian los montos de conceptos recurrentes (aumentos, ajustes salariales, cambios en descuentos o préstamos).
Activar o desactivar conceptos según el período: Para habilitar o pausar conceptos según necesidades temporales, sin eliminarlos.
Eliminar conceptos que ya no aplican: Cuando un concepto recurrente deja de ser necesario para la persona (por ejemplo, finalización de un préstamo o eliminación de una bonificación).
Realizar ajustes masivos en un solo proceso: Para crear, actualizar y eliminar múltiples conceptos en una sola operación, útil al hacer cambios masivos o al configurar varios conceptos a la vez.
Cambiar el tipo de cálculo de un concepto: Para modificar si un concepto se calcula de forma proporcional o con valor fijo, según cambios en el contrato o políticas de la empresa.
Controlar en qué quincenas o períodos se aplica un concepto: Para definir en qué quincenas o períodos se aplica un concepto recurrente. Útil cuando un concepto debe aplicarse solo en la primera quincena (por ejemplo, una bonificación que se paga al inicio del mes), solo en la segunda quincena (por ejemplo, un descuento que se aplica a mitad de mes) o en ambas quincenas distribuyendo el valor mensual. En empresas con pago mensual, el concepto se aplica en todos los períodos mensuales. Esto permite controlar cuándo se calcula y liquida cada concepto en la nómina de la persona, según las políticas de la empresa o acuerdos específicos.

📌 Consideraciones importantes

Permisos y autenticación

Debes estar autenticado en el sistema y tener acceso activo a la empresa para gestionar conceptos recurrentes de las personas.
Debes tener permisos de edición en la empresa; si solo tienes permisos de lectura, recibirás un error 403 No autorizado.
La empresa debe tener una suscripción activa. Si la suscripción está inactiva, vencida o pendiente de pago, recibirás un error 402 Pago requerido indicando que se requiere pago para realizar esta operación.
Solo puedes gestionar conceptos recurrentes de personas que pertenezcan a empresas a las que tengas acceso. Si intentas acceder a una persona de otra empresa, recibirás un error 404 Concepto recurrente no existe.

Variaciones en la respuesta:

Estructura de respuesta exitosa (202 Accepted): La respuesta incluye solo los conceptos que fueron creados o actualizados en la operación. Los conceptos eliminados no aparecen en la respuesta.

Ejemplo 1: Respuesta con conceptos creados y actualizados

{
  "data": [
      {
          "id": "eb7431c2-ef12-433d-ae98-5eef6aa6d5dd",
          "active": true,
          "balance": 500000,
          "concept_type": "proportional",
          "deleteable": true,
          "monthly_value": 200000,
          "period_apply": "second_fortnightly",
          "value": 500000,
          "payroll_concept": {
              "id": "fb87b7ea-f263-497e-86de-ea43e6ab75e1",
              "name": "aporte institucional empleado"
            }
        }
    ]
}

Ejemplo 2: Respuesta cuando solo se eliminan conceptos Si en la operación solo se eliminan conceptos (sin crear ni actualizar), el array data estará vacío:

{
  "data": []
}

🛡️ Validaciones

Ejemplo de respuesta:

Si la persona no existe o no pertenece a la empresa, recibirás un error 404 Persona no existe.

{
    "error": [
        {
            "message": "Persona no existe",
            "code": "0001",
            "object": "worker",
            "index": 0
        }
    ]
}

Solo puedes modificar conceptos recurrentes que pertenezcan a la persona especificada. Si intentas actualizar o eliminar un concepto que no corresponde a esa persona, recibirás un error 404 Concepto recurrente no existe indicando el concepto que no se encontró.

{
  "error": [
      {
          "message": "Concepto recurrente no existe",
          "code": "0001",
          "object": "recurrent_concept",
          "index": 0
        }
    ]
}

Si intentas crear un concepto recurrente para una persona y esta ya tiene otro concepto recurrente con el mismo concepto de nómina, recibirás un error 422 Contenido no procesable.

{
  "error": [
      {
          "message": "Concepto de nómina ya está en uso",
          "code": "0003",
          "object": "payroll_concept",
          "index": 0
        }
    ]
}

Debes enviar al menos un concepto recurrente en la solicitud. Si el listado de conceptos está vacío o no se envía, recibirás un error 422 Contenido no procesable.

{
  "error": [
      {
          "message": "Los datos enviados son inválidos.",
          "code": "0102",
          "object": "request",
          "index": 0
        }
    ]
}

Para personas con contrato de tiempo parcial, no puedes crear o actualizar deducciones con valor fijo. Solo se permiten deducciones con cálculo proporcional. Si intentas agregar una deducción con valor fijo a una persona con contrato de tiempo parcial, recibirás un error 422 Contenido no procesable.

{
  "error": [
      {
          "message": "Al contrato tiempo parcial no se le puede agregar una deducción con valor fijo.",
          "code": "5501",
          "object": "recurrent_concept",
          "index": 0
        }
    ]
}

Si la persona tiene retención en la fuente automática activa, no puedes crear o activar un concepto recurrente de retención en la fuente. Si intentas activarlo, recibirás un error 422 Contenido no procesable

{
  "error": [
    {
      "message": "No puedes activar un concepto recurrente de retención en la fuente porque tienes la retención en la fuente automática activa.",
      "code": "5506",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}

Si defines un valor total para el concepto recurrente, este no puede ser menor al monto ya pagado. Si intentas establecer un valor menor al ya pagado, recibirás un error 422 Contenido no procesable .

{
  "error": [
    {
      "message": "El valor no puede ser menor al total pagado por el concepto recurrente.",
      "code": "5503",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}

No puedes activar un concepto recurrente que ya fue pagado en su totalidad. Si intentas activarlo cuando el balance es cero, recibirás un error 422 Contenido no procesable .

{
  "error": [
    {
      "message": "No puedes activar este concepto recurrente porque ya se pagó en su totalidad",
      "code": "5502",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}

En empresas con período de pago mensual, los conceptos recurrentes solo pueden aplicarse en todos los períodos. No puedes configurar que se apliquen solo en la primera o segunda quincena. Si intentas hacerlo, recibirás un error 422 Contenido no procesable.

{
  "error": [
    {
      "message": "No es posible escoger el periodo de aplicación si la empresa es mensual",
      "code": "5504",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}

Para conceptos con cálculo proporcional, no puedes configurar que se apliquen solo en la primera quincena. Solo puedes configurarlos para que se apliquen en todos los períodos o solo en la segunda quincena. Si intentas configurarlo para la primera quincena, si intentas hacerlo, recibirás un error 422 Contenido no procesable.

{
  "error": [
    {
      "message": "El periodo de aplicación no puede ser la primera quincena si el concepto es proporcional",
      "code": "5505",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}

Solo puedes eliminar un concepto recurrente si no tiene registros de pago en nóminas anteriores, o si solo tiene registros en el período actual con valor cero. Si intentas eliminar un concepto que ya tiene pagos registrados en períodos anteriores, recibirás un error 422 Contenido no procesable, indicando que el concepto no puede ser eliminado.

{
  "error": [
    {
      "message": "Concepto recurrente no se puede eliminar",
      "code": "5501",
      "object": "recurrent_concept",
      "index": 0
    }
  ]
}