Webhooks y respuestas asíncronas en la integración e-CF DGII República Dominicana

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

El e-CF fue transmitido. La DGII devuelve HTTP 200 con un acuse de recibo. Pero la respuesta definitiva — el documento Aceptado o Rechazado — no llega inmediatamente. El sistema del ISV tiene que decidir: ¿espóll en un loop hasta obtener respuesta? ¿espera un webhook que quizás nunca llegue? ¿bloquea el hilo hasta confirmar el estado? El manejo de respuestas asíncronas de la DGII es uno de los aspectos más subestimados del diseño de la integración y uno de los que más impacta la experiencia del usuario final.

Esta guía cubre el modelo de respuesta de la DGII, las estrategias de polling y notificación, el diseño de colas de trabajo para procesar respuestas, y cómo gestionar los casos de error de red sin duplicar documentos ni perder acuses de recibo.

El modelo de respuesta de la DGII: síncrona vs asíncrona

La DGII opera con un modelo mixto dependiendo del volumen y condiciones del sistema. Para documentos individuales en condiciones normales, la DGII puede retornar la respuesta definitiva (Aceptado/Rechazado) en la misma respuesta HTTP del POST de transmisión, dentro de los primeros 5-30 segundos. Para envíos en lote o cuando la DGII está bajo carga, retorna un acuse de recibo provisional con el código de rastreo del documento, y la respuesta definitiva debe consultarse posteriormente mediante polling.

El sistema del ISV debe estar diseñado para manejar ambos casos: procesar la respuesta definitiva si viene en el response inicial, o almacenar el código de rastreo y encolar la consulta de estado si la respuesta es provisional. Diseñar el sistema solo para el caso síncrono es una fuente segura de problemas en producción durante picos de carga.

Estrategia de polling: frecuencia y límites

Cuando la respuesta es asíncrona, el sistema debe consultar el estado del e-CF usando el endpoint de consulta de la DGII con el código de rastreo. La frecuencia de polling debe ser controlada para no saturar la API DGII y para no penalizar la experiencia del usuario. La estrategia recomendada es backoff exponencial con jitter: primera consulta a los 3 segundos, luego 10s, 30s, 90s, 180s, hasta un máximo de 5 consultas. Si al quinto intento el estado sigue siendo pendiente, el documento pasa a un estado de 'pendiente de revisión manual' y se genera una alerta operativa.

import asyncio
import random
from enum import Enum

class EstadoECF(Enum):
    PENDIENTE = 'pendiente'
    ACEPTADO = 'aceptado'
    ACEPTADO_CONDICIONALMENTE = 'aceptado_condicionalmente'
    RECHAZADO = 'rechazado'
    ERROR_RED = 'error_red'

async def consultar_estado_con_backoff(
    codigo_rastreo: str,
    dgii_client,
    max_intentos: int = 5
) -> EstadoECF:
    intervalos = [3, 10, 30, 90, 180]  # segundos
    
    for intento, intervalo in enumerate(intervalos[:max_intentos]):
        await asyncio.sleep(intervalo + random.uniform(0, 2))  # jitter
        
        try:
            estado = await dgii_client.consultar_estado(codigo_rastreo)
            if estado != EstadoECF.PENDIENTE:
                return estado
        except Exception as e:
            if intento == max_intentos - 1:
                return EstadoECF.ERROR_RED
    
    # Agotar reintentos sin respuesta definitiva
    return EstadoECF.PENDIENTE  # escalar a revisión manual

Diseño de la cola de trabajo para respuestas DGII

Para sistemas con volúmenes medianos o altos (más de 100 e-CF por día), el polling en el hilo de la solicitud original bloquea recursos y degrada la experiencia del usuario. La arquitectura recomendada separa el proceso en dos etapas: la API del ISV envía el e-CF a la DGII, recibe el acuse de recibo, almacena el código de rastreo en base de datos con estado PENDIENTE, y responde al usuario con el estado provisional. Un worker asíncrono independiente consume la cola de documentos pendientes, consulta el estado en la DGII con backoff exponencial, y actualiza el estado en base de datos cuando la DGII retorna la respuesta definitiva.

