Idempotencia y Reintentos en la API del DGI Panamá: Guía para ISVs

Cuando un sistema integrado con el DGI en Panamá pierde la conexión justo después de enviar un documento al PAC y antes de recibir la respuesta de confirmación, el equipo de desarrollo enfrenta una decisión crítica: ¿reintentar el envío o asumir que el documento ya fue procesado? Sin una estrategia de idempotencia bien definida, cualquiera de las dos opciones puede resultar en un documento duplicado en el SFEP o en un registro omitido que genera inconsistencias entre el sistema del ISV y los registros del DGI.

Esta guía describe cómo implementar idempotencia y reintentos seguros en la integración con la API del DGI a través del PAC en Panamá. Al finalizar, el equipo técnico contará con un modelo de control de transmisiones, una estrategia de backoff y los criterios precisos para decidir cuándo reintentar y cuándo escalar al equipo de operaciones.

Qué es la idempotencia y por qué importa en el SFEP de Panamá

Definición aplicada al flujo de transmisión DGI-PAC

Idempotencia, en el contexto de una integración con el DGI de Panamá, significa que enviar el mismo documento al PAC múltiples veces produce exactamente el mismo resultado que enviarlo una sola vez: el documento queda registrado una única vez en el SFEP. Esta propiedad es crítica porque el protocolo de comunicación entre el ISV, el PAC y el DGI no garantiza entrega exactamente una vez. Si el ISV envía un documento y no recibe respuesta por timeout, no puede saber con certeza si el PAC recibió y procesó el envío o si la solicitud nunca llegó. Sin idempotencia implementada en el sistema, el reintento automático puede generar un documento duplicado en el SFEP, lo que en el contexto fiscal panameño representa una inconsistencia que el contribuyente debe resolver manualmente ante el DGI.

El riesgo concreto de documentos duplicados en producción

En producción, los timeouts de red no son eventos excepcionales: son inevitables. Un ISV con volumen de 5.000 documentos mensuales puede experimentar decenas de timeouts en condiciones normales de red. Si la integración reintenta automáticamente todos los envíos fallidos sin verificar si el documento ya fue procesado, el resultado son documentos duplicados que el PAC puede rechazar —si implementa deduplicación— o, en el peor caso, documentos que llegan al DGI con números distintos para la misma transacción, generando obligaciones fiscales no deseadas para el emisor. El escenario más costoso es una factura de alto valor transmitida múltiples veces por un ciclo de reintentos mal configurado: genera varios registros en el SFEP y obliga a un proceso manual de corrección ante el DGI.

Cómo funciona la idempotencia en el marco del SFEP panameño

El número de documento DGI como identificador único

El SFEP de Panamá asigna a cada documento fiscal electrónico un número compuesto por el código del contribuyente, el tipo de documento (FE para factura electrónica, NC para nota de crédito, ND para nota de débito) y un número secuencial. Este número debe ser único por contribuyente y por tipo de documento en el registro del DGI. Si el PAC recibe dos documentos con el mismo número, el comportamiento depende de cada PAC habilitado: algunos implementan deduplicación y devuelven el resultado del primer procesamiento, otros rechazan el segundo con código de error de duplicado. La implementación correcta de idempotencia desde el lado del ISV garantiza que nunca se genere un segundo documento con el mismo número: el número se asigna una única vez, se persiste en la base de datos antes de intentar cualquier transmisión, y cualquier reintento usa el mismo número sin generar uno nuevo.

Comportamiento del PAC ante reintentos: variabilidad entre proveedores

El comportamiento del PAC ante el reintento de un documento ya procesado no está estandarizado en el SFEP: cada PAC habilitado por el DGI puede implementar su propia lógica. Algunos PACs devuelven la misma respuesta de éxito si el documento ya fue procesado (idempotencia total). Otros devuelven un error de duplicado que el ISV debe interpretar como éxito (el documento ya está en el sistema). Otros simplemente procesan el documento como si fuera nuevo, generando el duplicado. Por este motivo, la estrategia de idempotencia no debe depender del comportamiento del PAC: debe implementarse del lado del ISV, verificando el estado del documento en el sistema propio antes de cualquier reintento.

Estrategia de reintentos segura para integraciones con el DGI en Panamá

Backoff exponencial y número máximo de intentos

