Parámetros del Request

Estructura General del Request

El request debe enviarse en formato JSON en el body de la petición POST:

{
  "periodo": { ... },
  "nivelCalculo": "empleado|proyecto",
  "escenario": "mejor|peor|promedio",
  "porcentajeNovedades": 0-100,
  "porcentajesPersonalizados": { ... },
  "perfiles": [ ... ]
}

---

Parámetros Principales

1. periodo (Obligatorio)

Define el mes y año para el cual se calculará la nómina.

Campo	Tipo	Requerido	Descripción	Ejemplo
mes	number	Sí	Mes del cálculo (1-12)	1
anio	number	Sí	Año del cálculo (≥ 2025)	2025

Ejemplo:

"periodo": {
  "mes": 1,
  "anio": 2025
}

Validación de Periodo

• El mes debe estar entre 1 y 12
• El año debe ser mayor o igual a 2025
• El sistema utiliza el año para cargar los valores correctos de SMMLV, UVT y auxilio de transporte

---

2. nivelCalculo (Obligatorio)

Define el nivel de agregación de los resultados.

Valor	Descripción
empleado	Retorna cálculos individuales por cada empleado
proyecto	Agrupa resultados por proyecto y genera totales por proyecto

Ejemplo:

"nivelCalculo": "proyecto"

¿Cuándo usar cada nivel?

• empleado: Usa este nivel cuando necesites el detalle individual de cada persona, ideal para nóminas pequeñas o análisis específicos por empleado.
• proyecto: Usa este nivel para presupuestos y análisis por proyecto. Los resultados incluirán subtotales por cada idProyecto además del detalle individual.

---

3. escenario (Obligatorio)

Define el tipo de simulación que deseas realizar.

Valor	Descripción	Uso Recomendado
mejor	Mínimo costo: Solo salario base con posibles ausentismos (incapacidades, licencias, suspensiones)	Presupuesto optimista
peor	Máximo costo: Incluye máximo de horas extras, recargos y bonificaciones permitidos legalmente	Presupuesto pesimista o worst-case
promedio	Costo realista: Escenario intermedio configurable mediante porcentajeNovedades	Presupuesto más probable

Ejemplo:

"escenario": "promedio"

Comportamiento por Escenario

Escenario MEJOR:

• Solo salario base y prestaciones normales
• Puede incluir aleatoriamente: incapacidad (5-10 días), suspensión (3-7 días) o licencia no remunerada (2-5 días)
• Ignora el parámetro porcentajeNovedades

Escenario PEOR:

• Máximo legal de horas extras mensuales (48 horas, distribuidas en 4 tipos)
• Máximo de recargos (40 horas mensuales en 3 tipos)
• Bonificaciones altas (20% salarial + 20% no salarial del salario base)
• Ignora el parámetro porcentajeNovedades

Escenario PROMEDIO:

• Respeta el parámetro porcentajeNovedades
• Cantidad y tipos de novedades variables según probabilidades
• Simula condiciones laborales normales

---

4. porcentajeNovedades (Opcional)

Controla la aplicación de novedades solo en escenario promedio.

Tipo	Rango	Default	Descripción
number	0-100	0	Porcentaje de intensidad o cobertura de novedades

Comportamiento según nivelCalculo:

Con nivelCalculo: "empleado"

El porcentaje controla la intensidad de las novedades del empleado individual:

• 0%: Sin novedades
• 50%: Mitad de probabilidades y cantidades de novedades
• 100%: Probabilidades y cantidades normales

Ejemplo:

{
  "nivelCalculo": "empleado",
  "escenario": "promedio",
  "porcentajeNovedades": 50
}

Con 50%, si normalmente se generarían 10-15 horas extras, se generarán 5-8 horas.

Con nivelCalculo: "proyecto"

El porcentaje controla cuántos empleados del proyecto tendrán novedades:

• 0%: Ningún empleado tiene novedades
• 30%: Aproximadamente 30% de empleados tendrán novedades
• 100%: Todos los empleados pueden tener novedades

