Ambiente de Pruebas DIAN: Cómo Usar el Sandbox

El sandbox de la DIAN es donde una integración debe vivir el tiempo suficiente para descubrir todos los rechazos posibles antes de tocar producción — pero también es donde más equipos cometen el error de probar solo el camino feliz y descubrir, semanas después, que el código no maneja correctamente los escenarios reales que aparecen en producción con volúmenes más altos.

Esta guía explica qué es exactamente el sandbox DIAN, qué endpoints expone, cuáles son las diferencias clave con producción que conviene conocer, qué set mínimo de pruebas cubrir antes de migrar, y los errores frecuentes que aparecen al pasar de sandbox a producción y cómo prevenirlos.

Qué es el sandbox DIAN y cómo se accede

Ambiente de habilitación: definición oficial

El sandbox oficialmente se denomina ambiente de habilitación en la nomenclatura DIAN. Es un entorno funcionalmente idéntico a producción pero aislado: los documentos emitidos en él no tienen validez legal, no afectan la contabilidad fiscal y no se registran en el repositorio público. Sirve para validar que el sistema emisor construye correctamente los documentos antes de transmitir en producción.

Endpoints y URL base

Los endpoints del sandbox tienen una URL base distinta a producción. La práctica recomendada es configurar la URL base mediante variable de entorno separada por ambiente, junto con la clave técnica del software, el certificado del firmante y el flag TipoAmb del CUFE. Así, cambiar de ambiente es modificar variables, no código.

Diferencias clave entre sandbox y producción

Adquiriente sintético vs adquiriente real

En sandbox, los adquirientes son ficticios: el NIT sintético (típicamente 222222222222) que la DIAN tiene reservado para pruebas. Usar un adquiriente real en sandbox — incluso el propio NIT — dispara rechazo por intento de operación real en ambiente de pruebas. En producción ocurre lo contrario: el NIT sintético es rechazado porque no corresponde a contribuyente registrado.

Clave técnica distinta por ambiente

La DIAN entrega dos claves técnicas durante la habilitación: una para sandbox, otra para producción. La clave entra en el cálculo del CUFE. Olvidar cambiar la clave al migrar a producción es el error más frecuente de rotación: la facturación se rechaza con FAB14b porque el CUFE está calculado con la clave incorrecta. Configurar ambas claves como variables de entorno separadas evita el problema.

Rangos de numeración independientes

El rango de numeración autorizado para sandbox es amplio y no consume cuota de producción. El rango de producción está limitado por resolución DIAN con vigencia específica. Al migrar, el contador interno de números emitidos debe resetearse o gestionarse separadamente; reutilizar la secuencia de sandbox en producción suele violar el rango autorizado vigente.

Set de pruebas recomendado antes de producción

Set mínimo exigido por DIAN

Las pruebas obligatorias DIAN cubren factura básica, factura con descuento global, factura con múltiples impuestos, nota crédito asociada y nota débito. Estos son los mínimos que la DIAN valida antes de aprobar el paso a producción. La aprobación del set es requisito formal pero no garantiza que la integración sea robusta para volúmenes reales.

Set adicional recomendado para robustez

Adicional al set DIAN, conviene cubrir: factura con muchas líneas (50+), factura con base imponible próxima a cero, factura con dígitos significativos en decimales (riesgo de redondeo), rechazo simulado por error de cálculo, escenario de servidor DIAN caído (modo contingencia), consulta de estado por CUFE de documento aprobado y de documento rechazado, y manejo del rate limit del endpoint sandbox cuando se hacen pruebas de carga.

Migración correcta de sandbox a producción

Checklist de cambios al migrar

El checklist mínimo de migración incluye cuatro cambios: URL base del endpoint (de sandbox a producción), clave técnica (de sandbox a producción), flag TipoAmb en el CUFE (de "2" a "1"), y rangos de numeración autorizados (los de producción son distintos a los de sandbox). Cualquiera de los cuatro olvidados produce rechazo del primer envío en producción.

