Integración de API de facturación electrónica en Panamá: guía técnica para ISVs

Para un ISV que opera en Panamá o que quiere dar soporte a clientes panameños, la integración con el sistema FEPA no es solo un requerimiento fiscal — es un componente crítico de la propuesta de valor del producto. La calidad de esa integración determina cuánto tiempo pierde el equipo de soporte atendiendo incidencias fiscales.

Esta guía cubre las decisiones técnicas de arquitectura que más impactan la calidad de la integración FEPA: la abstracción del PAC, el manejo de errores, el almacenamiento del CUFE y la estrategia para contingencias.

Abstraer el PAC como dependencia intercambiable

El error de arquitectura más frecuente en implementaciones FEPA es acoplar el código directamente a la API de un PAC específico. Cuando el cliente quiere cambiar de PAC, o cuando el PAC cambia su API, la integración entera debe reescribirse.

La solución es implementar una capa de abstracción: una interfaz `PACClient` con los métodos `emitir(documento)`, `consultar(cufe)` y `anular(cufe, motivo)`. Cada PAC tiene su propia implementación de esta interfaz. El módulo de facturación del sistema solo conoce la interfaz, no la implementación del PAC. Cambiar de PAC implica solo cambiar la implementación, no el código del sistema.

# Interfaz abstracta de PAC — pseudocódigo
from abc import ABC, abstractmethod

class PACClient(ABC):
    @abstractmethod
    def emitir(self, documento_xml: str) -> dict:
        """
        Retorna:
        - cufe: str (solo si exitoso)
        - estado: 'aceptado' | 'rechazado' | 'contingencia'
        - mensajes: list[str]
        - xml_sellado: str
        """
        pass

    @abstractmethod
    def consultar(self, cufe: str) -> dict:
        pass

class PACProveedorA(PACClient):
    def __init__(self, api_url, credentials):
        self.client = SOAPClient(api_url, credentials)

    def emitir(self, documento_xml: str) -> dict:
        resp = self.client.call('EmitirDocumento', xml=documento_xml)
        return {
            'cufe': resp.get('CUFE'),
            'estado': 'aceptado' if resp.get('Resultado') == '0' else 'rechazado',
            'mensajes': resp.get('Mensajes', []),
            'xml_sellado': resp.get('XMLSellado')
        }

Manejo de errores y categorización

Los errores en la integración FEPA caen en cuatro categorías: errores de validación de datos (el XML tiene campos incorrectos — deben corregirse), errores de conectividad (timeout, el PAC no responde — reintentar con backoff exponencial), errores de certificación (el PAC rechaza el documento por reglas de negocio FEPA), y errores de la DGI retransmitidos por el PAC.

Almacenamiento del CUFE y trazabilidad

El CUFE debe almacenarse junto con el documento y estar disponible para: búsqueda por parte del equipo de soporte, reimpresión del documento con el CUFE visible, y consulta de estado futura. Muchos sistemas almacenan el CUFE en la base de datos pero no lo incluyen en la representación gráfica — esto dificulta las consultas manuales del cliente.

El XML sellado por el PAC también debe almacenarse. La DGI puede requerir el XML original sellado ante auditoría. Almacenar solo el CUFE y generar el XML de nuevo en caso de auditoría no es una estrategia confiable.

Estrategia de contingencia

La contingencia FEPA se activa cuando el PAC no está disponible. La estrategia correcta es: (1) detectar el fallo de conectividad con el PAC, (2) cambiar al modo contingencia en el sistema, (3) generar el documento con indicador de contingencia en el XML, (4) almacenarlo localmente en cola de regularización, (5) cuando el PAC esté disponible, transmitir los documentos en contingencia en orden cronológico.

Representación gráfica del documento

La DGI define los elementos mínimos que debe incluir la representación gráfica del documento FEPA: número de documento fiscal, CUFE (en texto y como código QR), datos del emisor y receptor, detalle de líneas, totales e impuestos, y el texto de autorización DGI. El QR debe codificar una URL que lleve a la consulta del documento en el portal DGI.

Preguntas frecuentes

¿Cuál es el tiempo de respuesta esperado del PAC para una emisión individual?

Los tiempos típicos en condiciones normales están entre 1 y 5 segundos para documentos individuales. Configurar un timeout de 15 segundos para el primer intento y de 10 segundos para reintentos. Timeouts más cortos generan falsos errores de conectividad cuando el PAC está bajo carga.

¿Cómo puedo manejar la emisión de documentos en lote en Panamá?

La mayoría de los PAC autorizados soportan envío en lote (batch) mediante un XML envolvente. El PAC procesa el lote y retorna el estado de cada documento individualmente. Para lotes grandes, implementar procesamiento asíncrono: enviar el lote, recibir un identificador de lote, y consultar el estado periódicamente.

¿Qué diferencia hay entre la firma del emisor y el sello del PAC en el documento FEPA?

En el modelo panameño estándar, el PAC es quien certifica (sella) el documento con su firma digital autorizada por la DGI. El emisor debe autenticarse con el PAC mediante credenciales, pero no necesariamente firmar el XML del documento. Verificar con el PAC elegido si requiere pre-firma del emisor.

¿Es posible emitir facturas electrónicas en Panamá sin certificado propio?

En el modelo PAC actual, el emisor no necesita certificado propio para firmar documentos. El PAC usa su certificado para sellar el documento en nombre del emisor. El emisor se autentica con el PAC mediante usuario y contraseña. Esto simplifica considerablemente la implementación frente a sistemas de LATAM donde el emisor debe gestionar su propio certificado.