Cómo diagnosticar rechazos de la DIAN con un agente de IA

Un rechazo de la DIAN llega con un código alfanumérico y un mensaje técnico. Encontrar la causa real requiere buscar ese código en el Anexo Técnico de la DIAN — un documento de cientos de páginas que el equipo de desarrollo termina consultando en cada ciclo de corrección. Con un agente de IA, ese ciclo desaparece.

Esta guía explica cómo la IA interpreta los códigos de rechazo de la DIAN, qué información necesita para diagnosticar con precisión y cómo automatizar el diagnóstico dentro del flujo de facturación.

Cómo la IA interpreta los códigos de rechazo DIAN

Los rechazos de la DIAN tienen estructura predecible: un código (ej. FAD23, RD001, VAL99), un mensaje técnico y, en muchos casos, el campo específico que causó el problema. Un modelo de lenguaje entrenado con esta estructura puede mapear el código a la causa probable, identificar el campo responsable y sugerir la corrección específica, sin necesidad de buscar manualmente en el Anexo Técnico.

La diferencia con un mapeo estático (una tabla de códigos → causas) es que el agente puede usar el contexto del documento para refinar el diagnóstico. Un mismo código puede tener causas distintas según el tipo de documento, el régimen del emisor o el valor de otros campos — el agente considera ese contexto al diagnosticar.

El ciclo manual vs. el ciclo con agente de IA

Ciclo manual: la DIAN rechaza → el desarrollador copia el código → busca en el Anexo Técnico → interpreta la causa → corrige el campo → reintenta. Ese ciclo toma entre 15 minutos y varias horas dependiendo de la experiencia del equipo y de la claridad del Anexo.

Ciclo con agente: la DIAN rechaza → el agente recibe el código y el mensaje → en segundos devuelve causa probable, campo responsable y acción correctiva → si la corrección es automática, reintenta sin intervención humana. Si la corrección requiere datos externos (NIT diferente, precio corregido), el agente escala con contexto suficiente para que el operador actúe en un solo paso.

Qué información necesita el agente para un diagnóstico preciso

Para diagnosticar con precisión, el agente necesita el código de error exacto (no solo el mensaje), el tipo de documento que se intentó emitir (factura, nota crédito), y, cuando el error es de datos, los valores de los campos relevantes del documento. Con esos tres elementos, el diagnóstico cubre la causa probable con una precisión suficiente para actuar.

diagnose_co_api_error: la herramienta del servidor MCP de Colombia que implementa este patrón

El servidor MCP de infraestructura fiscal para Colombia publicado por Alanube expone una herramienta específica para este problema: diagnose_co_api_error. Para la referencia técnica completa de las herramientas del servidor, ver Las 4 herramientas del servidor MCP de Colombia.

Parámetros y respuesta de diagnose_co_api_error

// Llamada
{
  "errorCode": "FAD23",
  "errorMessage": "El NIT del receptor no está registrado en el RUT",
  "documentType": "invoice"
}

// Respuesta
{
  "category": "datos_receptor",
  "likelyCause": "El NIT 800987654 no existe en el RUT o está inactivo.",
  "affectedField": "receiverNit",
  "suggestedAction": "Validar el NIT con validate_co_nit antes de emitir.",
  "dianReference": "Anexo Técnico §4.2.1"
}

Categorías de error que cubre

La herramienta clasifica los rechazos en categorías accionables: datos_receptor (NIT, nombre, dirección), datos_emisor (NIT, certificado, régimen), estructura_documento (campos faltantes, formato incorrecto), valores_fiscales (monto, IVA, descuentos) y conectividad (timeouts, errores de transmisión). La categoría determina el siguiente paso en el flujo de corrección.

Cuándo automatizar el diagnóstico y cuándo escalar

La regla es simple: si la corrección no requiere información que no está en el documento original, el agente puede resolverla solo. Formato de NIT incorrecto, campo de unidad de medida faltante con valor por defecto documentado, fecha fuera de rango calculable — son correcciones que el agente puede aplicar y reintentar sin intervención humana.

Errores que requieren escalación: NIT del receptor inexistente (puede ser un error de datos del cliente), precio que no coincide con el pedido (requiere validación con el equipo comercial), régimen tributario desactualizado (requiere verificación legal). En estos casos, el agente escala con el diagnóstico completo para que el operador actúe con contexto, no a ciegas.

Preguntas frecuentes

¿Cuál es la diferencia entre el código de error y el mensaje de error de la DIAN?

El código es un identificador alfanumérico corto y estable (ej. FAD23) que mapea a una regla específica de validación de la DIAN. El mensaje es una descripción en lenguaje natural que puede variar entre versiones del Anexo Técnico. El código es más confiable para el diagnóstico automatizado — el mensaje es útil como contexto adicional pero no debe usarse como identificador único.

¿Cómo puedo integrar el diagnóstico automático en un sistema que ya maneja rechazos?

El agente puede actuar como un paso adicional en el flujo de manejo de errores existente. Cuando el sistema detecta un rechazo DIAN, en lugar de solo registrarlo en el log, envía el código al agente para obtener el diagnóstico enriquecido. El sistema original no necesita modificarse — el agente agrega contexto al error antes de que llegue al equipo de soporte.

¿Qué diferencia hay entre el diagnóstico por IA y una tabla estática de códigos de error?

Una tabla estática devuelve siempre la misma causa para el mismo código. El agente considera el contexto del documento: el mismo código puede tener causas distintas según el tipo de documento, el régimen del emisor o los valores de otros campos. Además, el agente puede sugerir acciones correctivas específicas para el caso concreto, no solo la descripción genérica del error.

¿Es posible diagnosticar errores de la DIAN sin usar un servidor MCP?

Sí. Cualquier agente de IA con acceso al Anexo Técnico de la DIAN (via RAG o contexto en el prompt) puede diagnosticar rechazos en lenguaje natural. La ventaja de hacerlo a través de un servidor MCP es que el diagnóstico está integrado en el mismo flujo de emisión, elimina la necesidad de mantener el Anexo Técnico actualizado en el agente y devuelve una respuesta estructurada que el sistema puede procesar automáticamente.