MCP DIAN en Sandbox: escenarios de prueba obligatorios antes de producción

El sandbox de un servidor MCP fiscal no es un trámite — es el único lugar donde se pueden probar escenarios de error sin consecuencias fiscales reales. Un flujo que no ha sido probado con rechazos, NITs inválidos y notas crédito en entorno de prueba llegará a producción con comportamientos indefinidos ante el primer caso borde.

Esta guía describe los cinco escenarios que cualquier integración MCP de facturación DIAN debe cubrir en sandbox antes de solicitar acceso a producción, y la lista de verificación para confirmar que el flujo está listo.

Por qué el sandbox no es solo una formalidad

En producción, cada factura emitida tiene validez fiscal, genera obligaciones tributarias y puede ser auditada por la DIAN. Los errores en producción no se pueden deshacer con una simple corrección de código — requieren notas crédito, comunicación con el receptor y, en casos graves, reportes a la entidad. El sandbox existe precisamente para que esos errores ocurran en un entorno sin consecuencias.

Además, el sandbox tiene comportamiento distinto al de producción en algunos aspectos: los NITs de prueba no existen en el RUT real, los CUFEs generados no son válidos ante la DIAN y los tiempos de respuesta pueden variar. Cubrir todos los escenarios en sandbox es la única forma de confirmar que el flujo maneja esas diferencias correctamente.

Escenario 1 — Emisión válida con datos de prueba

El primer escenario confirma que la conexión funciona de extremo a extremo: el agente llama a la herramienta de emisión con datos válidos de sandbox y recibe un CUFE. Este es el caso feliz — si falla aquí, hay un problema de configuración que resolver antes de avanzar.

// Prompt de prueba para el agente
"Emite una factura de prueba en sandbox por un servicio de consultoría
 de 1.000.000 COP + IVA 19% para el NIT de prueba 800123456."

// Resultado esperado
// → ok: true
// → cufe: [string]
// → status: "ACCEPTED"

Escenario 2 — Emisión con NIT de receptor inválido

Este escenario prueba que el flujo maneja correctamente un rechazo por datos del receptor. Usar un NIT que no existe en el entorno de sandbox. El resultado esperado es un rechazo con código de error — lo importante no es el rechazo sino cómo el flujo lo presenta al operador o lo maneja automáticamente.

Verificar que: el rechazo no genera una excepción no controlada, el código de error es accesible para el diagnóstico posterior, el flujo no reintenta automáticamente sin corrección (un NIT inexistente no se vuelve válido con un reintento).

Escenario 3 — Nota crédito referenciando factura emitida en sandbox

Emitir primero una factura válida en sandbox y guardar su CUFE. Luego emitir una nota crédito referenciando ese CUFE. Este escenario confirma que el flujo de corrección funciona de extremo a extremo y que el sistema almacena el CUFE de forma accesible para cuando se necesite.

Escenario 4 — Rechazo por campo faltante o formato incorrecto

Provocar intencionalmente un rechazo enviando un documento con un campo obligatorio vacío (ej. descripción del ítem) o con formato incorrecto (ej. fecha en formato DD/MM/YYYY en lugar de YYYY-MM-DD). Este escenario confirma que el diagnóstico de errores funciona y que el mensaje al operador es accionable.

Verificar que: el código de error específico es retornado correctamente, el diagnóstico identifica el campo responsable, el mensaje al operador indica qué corregir (no solo que hubo un error).

Escenario 5 — Transición del endpoint sandbox a producción

Antes de solicitar acceso a producción, verificar que el flujo puede cambiar de endpoint sin modificar la lógica de negocio. El servidor MCP de sandbox y el de producción tienen la misma interfaz de herramientas — solo cambia la URL y las credenciales. Ese cambio debe ser de configuración, no de código.

El sandbox disponible para Colombia corresponde al servidor de Alanube. Las credenciales de prueba se obtienen al registrar la cuenta. Para la guía de conexión completa, ver Cómo conectar un agente de IA a la DIAN con MCP.

Lista de verificación antes de pasar a producción

Escenario 1 cubierto: emisión válida retorna CUFE en sandbox. Escenario 2 cubierto: el rechazo por NIT inválido es manejado sin excepción no controlada. Escenario 3 cubierto: nota crédito referenciando factura del sandbox funciona correctamente. Escenario 4 cubierto: el diagnóstico de campos faltantes retorna el campo responsable. Escenario 5 cubierto: cambio de endpoint sandbox → producción es de configuración, no de código. Logs configurados: todas las llamadas al servidor MCP se registran con código de error cuando aplica. Alertas definidas: tasa de rechazo > X% genera una notificación al equipo técnico.

Preguntas frecuentes

¿Cuánto tiempo debo dedicar a pruebas en sandbox antes de ir a producción?

Los cinco escenarios descritos en esta guía pueden cubrirse en una jornada de trabajo si el entorno de desarrollo está bien configurado. El tiempo real depende de cuántos casos de error específicos del negocio se quieran cubrir además de los básicos. Para un flujo de facturación estándar, una semana en sandbox es suficiente para tener confianza en el comportamiento del sistema.

¿Los datos emitidos en sandbox aparecen en los registros fiscales de la empresa?

No. El sandbox está completamente aislado del sistema fiscal real de la DIAN. Los CUFEs generados en sandbox no tienen validez legal y no aparecen en ningún reporte tributario. Los NITs de prueba tampoco corresponden a contribuyentes reales.

¿Qué diferencia hay entre un error en sandbox y el mismo error en producción?

El comportamiento del servidor MCP ante el error es idéntico — el mismo código, la misma estructura de respuesta. La diferencia está en las consecuencias: un error en sandbox no genera ninguna obligación fiscal, mientras que en producción puede requerir una nota crédito, una comunicación al receptor o un reporte a la DIAN dependiendo del tipo de documento y del momento en que se detecte el error.

¿Es posible acceder al sandbox sin haber completado el proceso de habilitación DIAN?

Depende del proveedor del servidor MCP. Algunos ofrecen acceso al sandbox con credenciales de prueba independientes del proceso de habilitación DIAN, lo que permite iniciar el desarrollo antes de completar los trámites fiscales. Verificar con el proveedor si el sandbox está disponible desde el momento del registro o si requiere habilitación previa.