Integración Fiscal
La página de Integración Fiscal permite configurar la conexión con un proveedor de facturación electrónica del gobierno para emitir documentos fiscales válidos. Cuando está habilitada, el sistema genera automáticamente documentos fiscales electrónicos (por ejemplo, CUFE en Panamá) cuando se contabilizan facturas C/C, facturas de reserva C/C, notas de crédito C/C y facturas de contado. Se admiten dos proveedores: FacturaFácil y The Factory HKA.
Acceso a la Página
Sección titulada «Acceso a la Página»Navega a Finanzas → Configuración → Integración Fiscal en el menú lateral, o ve a /finance/settings/fiscal-integration.
Nota: Esta página solo es visible si el país del tenant está configurado como Panamá (PA). Para otros países, la sección no aparece en el menú.
Secciones de Configuración
Sección titulada «Secciones de Configuración»Proveedor
Sección titulada «Proveedor»| Campo | Descripción | Opciones |
|---|---|---|
| Proveedor | Proveedor de facturación electrónica | FacturaFácil, The Factory HKA |
| Entorno | Entorno de operación | Prueba, Producción |
Selecciona Prueba para validar la integración sin emitir documentos fiscales reales. Cambia a Producción cuando la configuración esté verificada.
Los campos de credenciales y configuración del POS mostrados debajo del selector de Proveedor se adaptan al proveedor elegido — cada proveedor declara las claves que requiere, y el formulario las renderiza dinámicamente.
Credenciales y Configuración del POS
Sección titulada «Credenciales y Configuración del POS»Los campos mostrados dependen del proveedor seleccionado. Toda la configuración específica del proveedor se almacena cifrada en la configuración fiscal del tenant.
FacturaFácil
| Campo | Requerido | Tipo | Descripción |
|---|---|---|---|
| API Key | Sí | Contraseña | Clave de autenticación proporcionada por el proveedor; se almacena de forma segura y no se muestra después de guardar |
| ID de Empresa | Sí | Texto | Identificador de la empresa en el sistema del proveedor |
| ID de Sucursal | No | Texto | Identificador de la sucursal cuando la empresa tiene múltiples sucursales |
| Código de POS | Sí | Texto | Código del punto de venta registrado con el proveedor |
The Factory HKA
| Campo | Requerido | Tipo | Descripción | Predeterminado |
|---|---|---|---|---|
| Código de Sucursal | Sí | Texto | Coordenada de sucursal usada por HKA al almacenar y recuperar documentos | 0000 |
| POS | Sí | Texto | Coordenada de punto de venta usada por HKA | 001 |
| Serial del Dispositivo | No | Texto | Identificador de dispositivo serial emitido por HKA; usado como parte de las coordenadas de descarga del PDF fiscal |
Pueden aparecer claves de credenciales adicionales según la configuración del proveedor. El formulario siempre muestra el conjunto exacto de campos que el proveedor activo declaró al momento del registro.
| Campo / Acción | Descripción |
|---|---|
| Integración Habilitada | Activa o desactiva el envío de documentos al sistema fiscal |
| Probar Conexión | Valida las credenciales y la conectividad con el proveedor |
El botón Probar Conexión envía una solicitud de prueba al proveedor fiscal con las credenciales configuradas y muestra un mensaje de éxito o error.
Cuando la integración está Habilitada, los documentos elegibles (Facturas de Venta y Facturas de Contado) se envían automáticamente al sistema del proveedor fiscal al contabilizarse. El sistema asigna un identificador fiscal (CUFE) que se muestra en el detalle del documento.
Permisos
Sección titulada «Permisos»| Permiso | Descripción |
|---|---|
canManageFiscalIntegration | Requerido para ver y modificar la configuración fiscal |
Descarga de PDF Fiscal e Imagen QR
Sección titulada «Descarga de PDF Fiscal e Imagen QR»Cuando un documento se fiscaliza, el proveedor devuelve un identificador de documento fiscal (CUFE en Panamá) y — dependiendo del proveedor — una imagen QR codificada en base64. Ambos se almacenan en los Datos Fiscales del documento.
- Dónde descargar — Las páginas de detalle de Factura C/C, Factura de Reserva C/C y Nota de Crédito C/C muestran una acción Descargar PDF Fiscal cuando el documento está fiscalizado. El endpoint es
GET /<tipo-de-documento>/{id}/fiscal/pdfy devuelve un PDF llamado{númeroDeDocumento}-fiscal.pdf. - Comportamiento del proveedor — Con The Factory HKA, el sistema usa las coordenadas fiscales almacenadas (código de sucursal, POS, serial del dispositivo, número de documento, tipo de documento, tipo de emisión) para recuperar el PDF autorizado directamente desde HKA. Con FacturaFácil, se sigue la URL del PDF almacenado.
- Imagen QR — Cuando el proveedor devuelve una imagen QR, se almacena como data URI en los datos fiscales del documento y se renderiza en la página de detalle de la factura. Si el proveedor no devuelve una imagen pero devuelve un valor QR, el sistema genera la imagen QR a partir del valor y almacena el PNG. Tanto
qrCode(el valor) comoqrImageBase64(la imagen renderizada) están disponibles en el documento.
Notas de Reglas de Negocio
Sección titulada «Notas de Reglas de Negocio»- Cambiar el entorno de Producción a Prueba afecta todos los documentos futuros. Los documentos ya emitidos en producción no se ven afectados.
- Si el Probar Conexión falla, revisa las credenciales y el estado del servicio del proveedor.
- Las facturas emitidas cuando la integración estaba deshabilitada no se reenvían automáticamente al habilitarla.
- El CUFE generado por el sistema fiscal se muestra en la sección de Información Fiscal del detalle de cada factura, junto con la imagen QR.
- Una vez que una Factura C/C, Factura de Reserva C/C o Nota de Crédito C/C ha sido fiscalizada, la cancelación del documento está bloqueada — emite una nota de crédito contra el documento en su lugar.
- La configuración del proveedor se almacena cifrada. Guardar el formulario con el campo de contraseña en blanco preserva el valor almacenado existente.
Tareas Comunes
Sección titulada «Tareas Comunes»- Navega a Finanzas → Configuración → Integración Fiscal.
- Selecciona FacturaFácil como proveedor y Prueba como entorno.
- Ingresa las credenciales (API Key e ID de Empresa) del proveedor.
- Completa los datos del Punto de Venta (ID de Sucursal y Código POS).
- Haz clic en Probar Conexión para verificar la integración.
- Si la prueba es exitosa, cambia el entorno a Producción y activa la integración.
Páginas Relacionadas
Sección titulada «Páginas Relacionadas»- Facturas de Venta — Documentos enviados al sistema fiscal
- Factura de Contado — Creación con datos fiscales incluidos
- Detalle de Factura — Ver el CUFE asignado, la imagen QR y la descarga del PDF fiscal
- Facturas de Reserva C/C — Las facturas de reserva participan en la emisión fiscal y la descarga del PDF
- Notas de Crédito C/C — Las notas de crédito contra documentos fiscalizados también emiten un documento fiscal