Ejemplo:

{
  "nivelCalculo": "proyecto",
  "escenario": "promedio",
  "porcentajeNovedades": 30,
  "perfiles": [ /* 10 empleados */ ]
}

Resultado: ~3 empleados tendrán novedades aleatorias, 7 solo tendrán salario base.

Solo para Escenario Promedio

Los escenarios mejor y peor ignoran este parámetro. Si lo envías con esos escenarios, será ignorado silenciosamente (el endpoint funcionará pero no tendrá efecto).

---

5. porcentajesPersonalizados (Opcional)

Permite sobrescribir los porcentajes legales por defecto. Útil para empresas con convenios especiales.

Campo	Tipo	Default	Descripción
saludEmpleado	number	4.0	% Salud empleado
saludEmpleador	number	8.5	% Salud empleador
pensionEmpleado	number	4.0	% Pensión empleado
pensionEmpleador	number	12.0	% Pensión empleador
sena	number	2.0	% SENA
icbf	number	3.0	% ICBF
cajaCompensacion	number	4.0	% Caja de Compensación
cesantias	number	8.33	% Cesantías
interesesCesantias	number	1.0	% Intereses cesantías
primaServicios	number	8.33	% Prima de servicios
vacaciones	number	4.17	% Vacaciones

Formato: Los porcentajes se envían como decimales (ej: 4% = 0.04)

Ejemplo:

"porcentajesPersonalizados": {
  "saludEmpleado": 0.04,
  "saludEmpleador": 0.085,
  "pensionEmpleado": 0.04,
  "pensionEmpleador": 0.12,
  "sena": 0.02,
  "icbf": 0.03,
  "cajaCompensacion": 0.04,
  "cesantias": 0.0833,
  "interesesCesantias": 0.01,
  "primaServicios": 0.0833,
  "vacaciones": 0.0417
}

¿Cuándo usar porcentajes personalizados?

• Empresas con exoneración de parafiscales (envía sena: 0, icbf: 0)
• Convenios especiales con EPS o fondos de pensiones
• Regímenes especiales autorizados por el Ministerio del Trabajo
• Para omitir algún componente específico en la simulación

Si no envías este parámetro, se usan los porcentajes legales vigentes para el año actual.

---

Parámetro perfiles (Obligatorio)

Array de objetos con la información de cada empleado a calcular.

Límites:

• Mínimo: 1 perfil
• Máximo: 1,000 perfiles por petición

Estructura de cada perfil

{
  "idEmpleado": "EMP001",
  "idProyecto": "PROY001",
  "tipoContrato": "indefinido",
  "salarioBasico": 3000000,
  "tipoSalario": "no_integral",
  "diasContratados": 30,
  "porcentajeJornada": 100,
  "aplicaAuxilioTransporte": true,
  "nivelRiesgoArl": 1,
  "novedades": { ... }
}

Campos del perfil

Campo	Tipo	Requerido	Descripción	Ejemplo
idEmpleado	string	Sí	Identificador único del empleado	"EMP001"
idProyecto	string	No	Identificador del proyecto (solo para nivelCalculo: "proyecto")	"PROY001"
tipoContrato	string	Sí	Tipo de contrato: termino_fijo, indefinido, obra_labor, prestacion_servicios	"indefinido"
salarioBasico	number	Sí	Salario mensual básico en COP (≥ SMMLV proporcional)	3000000
tipoSalario	string	Sí	Tipo de salario: integral o no_integral	"no_integral"
diasContratados	number	Sí	Días contratados en el mes (1-30)	30
porcentajeJornada	number	No	Porcentaje de jornada laboral (1-100). Default: 100	100
aplicaAuxilioTransporte	boolean	No	Si aplica auxilio de transporte. Default: true	true
nivelRiesgoArl	number	No	Nivel de riesgo ARL (1-5). Default: 1	1
novedades	object	No	Novedades específicas del empleado (ver sección siguiente)	{}

Validaciones Importantes