El sistema de estados en base de datos debe incluir: eNCF (identificador del comprobante), codigo_rastreo (retornado por DGII en el acuse), estado_dgii (PENDIENTE / ACEPTADO / ACEPTADO_CONDICIONALMENTE / RECHAZADO), intentos_polling (contador de consultas realizadas), ultimo_intento_at (timestamp), y respuesta_dgii_raw (XML o JSON de la respuesta definitiva, para auditoría).

Manejo de errores de red sin duplicar documentos

El escenario más crítico es el timeout de red durante la transmisión: el sistema no sabe si la DGII recibió el documento o no. Retransmitir el mismo e-CF con el mismo eNCF puede resultar en un rechazo por duplicado si la DGII sí lo recibió. El protocolo correcto es: ante un timeout de transmisión, consultar el estado por código de rastreo o eNCF antes de retransmitir. Si la DGII retorna un estado para ese eNCF, el documento fue recibido y no debe retransmitirse. Solo si la DGII retorna 'documento no encontrado' se debe retransmitir.

Notificaciones al usuario final: UX del estado del e-CF

El usuario del software del ISV necesita saber si su factura fue aceptada. Mientras la respuesta DGII está pendiente, el sistema debe mostrar un estado intermedio claro: 'Enviada, pendiente de confirmación DGII'. Cuando la respuesta llega, el estado debe actualizarse en tiempo real o en la próxima carga de la página, con diferenciación visual clara entre Aceptada, Aceptada con Observaciones y Rechazada. Para rechazos, mostrar el código de error y una descripción comprensible del problema — no el código DGII crudo, que es técnico y no orientado al usuario final.

Preguntas frecuentes

¿Cuál es el tiempo máximo de espera para una respuesta definitiva de la DGII?

La DGII no publica un SLA oficial de tiempo de respuesta para e-CF. En condiciones normales de producción, la respuesta definitiva llega en menos de 60 segundos para documentos individuales. Durante picos de carga fiscal (vencimientos de declaraciones, cierres de mes), el tiempo puede extenderse a varios minutos. Diseñar la integración con polling de hasta 10 minutos antes de escalar a revisión manual cubre la mayoría de los escenarios de carga alta.

¿Cómo puedo implementar notificaciones en tiempo real al usuario cuando la DGII acepta el e-CF?

El patrón recomendado combina WebSockets (o Server-Sent Events) para la notificación en tiempo real al frontend, con un worker asíncrono en el backend que actualiza la base de datos cuando la DGII retorna la respuesta definitiva. Cuando el worker actualiza el estado del e-CF, emite un evento al canal WebSocket del usuario correspondiente. Si el usuario no está conectado al momento, el estado actualizado se muestra en la próxima carga de la vista de facturas.

¿Qué diferencia hay entre el acuse de recibo y la respuesta definitiva de la DGII?

El acuse de recibo (respuesta inmediata al POST de transmisión) confirma que la DGII recibió el documento y le asignó un código de rastreo. No implica aceptación fiscal. La respuesta definitiva es el documento XML retornado por la DGII con el estado final: Aceptado, Aceptado Condicionalmente o Rechazado, firmado digitalmente por la DGII. Solo la respuesta definitiva tiene valor fiscal y debe almacenarse como soporte tributario.

¿Es posible configurar un webhook en la DGII para recibir notificaciones push cuando el e-CF es procesado?

La DGII no ofrece un mecanismo de webhooks push nativos en el que el sistema del ISV reciba una notificación HTTP cuando el e-CF es procesado. El modelo es de polling: el ISV debe consultar activamente el estado usando el endpoint de consulta. Algunos proveedores de API de facturación electrónica sí ofrecen webhooks propios que internamente hacen el polling a la DGII y notifican al ISV cuando hay una respuesta definitiva, abstraindo esta complejidad.

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.