Flujo Técnico de Transmisión al DGI en Panamá a través del PAC: Paso a Paso
Guía técnica del flujo de transmisión de documentos al DGI en Panamá a través del PAC: endpoints, autenticación y estados de respuesta.
Una de las preguntas que más recibe el equipo de un PAC cuando un cliente nuevo va a integrar SFEP en Panamá es: ¿qué le pasa al XML después de que yo lo envío? El flujo entre emisor, PAC y DGI no está documentado de manera lineal en un solo lugar oficial, y eso causa confusión cuando se trata de manejar errores o reintentos en producción. Diagnosticar un rechazo sin entender el flujo completo suele costar días en lugar de horas.
Esta guía describe el flujo técnico completo paso a paso: qué hace el emisor, qué hace el PAC, qué hace la DGI, en qué punto se genera el CUFE, cómo se gestiona el estado asíncrono, qué hay que hacer cuando algo falla y qué patrones conviene implementar del lado del cliente para que la integración sea robusta. Lo cuento desde lo que verás en logs reales.
Visión general del flujo SFEP
Cuatro actores en el flujo
El flujo extremo a extremo tiene cuatro actores: el sistema del emisor (tu ERP o facturador), el PAC habilitado por la DGI, la DGI como ente fiscal, y el receptor final del documento. La transmisión al ente fiscal ocurre exclusivamente del PAC a la DGI —tu sistema nunca habla directo con la DGI bajo el modelo SFEP. Esa restricción es deliberada y centraliza el control de calidad de las emisiones.
Modelo asíncrono y validez fiscal
El SFEP usa modelo asíncrono: el emisor envía y recibe un acuse inmediato, pero la validez fiscal del documento solo se confirma después de que la DGI lo procese y devuelva respuesta de autorización. Esta característica define cómo deben diseñarse las colas, webhooks y reintentos del lado del cliente.
Paso 1: Construcción del XML en el emisor
Generación contra XSD oficial
Tu sistema arma el XML del documento conforme al XSD oficial publicado por la DGI. Esto incluye datos del emisor (RUC, código de actividad), datos del receptor cuando aplica (RUC o cédula), ítems con sus códigos del catálogo, cálculos de ITBMS, totales y la información complementaria según el tipo de documento.
Validación local previa
La validación contra el XSD se recomienda hacerla del lado del emisor antes de enviar al PAC. Esto evita viajes innecesarios por errores sintácticos básicos (campos mal tipados, atributos faltantes). Las librerías XML estándar de cada lenguaje (lxml en Python, xmllint en CLI, equivalentes en Node y Go) permiten esa validación en milisegundos.
Paso 2: Firma digital del XML
XAdES-BES con canonicalización C14N Exclusive
El XML se firma con XAdES-BES utilizando el certificado emitido por entidad habilitada por la AIG. La firma se calcula sobre el documento canonicalizado con C14N Exclusive y se embebe dentro del XML en el bloque Signature. El algoritmo es RSA-SHA256 y el certificado X.509 se incluye en KeyInfo.
Firma local vs firma delegada al PAC
Hay dos modelos. Firma local: el cliente firma con su certificado en su infraestructura y envía el XML ya firmado al PAC. Firma delegada: el cliente carga su certificado en la bóveda del PAC y el PAC firma en su nombre vía API. Para la mayoría de SaaS modernos, firma delegada elimina la necesidad de mantener librerías XAdES en producción.
Paso 3: Envío al PAC
Endpoint REST con autenticación Bearer
El XML (firmado o sin firmar según el modelo) se envía al endpoint del PAC. En un PAC moderno con API REST, típicamente es un POST sobre HTTPS con autenticación Bearer token o API key. El payload puede ser el XML directamente o un JSON que el PAC convierte internamente al XML correspondiente.
Respuesta síncrona con TrackId
La respuesta síncrona del PAC contiene un TrackId que identifica esta transmisión y un estado preliminar (recibido, en proceso). Este TrackId es la referencia operativa para consultas posteriores, webhooks y eventuales reintentos. Conviene persistirlo en la base de datos del cliente desde el primer momento.
Paso 4: Validación del PAC
Validaciones técnicas que ejecuta el PAC
El PAC ejecuta validaciones técnicas: estructura XSD, firma digital, cálculos de ITBMS, catálogos (formas de pago, tipos de documento, códigos de departamento), referencias cruzadas (CUFE de documento padre en notas), y reglas de negocio específicas de la DGI. Si alguna falla, el PAC rechaza antes de enviar a la DGI, devolviendo código y descripción del error tipificado.
Asignación del CUFE
Si las validaciones pasan, el PAC calcula y asigna el CUFE (40 caracteres) tomando como insumo el RUC emisor, fecha, número de documento, monto y demás campos críticos según el algoritmo definido por la DGI. El CUFE queda inmutable: cualquier modificación posterior implicaría un CUFE distinto y por tanto otro documento.
Paso 5: Transmisión a la DGI
Webservice oficial DGI
El PAC envía el XML con el CUFE incluido a los sistemas de la DGI vía webservice oficial. La DGI registra el documento en su repositorio fiscal y devuelve un acuse de recibo con timestamp. Esta es la transmisión que confiere validez fiscal al documento; sin ella, el documento es solo un draft interno.
Estado autorizado y respuesta al PAC
La DGI procesa el documento de forma asíncrona y devuelve uno de tres estados al PAC: autorizado (validez fiscal completa), rechazado (con detalle del problema) o condicional (autorizado provisionalmente con observaciones). El PAC propaga este estado al cliente vía webhook o disponible para consulta.
Paso 6: Respuesta al emisor
Webhook configurado por evento
El PAC retorna al emisor el XML autorizado (con CUFE y firma del PAC si aplica), el timestamp de DGI y el PDF de representación estándar para entregar al receptor. En APIs modernas, este paso es asíncrono y se entrega vía webhook HTTP REST al endpoint que el emisor configuró en su panel del PAC.
Polling como alternativa o respaldo
Como alternativa o respaldo del webhook, el cliente puede hacer polling sobre GET /documents/{trackId}. Es útil cuando el webhook no llegó por incidencia de red o como mecanismo de reconciliación diaria. No conviene usarlo como mecanismo primario en alto volumen.
Manejo de estados y reintentos en el cliente
Estados típicos del documento
Los estados típicos son: recibido (PAC aceptó el envio), en_validacion (validaciones técnicas en curso), validado (pasó validaciones, listo para transmisión DGI), transmitido (entregado a DGI), autorizado (DGI confirmó recepción), rechazado (validación o DGI lo negó), condicional (DGI lo autorizó con observaciones).
Idempotencia por TrackId externo
Para que los reintentos sean seguros, todo PAC moderno acepta un TrackId externo único por documento (UUID en el header HTTP) y lo usa como clave de idempotencia. Reintentos con el mismo TrackId externo no generan duplicación. Alanube implementa este patrón desde su primer endpoint, lo cual reduce significativamente el riesgo en alto volumen.
Tiempos esperados y SLA en cada paso
Latencia típica en operación normal
En operación normal, un documento completa el flujo en 2-10 segundos: ~100ms envío y validación del PAC, 1-3s asignación CUFE, 1-7s transmisión DGI. La latencia mayor proviene de la DGI cuando está bajo carga; el PAC tiene control limitado sobre ese factor.
Métricas P95/P99 publicadas
PACs maduros publican métricas de latencia P95 y P99 contra DGI productivo, lo cual permite a los integradores dimensionar SLA realista para sus clientes finales. Alanube en Panamá expone esos números en dashboard público, lo cual facilita el dimensionamiento de capacidad.
Preguntas frecuentes
¿Cuál es el canal válido de transmisión al DGI en el modelo SFEP? Bajo el modelo SFEP, el único canal válido de transmisión a la DGI es a través de un PAC habilitado. La DGI no expone endpoints públicos para que el contribuyente envíe directamente. Esta arquitectura es una decisión deliberada de la DGI: el PAC actúa como filtro de calidad y validación previa, evitando que el ente fiscal reciba documentos malformados. Si un proveedor afirma transmitir sin PAC al modelo SFEP, está incumpliendo la normativa vigente y la DGI puede invalidar los documentos.
¿Cómo puedo manejar correctamente reintentos cuando un documento no recibe respuesta del PAC? La práctica correcta es: usar un TrackId externo único por documento (UUID en el header HTTP), y reintentar con el mismo TrackId. El PAC reconoce el reintento por idempotencia y retorna el estado actual del documento original sin crear duplicado. Implementar también backoff exponencial entre reintentos (1s, 2s, 4s, 8s, 16s) para no saturar el endpoint en escenarios de degradación. Si tras 5 reintentos no hay respuesta exitosa, alertar al equipo operativo para revisión manual.
¿Qué diferencia hay entre el estado validado por el PAC y autorizado por la DGI? Validado significa que el PAC pasó sus controles técnicos (estructura XSD, firma, cálculos, catálogos) y el documento está listo para transmitir a la DGI. Autorizado significa que la DGI recibió, procesó y confirmó el documento en su repositorio fiscal. El documento adquiere validez fiscal solo cuando está en estado autorizado. Si tu sistema entrega el PDF al cliente cuando está solo validado pero la DGI luego rechaza, tienes una factura no válida en manos del cliente —situación a evitar.
¿Es posible que el PAC esté caído cuando necesito facturar? Sí puede ocurrir aunque es infrecuente en PACs maduros. Un buen PAC tiene alta disponibilidad (99.9%+) y replica geográfica. Además, la mayoría permite emisión en contingencia: el emisor sigue generando documentos localmente con un número secuencial reservado, y al recuperarse el servicio el PAC los transmite en lote a la DGI. La DGI acepta este modo de contingencia siempre que se transmita dentro del plazo razonable (típicamente 24-48 horas), regulado por resolución DGI específica.
Artículos Relacionados
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.
Cómo conectar un agente de IA a la DGII en República Dominicana: guía paso a paso con el MCP de Alanube
Guía completa para conectar un agente de IA a la DGII de República Dominicana usando el único servidor MCP de infraestructura fiscal disponible actualmente: configuración del cliente, primer e-CF en lenguaje natural y emisión programática con TypeScript.
Las 30 herramientas del MCP de infraestructura fiscal de República Dominicana: referencia completa
Referencia consolidada en español de las 30 herramientas del único servidor MCP de infraestructura fiscal conectado a la DGII en República Dominicana: organización por capas, casos de uso y cuándo usar el orquestador vs. emisión directa.