Estrategia de paso gradual

La práctica recomendada es transmitir el primer documento de producción a bajo valor y a un adquiriente conocido (la propia empresa o un proveedor cercano). Verificado el flujo completo — emisión, aprobación, entrega al adquiriente, consulta de estado — escalar al volumen normal. Saltarse el paso gradual es la causa más común de incidentes en las primeras horas de producción.

Errores comunes al pasar a producción

Clave técnica no rotada

El código sigue calculando el CUFE con la clave de sandbox al migrar. La DIAN rechaza todos los documentos con FAB14b porque el CUFE no coincide con el que ella recalcula con la clave correcta de producción. Diagnostico: comparar la cadena hasheada con lo que la DIAN espera. Prevención: configurar la clave por variable de entorno y validar el smoke test en cada deploy a producción.

Adquiriente sintético que sobrevivió a la migración

Casos donde el sistema de pruebas quedó mezclado con el de producción y un par de facturas reales se emitieron al NIT sintético. La DIAN rechaza con error de adquiriente desconocido. Prevención: separar completamente los datos de prueba de los de producción, validar el NIT del adquiriente contra catálogo antes de transmitir.

Preguntas frecuentes

¿Cuál es la diferencia entre el sandbox DIAN y el sandbox del proveedor tecnológico? Son dos ambientes distintos. El sandbox DIAN es el ambiente oficial de habilitación donde la DIAN valida documentos sintéticos antes de aprobar el paso a producción. El sandbox del PT es un entorno propio del proveedor que puede o no estar conectado al sandbox DIAN. En PT serios, el sandbox propio se conecta efectivamente al sandbox DIAN — lo cual significa que las pruebas viajan al validador real y se reciben las respuestas reales. En PTs menos maduros, el sandbox del PT puede ser solo un mock local sin conexión al validador, lo cual hace que las pruebas no detecten errores que aparecerían en producción.

¿Cómo puedo verificar que mi integración está lista para producción sin riesgo de rechazo en el primer envío? Tres validaciones mínimas. Primera: recalcular localmente el CUFE de la última factura emitida en sandbox con la clave técnica de producción y confirmar que el código produce el resultado esperado. Segunda: emitir una factura de prueba a un adquiriente real conocido (la propia empresa) por bajo valor en producción y verificar aprobación DIAN antes de habilitar tráfico. Tercera: configurar alertas automáticas sobre el primer día de producción (cualquier rechazo dispara notificación inmediata) en lugar de esperar al monitoreo regular.

¿Qué diferencia hay entre el rate limit del sandbox y el de producción? El rate limit del sandbox DIAN suele ser más estricto que el de producción porque el ambiente está dimensionado para pruebas, no para volúmenes reales. Esto puede llevar a falsos positivos: una prueba de carga que satura el sandbox no necesariamente saturaría producción. Para pruebas de carga realistas, conviene coordinar con la DIAN o con el PT una ventana de prueba con límites específicos, o realizar las pruebas en producción con volumen creciente bajo monitoreo cercano, lo cual es habitual en migraciones de empresas con volumen alto.

¿Es posible mantener sandbox y producción corriendo en paralelo después de la habilitación? Sí y es lo recomendado. Mantener un environment de sandbox activo después del paso a producción permite probar cambios de código (refactors, optimizaciones, nuevos casos de uso) sin riesgo en producción. La práctica estándar es mantener tres ambientes en paralelo: desarrollo local con mocks, sandbox DIAN para pruebas integradas, y producción. Cada release nuevo cruza primero por sandbox real antes de habilitarse en producción, lo cual cubre los casos en que un cambio aparentemente trivial rompe alguna parte del cálculo del CUFE o de la firma.

Ambiente de Pruebas DIAN: Cómo Usar el Sandbox para Factura Electrónica