Nómina electrónica en Colombia: guía técnica para ISVs que integran con la DIAN

Por Ing. Carlos Méndez | 2 de septiembre de 2026

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.

Un desarrollador que acaba de integrar facturación electrónica DIAN recibe la instrucción de agregar nómina electrónica en el mismo ciclo de desarrollo. El cliente asume que funcionará igual. No funciona igual: el esquema XML es diferente, el habilitador ahora es un OASF y no un PT, la firma usa el mismo estándar pero sobre un documento con estructura distinta, y los errores de rechazo DIAN rara vez son autoexplicativos. El equipo pierde semanas en una curva de aprendizaje que nadie presupuestó.

Esta guía cubre el modelo técnico completo de la nómina electrónica en Colombia: qué documentos existen, cómo se estructura el XML, qué hace un OASF, cómo funciona el flujo de validación DIAN, cómo se calcula el CUNE y qué criterios usar para seleccionar un proveedor de API. Al terminar, el equipo técnico tendrá el mapa completo para planificar la integración sin improvizar.

¿Qué es la nómina electrónica en Colombia?

La nómina electrónica en Colombia es el conjunto de documentos digitales que los empleadores deben generar, firmar digitalmente y transmitir a la DIAN para soportar los pagos salariales y prestaciones de sus trabajadores dependientes. No es un reemplazante de la factura electrónica de venta — es un sistema paralelo con su propia cadena de validación, sus propios tipos de documento y su propio flujo de habilitación.

El marco normativo está definido por la Resolución DIAN 0013 de 2021 y sus modificatorias, que establecen las condiciones técnicas de generación, transmisión y habilitación. La DIAN valida cada documento y emite una ApplicationResponse con el resultado. A diferencia de la factura electrónica, el intermediario aquí no es un proveedor tecnológico autorizado (PT) sino un Operador Autorizado de Facturación por Suscripción (OASF).

Para un ISV, la diferencia práctica es relevante: el software de nómina del cliente se conecta al OASF, y este transmite los documentos a la DIAN. El ISV debe conocer tanto el esquema XML de generación como la API específica del OASF que integra, porque ambas capas tienen sus propias reglas de validación y formatos de error.

Sujetos obligados y consecuencias del incumplimiento

Están obligados a emitir nómina electrónica todos los empleadores que realicen pagos laborales que constituyan deducción en el impuesto de renta: salarios, honorarios con retención, comisiones, prestaciones sociales y cualquier forma de remuneración a trabajadores dependientes. El criterio decisivo no es el tamaño del empleador sino si los pagos generan retención en la fuente laboral.

Para los ISVs que desarrollan software de nómina o ERP con módulo de nómina, esto implica que virtualmente todo cliente corporativo requerirá la funcionalidad activa. No es una característica opcional ni un módulo adicional — es infraestructura crítica que determina la validez tributaria de los pagos que el software procesa.

Tipos de documentos electrónicos de nómina: NIDD y NANE

La nómina electrónica en Colombia opera con dos tipos de documentos principales. Cada uno tiene un esquema XML específico, reglas de validación propias y un caso de uso bien delimitado. La decisión de cuál generar en cada situación debe estar modelada en la lógica del software — no en el criterio del usuario final.

Nómina Individual Devengada y Deducida (NIDD)

Es el documento principal de nómina — equivalente funcional al soporte de pago. Se genera por empleado, por período de liquidación (quincenal, mensual o el período pactado). Contiene los devengos brutos (salario básico, horas extra, comisiones, auxilio de transporte, vacaciones, prima, cesantías, viáticos) y las deducciones (aportes a salud, pensión, fondo de solidaridad, retención en la fuente, embargos judiciales). El CUNE (Código Único de Nómina Electrónica) identifica cada documento de forma única, análogo al CUFE en facturación de venta.

Nota de Ajuste de Nómina Electrónica (NANE)

Es el mecanismo de corrección — el equivalente de la nota crédito en facturación. Se usa cuando una NIDD ya validada por la DIAN contiene errores que deben corregirse: un valor de devengo incorrecto, datos del trabajador mal registrados o un período mal asignado. La NANE referencia el CUNE de la NIDD que corrige. Existen dos subtipos: reemplazo (anula y sustituye con valores correctos) y eliminación (anula sin reemplazo cuando el documento no debería existir). No existe edición directa de una NIDD ya transmitida.

