Factura electrónica en Panamá: tres PACs, un CUFE y el bug de la propina

En Panamá, si vendes software administrativo para PYMEs, tarde o temprano llegas al mismo muro: la factura electrónica. No es opcional, no es un “nice to have”, y no se resuelve leyendo un PDF. Es la parte del sistema que más me ha enseñado sobre la diferencia entre “funciona en mi máquina” y “la DGI le asignó un CUFE”.

Este post es lo que aprendí conectando Suite HUB a tres PACs distintos.

Qué es un PAC y por qué no puedes saltártelo#

En el modelo panameño no le mandas la factura directo a la DGI. Se la mandas a un PAC (Proveedor de Autorización Calificado): un intermediario autorizado que valida el documento, lo firma, lo transmite y te devuelve el CUFE, el código único que convierte tu venta en un documento fiscal válido.

Suena simple. La trampa está en que cada PAC implementa el mismo concepto de forma distinta: distintos WSDL, distintos nombres de campo, distinta tolerancia a los errores. Así que la primera decisión de arquitectura fue no casarme con ninguno.

Una capa abstracta, tres implementaciones#

En vez de esparcir llamadas SOAP por todo el código, definí un contrato: un puñado de funciones pac_* que todo el sistema usa sin saber qué proveedor hay detrás. Emitir, consultar RUC, obtener la leyenda del validador. La lógica de negocio habla ese contrato; cada PAC lo implementa a su manera.

Hoy Suite HUB habla con tres:

• The Factory HKA, validado en producción, con CUFE real.
• Digifact, validado en producción, con CUFE real.
• Factura Fácil, el que me costó el post entero (ya llegamos).

El beneficio de la capa abstracta se paga solo el día que un cliente quiere cambiar de PAC, o cuando uno de ellos se cae y necesitas un plan B sin reescribir el módulo de ventas.

El detalle que nadie te cuenta: extension=soap#

hka_lookup_ruc(), la función que consulta un RUC contra el registro, la implementé sobre el SOAP ConsultarRucDV, verificando el esquema contra el WSDL vivo, no contra la documentación (que casi nunca coincide).

Detalle que me costó una tarde: requiere extension=soap habilitada. En producción viene activa, pero en varios XAMPP de desarrollo viene comentada en el php.ini. El síntoma es hermosamente engañoso: el código está bien, el WSDL responde, y aun así “no existe la clase SoapClient”. Si algún día te pasa, empieza por ahí antes de dudar de tu lógica.

El bug de la propina#

Y aquí está la historia que da título al post.

Factura Fácil me rechazaba los documentos sin darme un CUFE. Nada de un error claro: la DGI simplemente no los autorizaba. Revisé firmas, secuencias, formato del rFE, credenciales. Todo correcto.

El problema estaba en el pago. En el payload, el monto pagado incluía la propina. Para el sistema de restaurante tenía todo el sentido, el cliente pagó subtotal + ITBMS + propina. Pero para la DGI el documento fiscal solo conoce subtotal + ITBMS. Al mandar un pago mayor que el total facturado, el documento descuadraba por el monto de la propina, y el validador lo tumbaba sin explicación útil.

La corrección fue una línea conceptual: en el payload fiscal, pago = subtotal + ITBMS. La propina se registra aparte, en el flujo del negocio, no en el documento que va a la DGI.

Lo aprendí de la peor manera, a punta de descartar hipótesis, y por eso lo escribo: cuando un PAC te rechaza sin CUFE, no asumas que es la firma o las credenciales. Cuadra el documento centavo por centavo primero. La mayoría de los rechazos silenciosos que he visto son aritmética, no criptografía.

La leyenda del validador (un detalle legal que sí importa)#

Cada PAC exige que la factura impresa muestre una leyenda con su autorización. En el caso de HKA, es literalmente el RUC del PAC y el número de resolución que lo habilita ante la DGI. Lo dejé como dato del proveedor, no hardcodeado en la plantilla, precisamente porque es el tipo de cosa que cambia por acto administrativo y no quieres estar buscándola entre el HTML cuando pase.

Lo que me llevo#

Integrar factura electrónica en Panamá no es difícil por el SOAP. Es difícil porque estás en la intersección de tres cosas que no se hablan entre sí: la lógica de tu negocio, la implementación del PAC y la interpretación de la DGI. Cada una tiene su propia idea de qué es “una venta”.

El trabajo real no es escribir el cliente SOAP, eso es una tarde. Es diseñar la capa que traduce entre esos tres mundos sin que el módulo de ventas se entere, y tener la paciencia de cuadrar un documento hasta el último centavo cuando el rechazo no dice por qué.

Si estás construyendo algo parecido en Panamá y te atascas: escríbeme. Ya pisé varias de esas piedras.