API de Simulación de Nómina

Bienvenido a la Documentación del API de Nómina

Esta documentación te guiará paso a paso en la integración del endpoint de Simulación de Costos de Nómina de Dataemunah, diseñado para calcular costos laborales bajo diferentes escenarios según la legislación colombiana vigente.

Contenido de la Documentación

La documentación está organizada en 4 secciones principales:

1. Introducción

¿Qué encontrarás?

Descripción general del endpoint
Casos de uso y beneficios
Información técnica y requisitos
Componentes de cálculo (devengos, deducciones, aportes, provisiones)
Rendimiento y límites

Recomendado para: Todos los usuarios, especialmente si es tu primera vez usando el API.

2. Parámetros del Request

¿Qué encontrarás?

Estructura completa del request JSON
Detalle de cada parámetro (obligatorios y opcionales)
Validaciones y restricciones
Configuración de escenarios (mejor, peor, promedio)
Manejo de novedades laborales
Porcentajes personalizados

Recomendado para: Desarrolladores que implementarán la integración.

3. Ejemplos de Uso en PHP

¿Qué encontrarás?

Función base reutilizable para peticiones
6 ejemplos completos de código PHP:
1. Cálculo individual básico
2. Proyecto con múltiples empleados
3. Comparación de 3 escenarios
4. Empleado con novedades específicas
5. Porcentajes personalizados (exoneración)
6. Salario integral
Tips de optimización y mejores prácticas
Manejo robusto de errores

Recomendado para: Desarrolladores PHP que buscan implementar rápidamente.

4. Respuestas y Manejo de Errores

¿Qué encontrarás?

Estructura completa de respuestas exitosas
Detalle de cada campo de la respuesta
Códigos de error HTTP y sus soluciones
Ejemplos de procesamiento de respuestas
Mejores prácticas de logging y monitoreo
Información de soporte y changelog

Recomendado para: Todos, especialmente para debugging y mantenimiento.

Inicio Rápido

Paso 1: Obtén tu API Key

Envía un correo a hola@dataemunah.com con:

Nombre de tu empresa
Caso de uso
Instancia de Dataemunah a consultar

Paso 2: Configura tu entorno

define('DATAEMUNAH_HOST', 'https://tu-instancia.dataemunah.com');
define('API_PAYROLL_KEY', 'tu_api_key');
define('NOMINA_ENDPOINT', DATAEMUNAH_HOST . '/api/nomina/calculate');

Paso 3: Haz tu primera petición

$requestData = [
    'periodo' => ['mes' => 1, 'anio' => 2025],
    'nivelCalculo' => 'empleado',
    'escenario' => 'promedio',
    'porcentajeNovedades' => 0,
    'perfiles' => [
        [
            'idEmpleado' => 'EMP001',
            'tipoContrato' => 'indefinido',
            'salarioBasico' => 3000000,
            'tipoSalario' => 'no_integral',
            'diasContratados' => 30,
            'aplicaAuxilioTransporte' => true,
            'nivelRiesgoArl' => 1
        ]
    ]
];

$respuesta = calcularNomina($requestData);

Casos de Uso Comunes

Presupuesto de Proyecto

// Ver ejemplo completo en: Ejemplos → Ejemplo 2
$requestData = [
    'nivelCalculo' => 'proyecto',
    'escenario' => 'promedio',
    'porcentajeNovedades' => 30,
    'perfiles' => [ /* múltiples empleados con idProyecto */ ]
];

Comparación de Escenarios

// Ver ejemplo completo en: Ejemplos → Ejemplo 3
foreach (['mejor', 'promedio', 'peor'] as $escenario) {
    $resultado = calcularNomina([
        'escenario' => $escenario,
        // ... otros parámetros
    ]);
}

Cálculo con Novedades Específicas

// Ver ejemplo completo en: Ejemplos → Ejemplo 4
$perfil = [
    // ... datos básicos
    'novedades' => [
        'horasExtras' => ['diurnas' => 15, 'nocturnas' => 8],
        'bonificaciones' => [
            ['concepto' => 'Productividad', 'tipo' => 'salarial', 'monto' => 600000]
        ]
    ]
];

Datos Importantes

Límites del Sistema

Máximo perfiles por petición: 1,000
Tiempo promedio (1000 perfiles): 3-4 segundos
Tiempo máximo observado: 8.4 segundos
Rate limiting: Sin límite de peticiones

Valores Vigentes 2025

SMMLV: $1,423,500
Auxilio de Transporte: $200,000
UVT: $47,065
Límite Auxilio Transporte: $2,847,000 (2 SMMLV)
Salario Integral mínimo: $18,505,500 (13 SMMLV)

Porcentajes Legales

Concepto	Porcentaje
Salud empleado	4%
Salud empleador	8.5%
Pensión empleado	4%
Pensión empleador	12%
ARL	0.522% - 6.96%
SENA	2%
ICBF	3%
Caja Compensación	4%

Aspectos Importantes

Autenticación

Host Variable

Timeout

Soporte

¿Necesitas Ayuda?

Email de soporte general:
📧 hola@dataemunah.com

Para solicitar API Key:
📧 hola@dataemunah.com (incluye: empresa, caso de uso, instancia)

Líder técnico:
👤 Consulta con tu líder técnico asignado para:

Problemas técnicos específicos
Configuración de instancia
Preguntas sobre tu API Key

Información al Reportar Problemas

Incluye siempre:

Código HTTP de respuesta
Timestamp de la petición
Cantidad de perfiles
Escenario usado
Mensaje de error completo

No incluyas:

Tu API Key
Datos sensibles de empleados

Glosario Rápido

Término	Significado
SMMLV	Salario Mínimo Mensual Legal Vigente
UVT	Unidad de Valor Tributario
IBC	Ingreso Base de Cotización (base para seguridad social)
ARL	Administradora de Riesgos Laborales
Parafiscales	SENA, ICBF y Caja de Compensación
Provisiones	Cesantías, prima, vacaciones (pagos futuros)
Salario Integral	Salario ≥ 13 SMMLV que incluye prestaciones

Versiones del API

Versión Actual: v1.1 (Octubre 2025)

Novedades v1.1

Parámetro porcentajeNovedades para escenario promedio
Estadísticas detalladas de novedades
Campo informativo nota según escenario
Contador de empleados con novedades por proyecto

Próximas Funcionalidades (Roadmap)

Cálculo de nómina quincenal
Soporte para múltiples periodos (proyecciones)
Exportación a PDF/Excel
Webhooks para notificaciones

Recursos Adicionales

Enlaces Útiles

Licencia y Términos de Uso

El uso de este API está sujeto a:

Términos y condiciones de Dataemunah
Acuerdo de confidencialidad de datos
Políticas de uso aceptable

Consulta con tu líder técnico para más información sobre licenciamiento.