Agente de Retención en Colombia: Obligaciones Técnicas para API de Facturación Electrónica

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.

Para el motor de facturación electrónica de un ISV, el concepto de agente de retención no es una abstracción tributaria sino una propiedad del modelo de datos del comprador que activa o desactiva bloques enteros del XML UBL 2.1. Cuando el equipo de desarrollo no lo trata como tal — y lo deja como un campo de texto libre o un checkbox sin validación — los errores de retención se convierten en el ruido más frecuente en el monitoreo de transmisiones a la DIAN.

Este artículo explica qué es exactamente un agente de retención en el contexto de la factura electrónica colombiana, cómo identificarlo desde fuentes verificables, cómo modelarlo en la base de datos del ISV, y qué flujos de activación de retenciones derivan de su presencia o ausencia en una transacción.

Qué es un agente de retención y quién designa esa condición

Un agente de retención es una persona natural o jurídica a quien la DIAN o la ley tributaria le impone la obligación de retener un porcentaje del pago que realiza a un proveedor y consignarlo directamente al Estado. La condición de agente retenedor se determina por la ley y por la calidad del pagador, no por la voluntad de las partes. Las categorías más comunes son: personas jurídicas en general (aplica reteRenta), grandes contribuyentes (aplica reteRenta, reteIVA), entidades del Estado (aplica reteRenta, reteIVA y en algunos casos reteICA), y autorretenedores (el propio emisor practica la retención sobre sus ingresos).

La condición de agente retenedor queda registrada en el RUT (Registro Único Tributario) del comprador, en el campo de Responsabilidades: código 06 para gran contribuyente, código 07 para agente retenedor designado, código 09 para autorretenedor, código 15 para agente retenedor de IVA. El ISV puede verificar esta condición consultando el RUT público del NIT del comprador, aunque la frecuencia de actualización es el reto: un comprador puede cambiar su condición y el ISV debe detectarlo.

Cómo identificar y mantener actualizada la condición de agente retenedor

Hay tres fuentes para identificar si un comprador es agente retenedor. Primera: consulta directa al servicio público de validación de RUT de la DIAN, disponible mediante scraping del portal o servicios de terceros que ofrecen la API de consulta de RUT. Segunda: información declarada por el propio cliente comprador al momento de registrarse en la plataforma del ISV. Tercera: notificaciones del cliente cuando cambia su condición tributaria. Las tres fuentes tienen fallos potenciales: la consulta RUT puede tener datos desactualizados, la autodeclaración puede ser incorrecta, y las notificaciones dependen de la diligencia del cliente.

La mejor práctica para ISVs de mediana y gran escala es: mantener un registro de la condición de agente retenedor por NIT con fecha de última verificación, programar una verificación automática trimestral contra el RUT, y permitir que el cliente corrija la condición con evidencia (PDF del RUT). El modelo de datos del comprador debe incluir al menos cuatro campos booleanos independientes: esAgenteReteRenta, esAgenteReteIVA, esAgenteReteICA, esAutorretenedor.

Modelo de datos recomendado para el objeto Comprador en el ISV

El objeto Comprador en el dominio del ISV debe separar claramente la información de identidad fiscal del comprador de su configuración de retenciones. La identidad incluye: NIT, razón social, régimen tributario (ordinario, SIMPLE, especial, entidad no contribuyente), tipo de persona (natural o jurídica). La configuración de retenciones incluye: tipo de agente retenedor (booleanos por tipo), tarifas específicas si difieren de las genéricas, municipios con reteICA activa y sus tarifas, fecha de última actualización de la configuración.

La separación entre identidad y configuración permite actualizar las tarifas o la condición de agente sin modificar los datos maestros del tercero, y genera un log de auditoría que puede presentarse ante requerimientos DIAN. Cada cambio en la configuración de retenciones debe quedar registrado con fecha, usuario y razón del cambio.

Flujo de activación de retenciones en el ciclo de creación de factura

Cuando un usuario crea una factura en el sistema del ISV y selecciona un comprador, el motor de facturación debe ejecutar esta secuencia de verificación: 1. ¿El emisor es contribuyente del régimen SIMPLE? Si sí: no aplica reteRenta ni reteIVA. Fin para estos tipos. 2. ¿El comprador es persona jurídica o gran contribuyente? Si sí: activar reteRenta. 3. ¿El comprador está marcado como agente retenedor de IVA (responsabilidad 15)? Si sí: activar reteIVA. 4. ¿El comprador es agente retenedor de ICA en el municipio de la actividad? Si sí: activar reteICA con la tarifa del municipio correspondiente. 5. ¿El emisor es autorretenedor (responsabilidad 09)? Si sí: activar autorretención en fuente independientemente de la condición del comprador.

