Retenciones en Factura Electrónica DIAN: Guía Técnica para ISVs

Ing. Carlos Méndez | Septiembre 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.

Cuando el área de contabilidad de un cliente reporta que sus certificados de retención no cuadran con los montos registrados en la DIAN, el equipo de desarrollo enfrenta invariablemente el mismo diagnóstico: las retenciones no se incluyeron en el XML de la factura electrónica, se incluyeron en el bloque incorrecto, o los porcentajes y bases no pasaron la validación del motor de la DIAN. En Colombia, las retenciones no son un dato informativo que se registra al margen del documento fiscal — forman parte integral de la estructura UBL 2.1, con validación matemática en tiempo real y cruce contra el RUT del agente retenedor.

Esta guía documenta los tres tipos de retención que cualquier ISV debe soportar en su implementación de factura electrónica colombiana (reteRenta, reteIVA y reteICA), su mapeo al XML UBL 2.1, la lógica de quién declara qué, y el flujo técnico completo de transmisión a la DIAN. Al terminarla, el equipo tendrá la referencia técnica para implementar correctamente la estructura WithholdingTaxTotal sin depender de la documentación oficial dispersa en varios anexos técnicos.

Por qué las retenciones son parte estructural de la factura electrónica en Colombia

En la facturación tradicional colombiana, las retenciones se manejaban como transacciones separadas entre comprador y vendedor, y el cruce ocurría en las declaraciones tributarias periódicas. Con la factura electrónica DIAN, esto cambia de forma sustancial: el emisor incluye en el XML las retenciones que el comprador (cuando es agente retenedor) va a practicar, convirtiendo esa información en parte del documento fiscal con validez legal. La DIAN valida matemáticamente que los montos declarados sean consistentes con las bases y porcentajes del documento.

Esto tiene una implicación técnica directa para los ISVs: el motor de validación de la DIAN rechaza documentos con estructuras de retención mal formadas con el mismo nivel de severidad que rechaza un NIT inválido o una firma XAdES-BES incorrecta. Un error en WithholdingTaxTotal no produce una advertencia — produce un rechazo con código de error que requiere corrección y re-transmisión del documento completo.

Los tres tipos de retención que todo ISV debe implementar

El estándar UBL 2.1 adoptado por Colombia para la factura electrónica distingue las retenciones mediante el campo TaxScheme/ID dentro de cada bloque WithholdingTaxTotal. Hay tres tipos que el ISV debe manejar, cada uno con su propio ID de esquema y reglas de cálculo.

Retención en la fuente — TaxScheme ID 06

La retención en la fuente (reteRenta) aplica cuando el comprador está designado como agente retenedor ante la DIAN. La base de retención es el valor antes de IVA (valor bruto del bien o servicio). El porcentaje varía entre 0.5% y 11% dependiendo del concepto tributario: 2.5% para servicios en general, 3.5% para honorarios de personas jurídicas, 11% para honorarios de personas naturales. El monto retenido reduce el valor neto que el comprador paga al proveedor, pero el proveedor debe declarar el valor bruto en su renta. En el XML, este bloque tiene TaxScheme/ID igual a '06'.

Retención de IVA (ReteIVA) — TaxScheme ID 04

La reteIVA aplica cuando el comprador es un gran contribuyente o una entidad del régimen especial designada por la DIAN para retener IVA. La tarifa estándar de ReteIVA es el 15% sobre el valor del IVA de la factura. Por ejemplo, si la factura tiene IVA de $190,000, la reteIVA sería $28,500. Esta retención se aplica sobre el IVA, no sobre la base gravable. Implementar correctamente la diferencia entre base de reteRenta (valor neto) y base de reteIVA (valor del IVA) es uno de los errores más comunes en las integraciones nuevas.

Retención de ICA (ReteICA) — TaxScheme ID 07

El ICA (Impuesto de Industria y Comercio) es un impuesto municipal, y su retención opera cuando el comprador está designado como agente retenedor de ICA en el municipio donde se genera la actividad comercial. La tarifa varía por municipio: Bogotá aplica entre 4 y 11.04 por mil según la actividad, Medellín entre 2 y 10 por mil. El ISV debe recibir del cliente la configuración de las tarifas municipales aplicables, ya que no existe un catálogo único centralizado en la DIAN para este impuesto.

Estructura XML UBL 2.1: cómo mapear WithholdingTaxTotal

Cada tipo de retención requiere su propio bloque cac:WithholdingTaxTotal dentro del elemento raíz Invoice. Si una factura tiene los tres tipos (reteRenta + reteIVA + reteICA), el XML contendrá tres bloques WithholdingTaxTotal independientes. El elemento interno cac:TaxSubtotal contiene el desglose: cbc:TaxableAmount es la base sobre la que se calcula la retención, cbc:TaxAmount es el monto retenido, y cac:TaxCategory/cac:TaxScheme/cbc:ID identifica el tipo. El cbc:TaxAmount en el nivel raíz de WithholdingTaxTotal debe ser igual al cbc:TaxAmount dentro de TaxSubtotal.

El campo cbc:Percent dentro de TaxCategory expresa la tarifa aplicada. Para reteRenta al 3.5%, el valor es '3.50'. Para reteIVA al 15% sobre IVA, el valor es '15.00'. La DIAN valida que TaxableAmount multiplicado por Percent/100 sea igual a TaxAmount, con tolerancia de hasta 1 peso por redondeo. Cualquier discrepancia mayor produce rechazo con código de error de validación matemática.

Un error frecuente es confundir el elemento TaxTotal (que agrupa los impuestos que el emisor cobra, como IVA) con WithholdingTaxTotal (que agrupa las retenciones que el receptor aplica). Son bloques completamente distintos en el esquema UBL 2.1. El primero aumenta el valor a pagar; el segundo lo reduce. Mezclarlo produce rechazos inmediatos en la validación de la DIAN.

