Validación Asíncrona DGII para e-CF en República Dominicana: Flujo Técnico Completo
La validación asíncrona de la DGII significa que la respuesta de validación del e-CF no es inmediata. El flujo incluye un estado pendiente y la respuesta llega por webhook o consulta.
La DGII valida los e-CF de manera asincrónica: cuando el emisor transmite el documento, la respuesta inmediata no es la aprobación final sino un acuse de recibo con un identificador interno (TrackId). La aprobación o rechazo real llega después, consultándose mediante un endpoint específico. Conocer ese flujo completo es la diferencia entre una integración estable y una que pierde documentos en limbo cuando el acuse llega pero el estado final nunca se consulta.
Esta guía describe paso a paso el flujo técnico de validación asincrónica de la DGII en República Dominicana: autenticación, envío del XML firmado, recepción del acuse, consulta de estado mediante TrackId, manejo de respuestas posibles, y patrones recomendados para asegurar que ningún e-CF queda sin estado resuelto.
Por qué la DGII opera asincrónicamente
La DGII adoptó un modelo asincrónico para no bloquear el lado del emisor durante la validación y para dimensionar su infraestructura a volúmenes altos de e-CF concurrentes. La transmisión entra a una cola interna del sistema DGII; la validación (estructura XML, firma, reglas de negocio, catálogos) se ejecuta después y el resultado se publica para consulta. Esto permite que el emisor procese volúmenes altos sin esperar respuesta síncrona en cada transmisión.
Pasos del flujo completo
Paso 1 — Autenticación con la DGII
La autenticación usa el certificado digital del emisor para obtener un token de sesión contra el servidor de identidad de la DGII. El token tiene vigencia limitada (típicamente minutos) y se renueva proactivamente antes de expirar. Sin token válido en el header Authorization, los siguientes pasos devuelven 401.
Paso 2 — Construcción y firma del e-CF
El emisor construye el XML del e-CF según el esquema de la DGII para el tipo correspondiente (Tipo 31 crédito fiscal, Tipo 32 consumo, Tipo 33 nota débito, Tipo 34 nota crédito, etc.), calcula el CUDE según la fórmula oficial y aplica firma XAdES con su certificado. El XML resultante es lo que se transmite.
Paso 3 — Transmisión y recepción del acuse
El XML firmado se envía al endpoint de recepción de la DGII mediante POST. La respuesta inmediata es 202 (Accepted) acompañada del TrackId asignado al documento. Ese TrackId es la referencia que el emisor debe persistir y usar para consultar el estado final. El acuse confirma ingreso a cola de validación, no aprobación del contenido.
Paso 4 — Consulta del estado por TrackId
Para obtener el resultado de validación, el emisor consulta un endpoint específico de la DGII pasando el TrackId. La respuesta incluye el estado actual (en proceso, aceptado, rechazado, aceptado condicional) y, cuando es definitivo, el detalle del resultado. La consulta es idémpotente y puede ejecutarse varias veces sin efectos colaterales.
Paso 5 — Entrega al receptor y mensaje de aceptación
Una vez aceptado por la DGII, el e-CF puede entregarse al receptor (B2B mediante intercambio electrónico o por correo). Para Tipo 31, el receptor debe emitir mensaje de aceptación o rechazo dentro de los plazos legales. Ese mensaje cierra el ciclo del documento desde el lado del receptor y queda registrado en la DGII también.
Estados posibles del e-CF
Estados positivos
Aceptado significa que el e-CF pasó todas las validaciones y tiene plena validez fiscal. Aceptado condicional aplica cuando la DGII detectó inconsistencias menores que no invalidan el documento pero el emisor debe corregir en emisiones futuras. Ambos estados permiten que el documento se entregue al receptor con efectos fiscales completos.
Estados negativos
Rechazado significa que la validación encontró errores críticos en el contenido o la firma del e-CF, y el documento no tiene validez. El emisor debe corregir el problema y emitir un nuevo e-CF con un CUDE distinto (la DGII no permite reutilizar CUDE de un documento rechazado). En proceso significa que la validación aún no terminó y conviene reintentar la consulta después con backoff.
Para equipos que no quieren mantener manualmente la lógica de polling, gestión de tokens y manejo de TrackId, la API de facturación electrónica para República Dominicana de Alanube maneja el flujo completo del lado del servidor: el cliente envía el e-CF, Alanube se encarga del polling contra la DGII y notifica el resultado final vía webhook, reduciendo significativamente el código del lado del emisor.
Patrones recomendados de polling y reconciliación
Polling con backoff exponencial
Si el sistema implementa polling propio contra el endpoint de consulta, la práctica recomendada es backoff exponencial: primer intento a los 10 segundos, segundo a los 30 segundos, tercero al minuto, cuarto a los 5 minutos, hasta un límite máximo. Esto respeta los rate limits de la DGII y reduce carga innecesaria del lado del emisor. Para documentos que llevan horas en "en proceso", convocar revisión manual.
Persistencia del TrackId
Inmediatamente después del acuse de recibo, el sistema debe persistir el TrackId junto con el CUDE del e-CF y el estado pendiente. Si el sistema cae antes de consultar el estado final, debe poder retomar la consulta al reiniciarse. El TrackId es lo único que identifica el documento en la cola interna de la DGII; perderlo significa documento huérfano cuyo estado solo puede confirmarse después consultando por CUDE en endpoints alternativos.
Reconciliación periódica como red de seguridad
Adicional al polling activo, conviene un job programático (cada hora o cada turno laboral) que consulte el estado de todos los e-CF con estado pendiente y los actualice. Esto cubre los casos en que el polling activo se interrumpió por fallo del worker o por reinicio del servidor. La reconciliación periódica es red de seguridad, no mecanismo primario.
La documentación pública de Alanube incluye plantillas de polling con backoff exponencial y patrones de reconciliación periódica adaptados a la DGII, lo cual reduce el tiempo de implementación del manejo de estados intermedios y minimiza los documentos en limbo en producción.
Preguntas frecuentes
¿Cuál es la diferencia entre el acuse de recibo y la aceptación final de la DGII? El acuse de recibo confirma que la DGII recibió el e-CF físicamente y lo colocó en cola de validación; es una respuesta casi inmediata con un TrackId. La aceptación final ocurre después, cuando la DGII ejecuta la validación completa contra el esquema, las reglas de negocio y los catálogos vigentes, y determina si el documento es legalmente válido. Solo la aceptación final da validez tributaria al e-CF; el acuse de recibo es únicamente confirmación de ingreso. Confundir ambos genera registros erróneos: documentos marcados como válidos en el sistema que en realidad fueron rechazados después.
¿Cómo puede asegurar que ningún e-CF queda en estado pendiente indefinidamente? Combinando tres mecanismos. Primero: polling activo con backoff exponencial inmediatamente después del envío hasta obtener estado final. Segundo: persistencia del TrackId y del CUDE en la base de datos para que un reinicio del sistema no pierda la referencia. Tercero: job de reconciliación periódica que consulta todos los pendientes y los actualiza. Adicional, conviene una alerta automática para documentos que pasan más de cierto tiempo en estado pendiente — típicamente algunas horas — que dispare revisión manual.
¿Qué diferencia hay entre rechazo por error sintáctico y rechazo por error de negocio en la DGII? El rechazo por error sintáctico se produce cuando el XML no cumple el esquema oficial: estructura malformada, elementos faltantes, namespaces incorrectos. Aparece en el primer paso de validación, antes de evaluar reglas de negocio. El rechazo por error de negocio se produce cuando el XML sí cumple el esquema pero las reglas tributarias detectan inconsistencias: cálculo de ITBIS incorrecto, código de tarifa fuera del catálogo, receptor con RNC inválido. El primero apunta al constructor del XML; el segundo apunta al contenido o a los datos del receptor.
¿Es posible reenviar un e-CF rechazado sin generar duplicados? La DGII identifica e-CF por CUDE único. Reenviar un e-CF con el mismo CUDE de uno rechazado puede ser permitido o rechazado según las políticas vigentes de la DGII. La práctica más segura es emitir un nuevo e-CF con CUDE distinto y datos corregidos, registrando internamente la referencia al e-CF rechazado original para auditoría. Para errores técnicos (timeout, 5xx), antes de reenviar conviene consultar el estado por TrackId del intento original: es posible que el documento sí haya llegado y esté en cola, en cuyo caso un reenvío generaría duplicado.
Artículos Relacionados
Los 10 tipos de comprobantes fiscales electrónicos (e-CF) en República Dominicana: cuándo usar cada uno
Referencia práctica de los 10 tipos de comprobantes fiscales electrónicos en República Dominicana: código, caso de uso, flujo de emisión (síncrono o asíncrono) e implicaciones técnicas para developers e integradores.
Cuánto tiempo toma integrar la API de facturación electrónica de la DGII: benchmark por método
Desglose honesto del tiempo de integración de la API de facturación electrónica de la DGII por etapa: lectura de documentación, construcción de payloads, manejo de estados y diagnóstico de rechazos. Comparativa REST vs MCP con estimaciones transparentes.
Errores de rechazo de la DGII en e-CF: cómo diagnosticarlos y corregirlos desde un agente de IA
Los rechazos de la DGII en e-CF tienen causas precisas y acciones correctivas definidas. Esta guía explica el ciclo de vida del documento, los códigos de error más frecuentes y cómo un agente de IA puede diagnosticar y corregir rechazos de forma autónoma.