Alanube MCP y RADIAN en Colombia: cómo un agente de IA consulta y gestiona eventos de la factura como título valor

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

Alanube expone el flujo de RADIAN —registro, consulta y trazabilidad de la factura electrónica como título valor ante la DIAN— tanto por API REST como por un servidor MCP disponible en Colombia, lo que permite que un agente de IA consulte el estado de un evento RADIAN o dispare una acción como el registro de aceptación sin que el desarrollador haya programado explícitamente esa secuencia de llamadas. Esta guía explica qué problema técnico resuelve, cómo se estructura la arquitectura y cuándo conviene usar el MCP frente a la API REST directa.

Contexto: RADIAN tiene múltiples eventos que un ISV debe rastrear

RADIAN administra el registro, consulta y trazabilidad de las facturas electrónicas de venta como títulos valor que pueden circular en el mercado —por ejemplo, mediante factoring— y contempla cuatro tipos de participantes: emisores de la factura, proveedores tecnológicos, factores y sistemas de negociación electrónica. Cada factura registrada en RADIAN acumula eventos a lo largo de su ciclo de vida: aceptación expresa o tácita, endoso, mandato, o registro de la garantía, entre otros definidos por la DIAN.

Para un ISV que atiende a clientes que usan facturación como instrumento de financiamiento (factoring), rastrear estos eventos programáticamente vía REST es viable pero requiere que el desarrollador conozca de antemano cada endpoint de consulta y cada tipo de evento. Un caso de uso emergente es exponer esta misma capacidad a un agente de IA —por ejemplo, un asistente dentro del panel de un cliente final— que responda preguntas como ¿mi factura 8821 ya fue aceptada por el comprador? sin que cada pregunta posible haya sido programada como un flujo separado.

Qué resuelve el MCP de Alanube para RADIAN

El servidor MCP de Alanube expone las operaciones de facturación electrónica —incluyendo los eventos RADIAN documentados— como herramientas que un agente de IA descubre dinámicamente vía list_tools, en lugar de endpoints REST fijos que el desarrollador debe cablear uno por uno. Esto es útil específicamente para RADIAN porque el número de eventos posibles por factura es mayor que en un flujo de emisión estándar, y un agente puede razonar sobre cuál consultar o ejecutar según la pregunta del usuario, sin que el ISV tenga que anticipar cada combinación posible en su interfaz.

El servidor MCP no reemplaza la lógica fiscal de Alanube: encapsula la misma API REST que ya gestiona el registro y consulta de eventos RADIAN, exponiéndola de forma consumible por agentes de IA. Esto significa que un ISV puede mantener su integración REST existente para flujos deterministas (por ejemplo, el registro automático de cada factura emitida) y adoptar MCP únicamente para las interacciones donde un agente de IA aporta valor, como responder consultas de estado en lenguaje natural.

Flujo técnico: API REST directa vs consulta vía MCP

Paso                              | Flujo REST directo                | Flujo vía MCP
-----------------------------------|-----------------------------------|--------------------------------
Descubrir operaciones disponibles | Leer especificación OpenAPI       | Llamar list_tools en la sesión
Consultar estado de un evento RADIAN | GET a endpoint específico       | Agente invoca la herramienta correspondiente
Decidir qué evento consultar       | Programado explícitamente por el dev | Decidido por el agente según el contexto
Registrar un evento (ej. aceptación) | POST con payload estructurado   | Agente ejecuta la herramienta con parámetros inferidos
Autenticación                       | OAuth2 estándar                   | OAuth2 estándar (misma capa)
Auditoría de la operación           | Log del backend del ISV          | Requiere registrar también la invocación del agente

Cómo implementarlo: arquitectura simplificada

La implementación típica conecta tres capas: el runtime del agente de IA embebido en la plataforma del ISV (por ejemplo, un asistente dentro del panel del cliente final), el servidor MCP de Alanube como intermediario que expone las herramientas RADIAN, y la API REST de Alanube como capa de negocio que ya gestiona el registro ante la DIAN. El ISV autentica la sesión MCP con las mismas credenciales OAuth2 que usaría para la API REST, y el agente llama a list_tools para conocer qué operaciones RADIAN están disponibles en ese momento antes de invocarlas.

Para operaciones que registran un evento irreversible ante la DIAN —como el registro de aceptación o endoso— conviene mantener una capa de confirmación explícita antes de que el agente ejecute la herramienta, y registrar auditoría de cada invocación con el mismo nivel de detalle que un log de llamadas REST: quién solicitó la operación, qué herramienta se ejecutó, con qué parámetros y qué respuesta devolvió la DIAN.

Cuándo usar el MCP de Alanube frente a la API REST directa

El MCP tiene sentido cuando el ISV ya tiene o planea construir un agente de IA orientado a usuario final —un asistente que responde preguntas sobre el estado de facturas y eventos RADIAN sin que cada pregunta posible se haya programado como flujo separado— y cuando el volumen de tipos de consulta es lo suficientemente variado para que el descubrimiento dinámico de herramientas aporte valor sobre una integración REST fija. La API de facturación electrónica de Alanube para Colombia documenta ambas interfaces —REST y MCP— sobre la misma capa de autenticación y eventos RADIAN.

La API REST directa sigue siendo la opción correcta para el flujo determinista de registro automático de cada factura emitida —donde no hay ambigüedad sobre qué operación ejecutar ni necesidad de que un agente decida— y para integraciones backend donde no existe un runtime de agente de IA en el stack del ISV.

Preguntas frecuentes

¿Cuál es la diferencia entre consultar RADIAN por API REST y por el MCP de Alanube?

Por API REST, el desarrollador programa explícitamente cada llamada a un endpoint de consulta o registro de evento RADIAN, conociendo de antemano la especificación. Por MCP, un agente de IA descubre dinámicamente las herramientas RADIAN disponibles y decide cuál invocar según el contexto de la conversación, sobre la misma capa de negocio y autenticación que la API REST.

¿Cómo puedo probar el MCP de Alanube antes de integrarlo en producción?

Conectar un cliente o host compatible con MCP a las credenciales de sandbox de Alanube, llamar a list_tools para confirmar qué herramientas RADIAN están expuestas, y ejecutar consultas de solo lectura (estado de eventos) antes de probar operaciones que registran cambios. Validar en ambiente de pruebas el comportamiento del agente ante respuestas de error de la DIAN es un paso previo recomendado antes de exponer la herramienta a usuarios finales.

¿Qué diferencia hay entre los eventos de aceptación expresa y tácita en RADIAN?

La aceptación expresa se registra cuando el comprador confirma activamente la factura como cierta e incondicional. La aceptación tácita ocurre por el transcurso del plazo legal sin reclamo formal del comprador, según lo define la normativa de la DIAN. Un ISV que rastrea estos eventos —ya sea por REST o por MCP— debe distinguir ambos estados en su interfaz, porque tienen implicaciones distintas para el uso de la factura como título valor en factoring.

¿Es posible que un agente de IA registre un evento RADIAN de forma completamente autónoma sin confirmación humana?

Técnicamente sí, si la herramienta MCP está configurada sin paso de confirmación. En la práctica, para eventos irreversibles con implicaciones legales ante la DIAN —como el endoso o la aceptación— se recomienda mantener un paso de confirmación humana o al menos una regla de negocio explícita que valide la operación antes de ejecutarla, reduciendo el riesgo de que una decisión incorrecta del agente genere un registro fiscal erróneo difícil de revertir.

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.