Sandbox de APIs de facturación electrónica en LATAM: qué debe simular y cómo probarlo

El sandbox de un proveedor de API de facturación electrónica es el primer filtro para evaluar si esa integración sobrevivirá al primer mes en producción. El problema es que la mayoría de los sandboxes en el mercado LATAM son entornos de demostración que aceptan casi cualquier documento bien formado y devuelven un identificador simulado. Eso no es un sandbox útil — es un entorno de marketing.

Esta guía describe qué debe simular un sandbox real en los cuatro mercados principales de la región — Colombia (DIAN), República Dominicana (DGII), Panamá (DGI) y Costa Rica (Ministerio de Hacienda) — y cómo probarlo con pruebas concretas que cualquier equipo de desarrollo puede ejecutar en menos de una hora.

Qué diferencia un sandbox real de uno de demostración

Un sandbox de demostración acepta cualquier documento válido según el esquema del proveedor y devuelve un identificador simulado (CUFE, NCF, CAFE, clave numérica). No valida los datos del emisor o receptor contra registros reales de la autoridad fiscal, no simula rechazos con códigos reales de la autoridad y no reproduce el comportamiento asíncrono cuando la autoridad fiscal procesa en diferido.

Un sandbox real conecta con el ambiente de pruebas de la autoridad fiscal del país, transmite el documento exactamente como lo haría en producción y devuelve los mismos códigos de error que la autoridad usaría para rechazar un documento mal formado. La diferencia es que los identificadores generados no tienen validez fiscal.

Sandbox en Colombia — DIAN

Colombia usa validación previa síncrona: la DIAN responde en el mismo request de transmisión. El sandbox debe reproducir ese flujo completo, incluyendo la firma XAdES-BES del XML y la transmisión al ambiente de habilitación de la DIAN. El CUFE de prueba generado debe seguir el mismo algoritmo SHA-384 que el CUFE de producción.

Pruebas de rechazo específicas para el sandbox Colombia

// Prueba 1: NIT emisor con dígito de verificación incorrecto
{ "issuer": { "taxId": "900000000-9" } }
// Esperado: rechazo DIAN con código de error en campo taxId

// Prueba 2: CUFE de Nota Crédito referenciando factura inexistente
{ "relatedInvoice": { "cufe": "000...000" } }
// Esperado: rechazo por referencia no encontrada

// Prueba 3: Tipo de documento 01 con fecha fuera del período fiscal
{ "issueDate": "2010-01-01" }
// Esperado: rechazo por fecha fuera de rango válido

// Prueba 4: Monto de IVA inconsistente con la tarifa declarada
{ "taxAmount": 100, "taxRate": 19, "subtotal": 1000 }
// IVA correcto sería 190 — Esperado: rechazo por inconsistencia fiscal

Sandbox en República Dominicana — DGII

La DGII usa validación asíncrona. El sandbox debe simular ese comportamiento: el documento se envía y el estado inicial debe ser “pending”. Después, la respuesta definitiva llega vía webhook o polling. Un sandbox que devuelve “accepted” en el mismo POST no está simulando el comportamiento real de la DGII y no prepara al equipo para gestionar el estado asíncrono en producción.

Pruebas de rechazo específicas para el sandbox RD

// Prueba 1: RNC del emisor no registrado en DGII
{ "issuer": { "rnc": "000000000" } }
// Esperado: rechazo async con código DGII de RNC inválido

// Prueba 2: NCF fuera del rango autorizado
{ "ncf": "E310999999999" }
// Esperado: rechazo por NCF fuera del rango aprobado

// Prueba 3: Tipo e-31 con comprador sin RNC
{ "type": "e-31", "buyer": { "rnc": null } }
// Esperado: rechazo por RNC obligatorio en Crédito Fiscal

// Prueba 4: Verificar que status inicial sea pending
POST /v1/ecf -> { "status": "pending" }  // CORRECTO
POST /v1/ecf -> { "status": "accepted" } // RED FLAG

Sandbox en Panamá — DGI y SFEP

El SFEP de Panamá genera un CAFE por cada factura aceptada. El sandbox debe conectar con el ambiente de pruebas de la DGI y generar CAFEs de prueba siguiendo el mismo flujo que producción. Un sandbox que genera códigos locales sin transmitir a la DGI no permite detectar los rechazos que la DGI aplica por RUC inválido, monto incorrecto o tipo de documento mal configurado.

Pruebas de rechazo específicas para el sandbox Panamá

// Prueba 1: RUC del emisor con formato incorrecto
{ "issuer": { "ruc": "0-00-0000" } }
// Esperado: rechazo por RUC inválido antes de transmitir a DGI