Esta secuencia debe ser ejecutada automáticamente pero con posibilidad de override manual por parte del usuario, con log obligatorio de la razón del override. Algunos ISVs implementan una interfaz de previsión que muestra al usuario los bloques de retención que se incluirán antes de emitir la factura, reduciendo errores por desconfiguración.

Grandes contribuyentes: exigencias adicionales en la API DIAN

Los grandes contribuyentes tienen validaciones adicionales en el sistema DIAN. Cuando el comprador es gran contribuyente, la DIAN puede cruzar el NIT del comprador contra la lista oficial de grandes contribuyentes y rechazar documentos donde el comprador aparezca como gran contribuyente pero no se hayan declarado las retenciones correspondientes. Aunque este cruce no es instantáneo en todos los casos, la DIAN lo usa en procesos de fiscalización posterior.

Algunos ISVs que usan proveedores de API de facturación con soporte nativo para retenciones pueden delegar la lógica de activación al proveedor cuando este expone un modelo de datos que incluye los campos de agente retenedor. La API de facturación electrónica para Colombia de Alanube incluye validación de consistencia de retenciones antes de la transmisión a la DIAN, lo que reduce el ciclo de corrección de errores en retenciones.

Manejo de la autorretención: cuando el emisor es el agente

La autorretención es el caso donde el propio emisor está designado por la DIAN como responsable de practicar y consignar su propia retención en la fuente. Se aplica principalmente a contribuyentes con ingresos elevados que la DIAN designa mediante resolución. Para el ISV, esto implica que el emisor debe configurar su propia condición de autorretenedor en el sistema, y el motor de facturación debe activar el bloque WithholdingTaxTotal ID 06 con el emisor como agente, independientemente de si el comprador es o no agente retenedor.

Un caso específico es la Autorretención Especial (Decreto 1625 de 2016): aplica a contribuyentes del régimen ordinario cuya actividad principal tiene tarifa de autorretención del 0.4%, 0.8% o 1.6% según la actividad económica CIIU del emisor. Esta tarifa se usa en el campo Percent del bloque WithholdingTaxTotal ID 06 cuando es autorretención especial, diferente de la tarifa de retención ordinaria que podría aplicar el comprador.

Preguntas frecuentes sobre agentes de retención en la API

¿Cuál es la diferencia entre agente retenedor designado y gran contribuyente en el contexto de retenciones?

Todo gran contribuyente es agente retenedor, pero no todo agente retenedor es gran contribuyente. El gran contribuyente tiene la designación formal de la DIAN (resolución anual) y sus obligaciones de retención incluyen reteRenta y reteIVA automáticamente. Un agente retenedor genérico (persona jurídica) aplica reteRenta por ley pero no necesariamente reteIVA. La diferencia en el modelo de datos del ISV es que 'gran contribuyente' debe tener ambos flags activos (esAgenteReteRenta y esAgenteReteIVA), mientras que una persona jurídica ordinaria solo tiene esAgenteReteRenta activo.

¿Cómo puedo verificar automáticamente si un NIT es agente retenedor sin consultar el RUT manualmente?

La DIAN no ofrece una API pública REST para consulta de RUT. Existen servicios de terceros que emulan la consulta del portal web DIAN y devuelven los datos del RUT en formato estructurado, incluyendo las responsabilidades. También está disponible el servicio de consulta SOAP de la DIAN para habilitados, que permite verificar el NIT y algunos atributos del contribuyente. En la práctica, la mayoría de ISVs usan la autodeclaración del cliente con validación periódica.

¿Qué diferencia hay entre autorretención ordinaria y autorretención especial en el XML?

Ambas usan TaxScheme ID 06 en el XML. La diferencia está en la tarifa (Percent) y en el concepto tributario asociado. La autorretención ordinaria usa las tarifas del concepto (servicios 4%, compras 2.5%). La autorretención especial usa las tarifas del Decreto 1625/2016 (0.4%, 0.8%, 1.6% según CIIU). En el modelo de datos, es conveniente tener un campo que diferencie el tipo de autorretención para seleccionar la tarifa correcta automáticamente.

¿Es posible que un mismo comprador sea agente retenedor en un período y no en otro?

Sí. La condición de agente retenedor puede cambiar si la DIAN revoca o actualiza la designación, si el contribuyente cambia de régimen, o si deja de ser gran contribuyente (la lista se actualiza anualmente). Para el ISV, esto implica que la configuración de retenciones de un comprador debe tener versionamiento temporal: las facturas emitidas en un período deben reflejar la condición del comprador en ese momento, no la condición actual. Un log con fecha de vigencia de cada configuración es la solución más robusta.