<!-- Estructura simplificada de una NIDD (NominaIndividual) -->
<NominaIndividual xmlns="dian:gov:co:facturacionelectronica:NominaIndividual">
  <InformacionGeneral
    Version="V1.0"
    TipoXML="102"
    CUNE="hash-sha384-aqui"
    Periodo="MENSUAL"
    FechaGen="2026-09-01"
    HoraGen="09:00:00"
    TipoMoneda="COP"/>
  <Empleador
    RazonSocial="Empresa SAS"
    NIT="900123456"
    Dv="7"
    Pais="CO"
    MunicipioCiudad="11001"/>
  <Trabajador
    TipoTrabajador="01"
    SubTipoTrabajador="00"
    TipoDocumento="13"
    NumeroDocumento="12345678"
    PrimerApellido="García"
    SegundoApellido="López"
    PrimerNombre="Luis"/>
  <Devengados>
    <Basico SuelDia="83333" TraDur="30" />
    <AuxTransporte AuxSalarial="162000" />
  </Devengados>
  <Deducciones>
    <Salud Porcentaje="4" Deduccion="100000" />
    <FondoPension Porcentaje="4" Deduccion="100000" />
  </Deducciones>
  <DevengadosTotal>2662000</DevengadosTotal>
  <DeduccionesTotal>200000</DeduccionesTotal>
  <ComprobanteTotal>2462000</ComprobanteTotal>
</NominaIndividual>

El CUNE: cómo se calcula y por qué no puede delegarse al proveedor

El CUNE (Código Único de Nómina Electrónica) es el identificador irrepetible de cada NIDD. Se calcula como el hash SHA-384 de la concatenación de los siguientes campos en orden exacto: número del documento de nómina, fecha de generación, hora de generación, devengado total, deducido total, total del comprobante, número de documento del trabajador, tipo de documento del trabajador, NIT del empleador, y ambiente (1 para producción, 2 para pruebas). Los campos se concatenan sin separadores. Cualquier discrepancia en el orden o en los valores produce un hash diferente al que la DIAN calculará para validar.

El error más frecuente es incluir separadores (puntos, comas) en los valores monetarios al concatenar — por ejemplo, escribir '2.462.000' en lugar de '2462000'. El CUNE calculado con valores formateados siempre diverge del que la DIAN espera. La implementación correcta trabaja con los valores numéricos crudos antes de cualquier formateo para presentación.

Flujo técnico de integración: de la generación XML a la validación DIAN

El flujo de integración de nómina electrónica tiene cuatro etapas secuenciales. Una falla en cualquiera produce documentos en estado de error que el empleador no puede usar como soporte deducible. A continuación, el flujo técnico completo desde la perspectiva del software integrador.

Paso 1 — Habilitación del empleador con el OASF

El empleador debe inscribirse en un OASF habilitado por la DIAN y obtener credenciales de acceso a su API. Este proceso es análogo a la habilitación en facturación electrónica pero completamente independiente: un empleador puede tener un PT diferente para facturas y un OASF diferente para nómina. El software debe gestionar la configuración de credenciales por cliente y por entorno (sandbox vs. producción).

Paso 2 — Generación del XML y cálculo del CUNE

El software genera la NIDD en formato XML conforme al XSD publicado por la DIAN, calcula el CUNE con SHA-384 y firma el documento con un certificado digital vigente emitido por una entidad certificadora acreditada en Colombia. La firma usa XAdES-BES. Un certificado vencido genera rechazo inmediato en la validación DIAN, independientemente de si el resto del documento es correcto.

Paso 3 — Envío al OASF

El software envía el XML firmado al OASF a través de su API. La estructura del request varía por operador: algunos aceptan XML directo como payload, otros lo esperan en base64 dentro de un envelope SOAP, otros tienen una API REST con OAuth 2.0. Esta variabilidad es el principal factor de fricción para ISVs que deben soportar múltiples OASF simultáneamente.

Paso 4 — Validación DIAN y ApplicationResponse