Una estrategia de reintentos para la integración con el DGI en Panamá debe cumplir tres condiciones: usar backoff exponencial para no saturar el endpoint del PAC en caso de degradación de servicio, establecer un número máximo de reintentos que evite ciclos infinitos, y verificar el estado del documento antes de cada reintento para no enviar algo que ya fue procesado. Los valores de referencia son: primer reintento a los 10 segundos, segundo a los 30, tercero a los 90, cuarto a los 300, con un máximo de 5 reintentos totales. Si el documento no tiene estado confirmado tras 5 intentos, debe marcarse como 'pendiente de revisión manual' y generar una alerta para el equipo técnico. El intervalo puede reducirse para documentos de alta prioridad, pero nunca debe ser inferior a 5 segundos para los primeros intentos, para evitar saturar el endpoint del PAC.

Cuándo reintentar y cuándo no: matriz de decisión por tipo de error

No todos los errores justifican un reintento automático. La matriz de decisión debe clasificar los errores en tres categorías. Errores que justifican reintento: timeout de red (el documento probablemente no llegó al PAC), error HTTP 503 (servicio no disponible temporalmente), error HTTP 504 (gateway timeout). Errores que no justifican reintento automático: error HTTP 400 (documento mal formado), error HTTP 422 (falla de validación de negocio), error HTTP 409 (duplicado detectado por el PAC). En estos casos, reintentar sin corrección produce el mismo error. Errores que requieren verificación previa: timeout con respuesta parcial, error HTTP 500 del PAC. En este tercer caso, el ISV debe consultar el estado del documento en el PAC antes de decidir si reintenta o lo confirma como procesado.

Implementación técnica: cómo garantizar idempotencia en el sistema del ISV

Tabla de control de transmisiones: esquema recomendado

La implementación más robusta de idempotencia requiere una tabla de control de transmisiones en la base de datos del ISV. El esquema mínimo incluye: document_id (UUID del sistema interno), document_number (número DGI asignado), document_type (FE/NC/ND), transmission_status (pending/sent/accepted/rejected/unknown), transmission_attempts (contador de reintentos), last_attempt_at (timestamp del último intento), pac_response (respuesta del PAC en el último intento), dgi_status (estado DGI cuando esté disponible), created_at y updated_at. Antes de cada intento de transmisión, el sistema consulta esta tabla: si el documento está en estado 'accepted', no se transmite. Si está en 'pending' o 'unknown', se transmite con el mismo número de documento ya asignado. Para ISVs que prefieren externalizar esta capa, la solución de facturación electrónica para Panamá de Alanube gestiona el control de transmisiones del lado del proveedor y expone al ISV únicamente el estado final del documento a través de su API REST.

Bloqueo atómico en la generación del número de documento

El punto más crítico del sistema es la asignación del número de documento DGI: debe ocurrir una única vez por transacción comercial y debe ser atómica respecto a la escritura en la base de datos. Si dos procesos paralelos intentan crear el documento simultáneamente —por ejemplo, un proceso de facturación automática y una acción manual del usuario—, ambos pueden obtener números distintos para la misma transacción en ausencia de bloqueo. Para evitarlo, la asignación del número debe implementarse dentro de una transacción de base de datos con bloqueo (pessimistic locking) o mediante una restricción de unicidad en la tabla de documentos que garantice que cada transacción comercial solo tenga un número asignado. En entornos multi-instancia, el uso de un generador de secuencias centralizado —una cola de mensajes, un servicio dedicado o un contador atómico en Redis— elimina el riesgo de colisión entre instancias.

Errores frecuentes y cómo prevenirlos

Reintento sin verificación de estado previo

El error más frecuente en integraciones con el DGI es configurar reintentos automáticos que no verifican el estado del documento antes de retransmitir. Este patrón es especialmente peligroso en arquitecturas basadas en colas de mensajes: si el mensaje de transmisión falla y queda en la cola para reintento, el worker que lo procesa en el segundo intento no tiene forma de saber si el primer intento llegó al PAC o no, a menos que consulte la tabla de control. La solución es implementar la verificación de estado como primera acción en cada intento de transmisión: el worker consulta la tabla de control, recupera el estado del documento, y solo transmite si el estado es 'pending' o 'unknown' sin confirmación previa de procesamiento por parte del PAC.

Generación paralela de documentos con el mismo número secuencial

En arquitecturas distribuidas con múltiples instancias del servicio de facturación, es posible que dos instancias asignen el mismo número secuencial a documentos distintos si el generador de secuencias no es atómico. El síntoma es intermitente: aparece solo bajo carga alta cuando varias instancias procesan documentos simultáneamente. La causa raíz es un generador implementado con una lectura seguida de una escritura no atómica, el clásico problema de race condition. La solución es una de tres: usar una secuencia de base de datos con autoincremento atómico, implementar un lock distribuido sobre la operación de generación, o usar un servicio externo de secuencias. La tercera opción introduce una dependencia adicional pero elimina completamente el riesgo de colisión en entornos multi-instancia de alta concurrencia.