• El salarioBasico debe ser ≥ al SMMLV 2025 (COP $1,423,500) si porcentajeJornada es 100%
• Para jornadas parciales, el salario mínimo se calcula proporcionalmente
• El salario integral debe ser ≥ 13 SMMLV (aprox. COP $18,505,500 para 2025)
• El auxilio de transporte solo aplica si el salario básico es < 2 SMMLV (COP $2,847,000)

---

Objeto novedades (Opcional)

Permite especificar novedades laborales concretas para un empleado. Estas novedades tienen prioridad sobre las simuladas por el escenario.

"novedades": {
  "horasExtras": { ... },
  "recargos": { ... },
  "bonificaciones": [ ... ],
  "incapacidad": { ... },
  "licencia": { ... },
  "suspension": { ... }
}

1. Horas Extras

"horasExtras": {
  "diurnas": 10,
  "nocturnas": 5,
  "diurnasFestivas": 2,
  "nocturnasFestivas": 1
}

Campo	Recargo	Descripción
diurnas	125%	Horas extras diurnas ordinarias (6am-10pm)
nocturnas	175%	Horas extras nocturnas (10pm-6am)
diurnasFestivas	205%	Horas extras diurnas en festivos/dominicales
nocturnasFestivas	255%	Horas extras nocturnas en festivos/dominicales

Límites Legales de Horas Extras

• Máximo 2 horas extras diarias
• Máximo 12 horas extras semanales
• El sistema validará que no excedas ~48 horas extras mensuales por tipo

2. Recargos

"recargos": {
  "nocturno": 20,
  "dominicalFestivoDiurno": 8,
  "dominicalFestivoNocturno": 4
}

Campo	Recargo	Descripción
nocturno	35%	Trabajo ordinario nocturno (10pm-6am)
dominicalFestivoDiurno	180%	Trabajo dominical/festivo diurno (6am-10pm)
dominicalFestivoNocturno	215%	Trabajo dominical/festivo nocturno (10pm-6am)

3. Bonificaciones

"bonificaciones": [
  {
    "concepto": "Bonificación por productividad",
    "tipo": "salarial",
    "monto": 500000
  },
  {
    "concepto": "Auxilio de alimentación",
    "tipo": "no_salarial",
    "monto": 300000
  }
]

Campo	Tipo	Descripción
concepto	string	Descripción de la bonificación
tipo	string	salarial (impacta IBC) o no_salarial
monto	number	Valor en COP

Diferencia entre tipos de bonificación

• Salarial: Se suma al IBC para calcular seguridad social y provisiones (aumenta el costo total)
• No salarial: No impacta IBC, solo se suma al total de devengos (menor costo)

4. Incapacidad

"incapacidad": {
  "dias": 5,
  "tipo": "eps"
}

Campo	Valores	Descripción
dias	1-30	Cantidad de días de incapacidad
tipo	eps o arl	Origen de la incapacidad

Pago según tipo:

• EPS (Común): Empresa paga 100% primeros 2 días, EPS paga 66.67% desde día 3
• ARL (Laboral): ARL paga 100% desde día 1

5. Licencia

"licencia": {
  "tipo": "no_remunerada",
  "dias": 3
}

Tipo	Días	Descripción
maternidad	Auto	18 semanas (requiere fechaInicio)
paternidad	Auto	14 días
luto	Auto	5 días
calamidad	Variable	Días según autorización
no_remunerada	Variable	Sin pago, reduce salario

6. Suspensión

"suspension": {
  "dias": 2,
  "tipo": "disciplinaria"
}

Campo	Valores	Descripción
dias	1-30	Días de suspensión
tipo	disciplinaria o administrativa	Tipo de suspensión

Validación de Coherencia

El sistema valida que la suma de días de novedades (incapacidad + licencia + suspensión) no exceda 30 días mensuales.

Además, no puedes tener simultáneamente:

• Incapacidad + Suspensión
• Licencia + Suspensión

---

Siguiente: Ejemplos de Uso

En la siguiente sección encontrarás ejemplos completos de código PHP para consumir el endpoint en diferentes escenarios.