El OASF retransmite el documento a la DIAN. La DIAN valida el esquema, la firma, el CUNE y las reglas de negocio, y retorna una ApplicationResponse con estado aprobado (código 0) o rechazado con código de error. El tiempo de respuesta varía: los OASF con infraestructura robusta responden en menos de 3 segundos en el percentil 95; en alta concurrencia pueden superar 30 segundos. El manejo asíncrono es recomendado para envíos masivos.

Criterios técnicos para evaluar un proveedor de nómina electrónica vía API

Evaluar un proveedor de nómina electrónica requiere criterios distintos a los de facturación. El volumen puede ser masivo (cientos de NIDD por período), los errores tienen consecuencias tributarias directas y la estructura de mensajes de error de la DIAN es más densa. Los criterios mínimos de evaluación son:

Sandbox con escenarios de error simulados: un sandbox que solo retorna éxito no sirve para pruebas reales. El entorno de pruebas debe simular rechazos DIAN con códigos reales.

API REST documentada con ejemplos funcionales: los endpoints deben estar versionados. La documentación debe incluir ejemplos completos de request y response, no solo esquemas abstractos.

Errores traducidos y accionables: los códigos de error de la DIAN deben llegar con descripción que indique el campo específico que falló y la corrección requerida, no solo el número de código.

Soporte a envíos masivos con cola de reintentos: la API debe soportar lotes y gestionar automáticamente los reintentos cuando la DIAN esté en mantenimiento, sin que el ISV implemente su propio mecanismo.

Webhooks o respuesta diferida consultable: dado que la validación no siempre es síncrona, el proveedor debe ofrecer notificación asíncrona (webhook) o un endpoint de consulta por ID de transacción.

Los ISVs que necesitan abstraer la complejidad multi-OASF pueden recurrir a una capa intermedia que normaliza los diferentes formatos. La API de nómina electrónica para Colombia de Alanube ofrece esta abstracción: el ISV se integra una vez y la plataforma gestiona la comunicación con el OASF correspondiente, incluyendo reintentos y manejo de errores estandarizado.

Preguntas frecuentes sobre nómina electrónica en Colombia

¿Cuál es la diferencia entre nómina electrónica y factura electrónica en Colombia?

Son sistemas completamente independientes. La factura electrónica documenta transacciones de venta de bienes o servicios y se transmite a través de un proveedor tecnológico (PT) habilitado por la DIAN. La nómina electrónica documenta pagos laborales y se transmite a través de un OASF. Los documentos tienen esquemas XML distintos, generan identificadores únicos diferentes (CUFE para factura, CUNE para nómina) y sus flujos de habilitación son independientes. Un empleador puede contratar el mismo proveedor para ambos o proveedores distintos.

¿Cómo puedo verificar si un documento de nómina fue aprobado por la DIAN?

La confirmación llega a través del OASF en forma de ApplicationResponse — un XML con el estado de validación de la DIAN. El campo de estado indica si el documento fue aceptado (código 0) o rechazado (código de error). El OASF debe retornar este documento al integrador como parte de la respuesta de la operación de envío, ya sea de forma síncrona o a través de webhook/polling. Los ISVs deben almacenar el CUNE y el estado de cada documento para auditoría.

¿Qué diferencia hay entre una NANE de reemplazo y una de eliminación?

Una NANE de reemplazo anula la NIDD original y la sustituye con un documento corregido cuyos valores correctos van incluidos en la misma NANE. Una NANE de eliminación simplemente anula la NIDD sin reemplazarla, usada cuando el documento fue emitido por error y no corresponde a ningún pago real. En ambos casos la NANE debe referenciar el CUNE de la NIDD afectada. Emitir una NANE de eliminación cuando se requería un reemplazo deja un período sin soporte deducible.

¿Es posible integrar nómina electrónica directamente con la DIAN sin pasar por un OASF?

No. La regulación exige que la transmisión se realice a través de un OASF habilitado por la DIAN. No existe un mecanismo de transmisión directa para empleadores que no sean operadores habilitados. Los ISVs deben integrar al menos un OASF, y la recomendación técnica es abstraer esa integración para poder cambiar de operador o soportar múltiples sin reescribir la lógica de generación del XML.

Sobre el autor

Ing. Carlos Méndez es arquitecto de software con más de 10 años integrando sistemas fiscales en América Latina. Ha liderado implementaciones de facturación electrónica en Colombia, México y Centroamérica para ISVs de mediana y gran escala.