Nómina electrónica DIAN: integración API paso a paso
La nómina electrónica en Colombia no es un PDF con los pagos de tus empleados — es un documento XML firmado que la DIAN valida antes de que tenga validez tributaria para el trabajador y para la empresa. Los sistemas de nómina que generan PDFs o archivos planos deben agregar una capa de integración para producir, firmar y enviar ese XML correctamente.
Esta guía cubre el proceso técnico completo: habilitación ante la DIAN, cálculo del CUNE, estructura del documento soporte de pago (IndNom), firma digital, envío vía API y consideraciones de producción. Audiencia: desarrolladores integrando un sistema de nómina con el servicio de recepción de la DIAN.
Prerrequisitos
- NIT del empleador activo en el RUT de la DIAN
- Certificado digital vigente para firma electrónica (entidad certificadora autorizada por la DIAN)
- Habilitación en el portal de la DIAN para emisión de documentos soporte de pago (IndNom)
- Software de nómina o sistema de RRHH que exporte los datos de pago por empleado
- Ambiente de pruebas DIAN habilitado: https://vpfe-hab.dian.gov.co/
Proceso de habilitación ante la DIAN
Antes de enviar el primer documento de nómina electrónica, la empresa debe habilitarse en el portal de la DIAN. El proceso tiene cuatro pasos:
- Registrar el software de nómina en el portal de la DIAN (Resolución DIAN 0013 de 2021)
- Obtener el
TestSetIddel set de pruebas asignado por la DIAN - Enviar los documentos de prueba correctamente: la DIAN asigna un set de 10–30 casos de prueba
- Solicitar la habilitación definitiva una vez superados los casos de prueba
El proceso de habilitación toma en promedio 5 días hábiles una vez enviados los documentos de prueba con resultado exitoso.
La habilitación para nómina electrónica es independiente de la habilitación para factura electrónica. Una empresa que ya factura electrónicamente debe igualmente completar el proceso de habilitación específico para el IndNom. El Software ID que se registra para nómina puede ser diferente al de facturación.
Cálculo del CUNE
El CUNE (Código Único de Nómina Electrónica) es el identificador único del documento soporte de pago. Se calcula como el hash SHA-384 de la concatenación de campos específicos del documento, en este orden exacto:
| Campo | Descripción | Formato requerido |
|---|---|---|
| Numero | Número consecutivo del documento | String tal como aparece en el XML |
| FechaGen | Fecha y hora de generación | YYYY-MM-DDTHH:mm:ss |
| FechaInicioPago | Inicio del período de pago | YYYY-MM-DD |
| FechaFinPago | Fin del período de pago | YYYY-MM-DD |
| FechaPago | Fecha real del pago al trabajador | YYYY-MM-DD |
| DevengadoTotal | Total de devengados del empleado | Decimal con 2 cifras, punto decimal |
| DeduccionTotal | Total de deducciones del empleado | Decimal con 2 cifras, punto decimal |
| ComprobanteTotal | Neto a pagar (Devengado – Deducción) | Decimal con 2 cifras, punto decimal |
| NitNE | NIT del empleador sin dígito de verificación | Solo dígitos |
| DocEmp | Número de documento del empleado | Solo dígitos |
| TipoXML | Tipo de documento (IndNom = 1) | Integer como string |
| ClaveT | Clave técnica asignada por la DIAN al software | String exacto sin modificar |
Nota: El código funcional de cálculo del CUNE está disponible en la documentación técnica de Alanube.
⚠️ Nota normativa: El orden de concatenación de los campos es determinístico y debe respetarse exactamente. Un campo fuera de orden produce un CUNE inválido que la DIAN rechazará con error 89 (CUNE no corresponde).
Estructura del documento IndNom (XML): devengados y deducciones
El documento soporte de pago de nómina electrónica (IndNom) es un XML con namespace UBL 2.1 adaptado por la DIAN. A diferencia de la factura electrónica, el IndNom tiene una estructura centrada en los conceptos de nómina de cada trabajador. Los nodos principales son Devengados y Deducciones.
| Concepto | Tipo | Nodo XML | Obligatorio |
|---|---|---|---|
| Salario básico mensual | Devengado | Basico | Sí |
| Auxilio de transporte | Devengado | AuxTransporte | No (aplica si salario ≤ 2 SMLMV) |
| Horas extras diurnas | Devengado | HEDs | No |
| Horas extras nocturnas | Devengado | HENs | No |
| Comisiones | Devengado | Comisiones | No |
| Vacaciones disfrutadas | Devengado | Vacaciones.VacacionesComunes | No |
| Aportes a salud (empleado) | Deducción | Salud.PorcentajeS | Sí |
| Aportes a pensión (empleado) | Deducción | FondoPension.PorcentajeP | Sí |
| Retención en la fuente | Deducción | Retencion | No (si aplica) |
Los nodos de devengados y deducciones se agrupan dentro del nodo del trabajador (Trabajador). Si hay varios conceptos del mismo tipo (por ejemplo, múltiples horas extras en un período), cada uno se representa como un elemento hijo dentro de su nodo correspondiente.
Envío del documento al servicio de recepción de la DIAN
El envío se realiza mediante un servicio SOAP usando el método SendNominaIndicativa del WSDL de la DIAN. El XML del IndNom debe ir comprimido en ZIP y codificado en Base64 dentro del body del request SOAP. El endpoint de habilitación es https://vpfe-hab.dian.gov.co/WcfDianCustomerServices.svc.
Nota: El código funcional de envío SOAP está disponible en la documentación técnica de Alanube.
💡 Con Alanube: La API de Alanube Colombia transforma el payload JSON de nómina al formato XML UBL requerido por la DIAN, calcula el CUNE, firma el documento y gestiona la comunicación SOAP — en un único POST /payroll.
Notas de ajuste de nómina electrónica
Cuando un documento IndNom ya enviado y validado por la DIAN contiene un error (montos incorrectos, período equivocado, empleado incorrecto), no se puede modificar el documento original. En su lugar, se debe emitir un documento de ajuste, que es el equivalente a una nota crédito en el ecosistema de factura electrónica.
El documento de ajuste referencia el CUNE del IndNom original en el campo CUNENov y describe la diferencia entre los valores originales y los correctos. Los tipos de ajuste son:
- Ajuste de eliminación (TipoNota = 1): Anula completamente el documento original. Se usa cuando el documento fue emitido por error (empleado equivocado, período duplicado).
- Ajuste de modificación (TipoNota = 2): Reemplaza los valores del documento original con valores correctos. Se usa cuando los montos o conceptos están incorrectos pero el documento corresponde al empleado y período correcto.
El plazo para emitir el ajuste es el mismo que para el documento original: dentro de los 60 días calendario siguientes a la fecha de pago. Pasado ese plazo, el empleador pierde la deducción sobre los montos originales y no puede corregirlos retroactivamente.
Integración con ERP y sistemas de nómina legados
La mayoría de los ERPs y sistemas de nómina en Colombia no generan el XML IndNom nativamente — solo producen el cálculo de nómina en formato propietario (archivos planos, CSV o tablas de base de datos). La integración típica tiene dos capas:
- Capa de extracción: Un proceso extrae los datos de nómina del ERP (devengados, deducciones, datos del trabajador, período) y los convierte a un formato intermedio estructurado (JSON o XML interno).
- Capa de integración fiscal: Un servicio recibe ese JSON, construye el XML IndNom, calcula el CUNE, aplica la firma digital XAdES-BES y envía a la DIAN.
Para SAP HCM, el punto de extracción natural es el informe de nómina procesada (transacción PC_PAYRESULT). Para Oracle HCM Cloud, los datos de payroll procesados se extraen vía REST API del módulo de Compensación. Para sistemas legados en AS/400 o mainframe, la extracción suele hacerse sobre los archivos de pago generados para el banco.
El cuello de botella más común en esta arquitectura es la sincronización de maestros: el sistema de nómina puede tener el tipo de contrato, la fecha de ingreso o el tipo de documento del trabajador desactualizado respecto a lo registrado en la DIAN. Cualquier discrepancia en el TipoDocumento o el NumeroDocumento del empleado produce rechazo del documento.
Consideraciones de producción
Antes de ir a producción con la integración de nómina electrónica, verificar los siguientes puntos:
- Certificado de producción: El certificado usado en pruebas es diferente al de producción. El certificado de producción debe ser emitido por una entidad certificadora autorizada por la ONAC y la DIAN.
- Gestión de consecutivos: Los números de los IndNom en producción deben ser secuenciales y únicos dentro del Software ID. Un gap o duplicado en la secuencia puede bloquear envíos posteriores.
- Manejo de reintentos: Si el servicio SOAP de la DIAN devuelve un timeout o error 5xx, el sistema debe reintentar el envío. Sin embargo, si el documento ya fue procesado por la DIAN (aunque el ACK no llegó), un reintento puede producir un duplicado. La estrategia correcta es consultar el estado del CUNE antes de reintentar.
- Zona horaria: Todos los campos de fecha y hora deben estar en zona horaria UTC-5 (Colombia). Un documento generado con hora UTC produce diferencias en el CUNE.
Errores comunes en la integración de nómina electrónica
Error: Regla: 89 — CUNE no corresponde al documento
Causa: El CUNE calculado no coincide con el que la DIAN recalcula del XML. Generalmente por diferencias de formato en los valores numéricos (separadores de miles, decimales).
Solución: Los campos numéricos en la cadena de CUNE deben tener exactamente 2 decimales, sin separadores de miles, usando punto como separador decimal.
Error: Regla: 172 — FechaGen fuera del período permitido
Causa: La nómina se intenta enviar con una FechaGen posterior a 60 días desde el fin del período de pago.
Solución: Asegurar que el documento se envía dentro de los 60 días calendario siguientes a la fecha de pago según la Resolución DIAN 0013 de 2021.
Error: Regla: 264 — NIT del proveedor no habilitado
Causa: El Software ID no está asociado al NIT del empleador en el sistema de la DIAN.
Solución: Verificar en el portal de la DIAN que el Software ID está correctamente vinculado al NIT del empleador y que la habilitación fue aprobada.
Error: Regla: 306 — TipoDocumento del trabajador no válido
Causa: El tipo de documento del empleado en el XML no corresponde al registrado en el RUT de la DIAN. Común cuando el sistema de nómina usa códigos propietarios distintos a los de la DIAN.
Solución: Mapear los tipos de documento del sistema de nómina a los códigos de la DIAN: CC=13, CE=22, PA=91, TI=12, NIT=31.
Error: Regla: 90 — Software de pruebas enviado a producción
Causa: El Software ID configurado corresponde al ambiente de pruebas, pero el request se envía al endpoint de producción.
Solución: Usar un mecanismo de configuración por ambiente. Los Software IDs de hab y producción son distintos y no son intercambiables.
FAQ
¿Cuál es la diferencia entre nómina electrónica y factura electrónica de nómina?
La nómina electrónica en Colombia es el documento soporte de pago de nómina (IndNom), un comprobante que respalda los pagos al trabajador para efectos de deducciones en renta. No es una factura — el trabajador no puede usarlo para IVA. Es obligatorio para empleadores que pagan nómina, independientemente de si facturan electrónicamente.
¿Cómo integrar el sistema de nómina con la DIAN si uso un software de terceros?
Si el software de nómina no genera el XML directamente, puedes exportar los datos de pago en CSV o JSON y procesarlos con un servicio intermedio que construya el XML, calcule el CUNE, firme y envíe a la DIAN. Este es el caso de uso más común para ERPs como SAP, Oracle HCM o sistemas legados que no tienen módulo Colombia nativo.
¿Qué pasa si no envío la nómina electrónica en el plazo establecido?
El empleador pierde la posibilidad de deducir esos pagos de nómina en la declaración de renta, según lo establece el artículo 107-1 del Estatuto Tributario colombiano. La DIAN rechazará documentos enviados con más de 60 días de retraso desde el período de pago.
¿La API de Alanube Colombia soporta nóminas con múltiples conceptos de pago?
Sí. El endpoint POST /payroll de Alanube acepta todos los conceptos de devengados (básico, horas extras, auxilio de transporte, comisiones, vacaciones) y deducciones (salud, pensión, retención en la fuente) como campos del payload JSON. Alanube construye los nodos XML correspondientes de cada concepto según el esquema de la DIAN. Obtén acceso en alanube.co.
¿Cuándo se debe emitir un ajuste de nómina electrónica?
El ajuste se emite cuando un IndNom ya aceptado por la DIAN contiene errores en los montos, conceptos, datos del trabajador o período. Hay dos tipos: eliminación (anula el documento completo) y modificación (reemplaza los valores incorrectos). El ajuste debe enviarse dentro de los 60 días del período de pago original, referenciando el CUNE del documento a corregir.
¿La nómina electrónica aplica para trabajadores independientes?
No. La nómina electrónica (IndNom) aplica para relaciones laborales dependientes — empleados con contrato de trabajo. Los pagos a trabajadores independientes se documentan con la factura electrónica de venta que emite el mismo trabajador, o con el documento soporte de contratación cuando el trabajador no está obligado a facturar. Estos son documentos distintos con reglas de habilitación separadas ante la DIAN.
Fuentes
- DIAN. (2021). Resolución 0013 de 2021 — Nómina Electrónica. Dirección de Impuestos y Aduanas Nacionales. https://www.dian.gov.co/normatividad/Paginas/resolucion_0013_11012021.aspx
- DIAN. (2022). Anexo técnico documento soporte de pago de nómina electrónica versión 1.0. https://www.dian.gov.co/impuestos/Paginas/Factura_Electronica.aspx
- Congreso de Colombia. (2019). Ley 2010 de 2019 — Ley de Crecimiento Económico. Art. 107-1.