Quién declara las retenciones: el emisor, no el receptor

Este es el aspecto que más confusión genera en equipos que vienen de otros países de LATAM: en Colombia, es el emisor de la factura quien incluye en el XML las retenciones que el comprador va a practicar. El receptor no modifica el documento. El proveedor conoce de antemano (por acuerdo comercial o por los datos del RUT del cliente) si el comprador es agente retenedor y qué tarifas aplica, y esa información va codificada en el XML que se transmite a la DIAN.

Si el comprador aplica retenciones que no estaban declaradas en la factura original, el camino de corrección es una nota débito (para aumentar el monto a cobrar) o una nota crédito (para ajustar valores). No existe en el sistema colombiano un mecanismo donde el receptor modifique el XML original de la factura electrónica. Esto implica que el ISV debe proveer a sus clientes (emisores) una interfaz para configurar si su contraparte es agente retenedor y con qué tarifas.

Flujo técnico de transmisión a la DIAN con retenciones

El flujo no difiere del de una factura estándar en términos de protocolo de transmisión. La diferencia está en la construcción del XML antes de enviarlo. Paso 1: el sistema calcula el valor neto del bien o servicio y los impuestos (IVA). Paso 2: si el comprador es agente retenedor, el sistema calcula los montos de retención aplicables (reteRenta sobre valor neto, reteIVA sobre valor del IVA, reteICA sobre valor neto si aplica). Paso 3: los bloques WithholdingTaxTotal se agregan al XML con sus respectivos TaxSubtotal. Paso 4: el LegalMonetaryTotal/PayableAmount debe reflejar el valor neto a pagar después de restar todas las retenciones. Paso 5: el documento firmado se transmite al endpoint DIAN para validación previa y generación del CUFE.

La DIAN ejecuta tres niveles de validación sobre las retenciones: validación de estructura (que los campos obligatorios existan con los tipos de dato correctos), validación de referencia cruzada (que el TaxScheme ID sea uno de los valores permitidos: 01-IVA, 04-ReteIVA, 06-ReteRenta, 07-ReteICA), y validación matemática (que los montos sean consistentes con las bases y porcentajes declarados). Los tres niveles se ejecutan en tiempo real y cualquier falla produce un rechazo con código específico.

Consideraciones para plataformas multi-cliente que manejan agentes retenedores

Un ISV que sirve a múltiples empresas emisoras enfrenta el desafío de que no todos los clientes tienen compradores agentes retenedores, pero algunos tienen muchos. La arquitectura más robusta es mantener una tabla de configuración por par (emisor, receptor) que indique qué tipos de retención aplican y con qué tarifas. Esto evita hard-codear porcentajes en la lógica de negocio y permite actualizarlos cuando la DIAN o el municipio modifiquen las tarifas sin necesidad de un despliegue de código.

Los proveedores de API de facturación electrónica que ofrecen soporte nativo para retenciones como parte del modelo de datos de su API (no como campos adicionales opcionales) reducen significativamente el tiempo de integración. La API de facturación electrónica para Colombia de Alanube expone los tres tipos de retención como objetos de primer nivel en el payload de creación de factura, con validación de consistencia antes de transmitir a la DIAN.

Preguntas frecuentes sobre retenciones en factura electrónica Colombia

¿Cuál es la diferencia entre TaxTotal y WithholdingTaxTotal en el XML DIAN?

TaxTotal agrupa los impuestos que el emisor cobra al comprador y que aumentan el valor de la factura, principalmente el IVA (TaxScheme ID 01). WithholdingTaxTotal agrupa las retenciones que el comprador practicará y que reducen el valor neto a pagar. Los dos elementos tienen estructura similar en UBL 2.1 pero posición diferente en el documento y efecto opuesto en el LegalMonetaryTotal. Mezclar los dos bloques es el error más frecuente y produce rechazo inmediato en la validación DIAN.

¿Cómo puedo incluir los tres tipos de retención en una misma factura electrónica?

Incluyendo tres bloques cac:WithholdingTaxTotal independientes dentro del elemento Invoice, uno por cada tipo de retención (ID 06 para reteRenta, ID 04 para reteIVA, ID 07 para reteICA). El orden en el XML no es crítico, pero cada bloque debe estar completo con su propio TaxSubtotal, TaxableAmount, TaxAmount, Percent y TaxScheme. El LegalMonetaryTotal/PayableAmount debe descontar la suma de todos los TaxAmount de los tres bloques WithholdingTaxTotal.

¿Qué diferencia hay entre incluir la retención en la factura electrónica y el certificado de retención?

Son documentos con propósitos distintos. La inclusión de retenciones en la FE es la declaración en tiempo real dentro del documento de compraventa, con validación DIAN. El certificado de retención es el documento que el agente retenedor emite periódicamente (mensual o bimestral) al proveedor, consolidando todas las retenciones practicadas. El certificado de retención no reemplaza la declaración en la FE — son instrumentos complementarios. Algunos ISVs también implementan la emisión automática de certificados de retención como módulo adicional a la facturación electrónica.

¿Es posible corregir una retención mal declarada en una factura ya aceptada por la DIAN?

No es posible modificar una factura electrónica ya aceptada. La corrección se realiza mediante una nota crédito que anule el documento original (referenciar la factura con su CUFE), seguida de una nueva factura con la estructura de retenciones correcta. Si solo se necesita ajustar el monto (por ejemplo, se declaró reteRenta al 2.5% cuando era al 3.5%), la vía más práctica es una nota débito que documente la diferencia. En cualquier caso, el ajuste queda registrado en el sistema DIAN con trazabilidad completa.