// Prueba 2: Factura tipo 01 (B2B) sin RUC del receptor
{ "type": "01", "receiver": { "ruc": null } }
// Esperado: rechazo por RUC receptor obligatorio en tipo 01

// Prueba 3: Verificar que el CAFE esté presente en la respuesta
POST /v1/invoices -> { "cafe": "<código>" }  // CORRECTO
POST /v1/invoices -> { "cafe": null }          // RED FLAG

Sandbox en Costa Rica — Ministerio de Hacienda y ATV

Costa Rica requiere que el comprobante se transmita al ATV con la firma digital del emisor. El sandbox debe simular ese flujo: recibir el certificado del emisor, firmar el XML y transmitirlo al ATV de pruebas de Hacienda. La respuesta debe incluir el campo ind-estado (aceptado, aceptado-parcial o rechazado) y la clave numérica de 50 dígitos.

Pruebas de rechazo específicas para el sandbox Costa Rica

// Prueba 1: Cédula del emisor con formato incorrecto
{ "issuer": { "cedula": "0000000000" } }
// Esperado: rechazo con mensaje sobre formato inválido de cédula

// Prueba 2: Monto de impuesto inconsistente con la tarifa
{ "taxRate": 13, "taxAmount": 5, "subtotal": 100 }
// IVA correcto sería 13 — Esperado: rechazo o advertencia

// Prueba 3: Verificar que la respuesta incluya ind-estado de Hacienda
// CORRECTO: { "haciendaResponse": { "ind-estado": "aceptado" } }
// RED FLAG: { "status": "ok" } sin ind-estado de Hacienda

Cómo evaluar el sandbox en menos de una hora

El protocolo para evaluar cualquier sandbox de facturación en LATAM: primero, solicitar acceso sin pasar por ventas — si el proveedor requiere una demo para dar acceso al sandbox, ese es el primer dato. Segundo, ejecutar una emisión exitosa y verificar que la respuesta incluya el identificador fiscal real del país (CUFE, NCF, CAFE o clave numérica). Tercero, ejecutar los rechazos intencionales descritos en esta guía para el país correspondiente. Cuarto, evaluar la calidad de los mensajes de error devueltos.

Preguntas frecuentes

¿Cuál es la diferencia entre el sandbox y el ambiente de habilitación de la DIAN en Colombia?

El ambiente de habilitación de la DIAN es el entorno oficial de pruebas que la misma DIAN provee para que los Proveedores Tecnológicos certifiquen su integración. El sandbox del proveedor es el entorno que ese proveedor expone a sus clientes (los ISVs) para que puedan probar la integración vía API sin acceder directamente a los sistemas de la DIAN. Un sandbox de calidad conecta internamente con el ambiente de habilitación DIAN; uno de baja calidad simula las respuestas localmente sin transmitir a la DIAN.

¿Cómo puedo saber si el sandbox del proveedor conecta realmente con la autoridad fiscal?

La prueba más confiable es enviar un documento con un NIT, RNC, RUC o cédula inválidos del emisor. Si el sandbox los rechaza con un código específico de la autoridad fiscal, está transmitiendo. Si los acepta o devuelve un error genérico, está validando localmente. Otra señal: preguntar al proveedor si el sandbox conecta con el ambiente de pruebas oficial de la autoridad fiscal del país. Un proveedor que no puede responder esa pregunta con claridad probablemente no conecta.

¿Qué diferencia hay entre un rechazo de sandbox y un rechazo en producción?

En un sandbox real, los rechazos deben ser idénticos en tipo y código a los que ocurrirían en producción. La única diferencia es que los documentos aceptados no tienen validez fiscal. En un sandbox de demostración, los rechazos son generados por la lógica del proveedor sin conectar con la autoridad fiscal, lo que significa que puede haber rechazos de producción que el sandbox nunca reprodujo. El primer rechazo de ese tipo siempre aparece en producción, no en el sandbox.

¿Es posible usar un sandbox multi-país para probar integraciones de Colombia, RD, Panamá y Costa Rica desde un solo endpoint?

Algunos proveedores ofrecen un sandbox unificado donde el país se especifica como parámetro. Eso es válido siempre que el sandbox conecte internamente con el ambiente de pruebas de cada autoridad fiscal por separado. Un sandbox unificado que simula todas las respuestas localmente sin conectar con ninguna autoridad es igual de limitado que cuatro sandboxes de demostración. La prueba es la misma: ejecutar los rechazos intencionales para cada país y verificar que los códigos de error correspondan con los de la autoridad fiscal respectiva.

Esta guía de sandbox es parte del cluster de evaluación de proveedores. Para el marco completo de criterios, consulta los 5 criterios técnicos para LATAM. Para checklists específicos: Colombia, República Dominicana, Panamá y Costa Rica.