Integración de efsta con Ágora: certificación fiscal en Portugal

La integración de efsta con Ágora certifica en Portugal los documentos del TPV: cada factura, factura simplificada y nota de crédito que emite Ágora se registra en efsta, el middleware fiscal que se encarga de la comunicación con la AT, y Ágora imprime el documento certificado que devuelve efsta. Connect Manager hace de puente, valida los datos antes de enviarlos y guarda cada documento.

Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local de Portugal. En Connect Manager el proveedor se llama Efsta (PT). Los mensajes que ve el camarero en el TPV están en portugués.

Qué hace la integración#

• Registra en efsta cada documento de Ágora al emitirlo: FT (factura) si lleva cliente, FS (factura simplificada) si no, y NC (nota de crédito) para las devoluciones, enlazada con el documento original. Ágora no cierra el documento hasta que efsta lo acepta.
• Envía las líneas con sus descuentos, los descuentos del ticket, los pagos y el desglose de impuestos, cada pago con su código de efsta y cada IVA con su grupo de impuesto, además del local, el terminal y el usuario que factura.
• Pide a efsta el documento certificado ya maquetado y se lo devuelve a Ágora para que lo imprima.
• Valida el NIF portugués del cliente (9 dígitos con dígito de control; admite el prefijo PT). Los NIF de otros países se envían con su prefijo de país, sin validar.
• Añade desde el TPV los datos fiscales del cliente al ticket (NIF, nombre, dirección y país) con el botón Dados da fatura, sin darlo de alta en Ágora. Si el NIF ya es de un cliente de Ágora, lo avisa.
• Emite e imprime facturas proforma certificadas del ticket abierto desde un botón. Si el ticket no ha cambiado de importe, reimprime la misma proforma; si ha cambiado, registra una nueva.
• Impide cerrar el documento si una forma de pago o un tipo de IVA no está configurado, si una venta sin NIF supera el importe máximo o si el importe cobrado con una forma de pago alcanza su límite.
• Exporta desde el TPV los documentos certificados de un año o de un periodo, con la exportación de efsta.
• Permite al usuario de Ágora cambiar su contraseña desde un botón del TPV.
• Guarda cada documento con lo enviado y lo respondido. En Listados fiscales → Efsta documentos se consultan, se abre su PDF y se envía por correo.
• Si Ágora reenvía un documento ya certificado (misma serie y número), no lo vuelve a registrar.

Qué no hace#

• No anula una factura proforma ya emitida: el botón Anular del listado no la anula en efsta.
• No factura si efsta no responde: no hay modo de contingencia en Connect Manager y el documento se rechaza hasta que efsta vuelve.
• No envía avisos por correo ni por Telegram: los campos de notificación de la pantalla no se usan en esta integración.
• La casilla Enviar facturas a integraciones de hotel no tiene efecto en la versión actual.
• No exporta a Excel los documentos de efsta desde el panel: para eso están las exportaciones por año y por periodo.

Requisitos#

• efsta instalado, licenciado y dado de alta para el contribuyente. Lo gestiona efsta o su partner: la comunicación con la AT es cosa de efsta, no de Connect Manager.
• URL del servicio de efsta accesible desde Connect Manager, que llama a efsta para registrar, imprimir y sacar el PDF de cada documento. Si efsta está en el local, publícalo con su propia URL o con un túnel adicional de Zero Connect. Los botones de exportación abren esa misma URL desde el TPV, así que el TPV también tiene que llegar a ella.
• Local en Connect Manager con la URL de la API y la API key de Ágora: los buscadores de formas de pago y de impuestos de la configuración consultan la API del local. El alta del local y de la integración la hace FOS.
• Ágora con Servicios de integración (integración de documentos con sistemas externos), Acciones personalizadas y plantillas de impresión ESC/POS: el documento de efsta llega como datos de impresión ESC/POS.
• Los dos informes personalizados que se descargan de la integración, instalados en Ágora. Los usan las ventanas de datos del cliente y de proforma.

[!WARNING] Connect Manager llama a efsta sin credenciales. No dejes su URL abierta a todo Internet: limita el acceso a las direcciones IP de Connect Manager y a la IP pública del local.

Datos que necesitamos#

Configuración paso a paso#

En efsta#

1. efsta o su partner instala y da de alta el servicio para el contribuyente y te facilita su URL.
2. Pídele los códigos de forma de pago y los grupos de impuesto que espera, y confirma si registra un terminal por cada TPV o uno por local.

En Connect Manager#

1. En https://app.connectmanager.es, ve a Administración → Locales, abre el local, revisa la URL de API y la API key de Ágora y pulsa Guardar.
2. Entra en Integraciones fiscales, pulsa Añadir y elige el Proveedor Efsta (PT).
3. En la pestaña Configuración rellena:
   • URL Api: la de efsta, terminada en /: Connect Manager le añade las rutas de efsta detrás.
   • Límite de pago FS: importe máximo de un documento sin NIF. Por encima, Ágora pide asignar un cliente. Vacío o 0, sin límite.
   • Usar el local como punto de venta: márcala si efsta registra un único terminal por local; desmarcada, cada TPV de Ágora es un terminal.
   • Enviar facturas a integraciones de hotel: déjala desmarcada.
4. Pulsa Guardar. Al pie aparecen la URL para enviar facturas desde Ágora, la URL de botón de asignación de CUIT (es la de Dados da fatura), la URL de botón cambiar password, la URL de botón generación factura proforma, la URL de botón de exportación anual de documentos y la URL de botón de exportación de documentos por periodo.
5. Descarga los informes Informe de datos del cliente (Customer_Data_For_Ticket.xml) e Informe de clientes filtrados por NIF (Customers_Filtered_By_CIF.xml).
6. En la pestaña Métodos de pago, pulsa + Añadir por cada forma de pago de Ágora que use el local: Método de pago, Código del método (el de efsta) y, si procede, Límite de pago del método.
7. En la pestaña Impuestos, pulsa + Añadir por cada tipo de IVA de Ágora: el impuesto y su Código del impuesto en efsta.

[!NOTE] Una forma de pago o un IVA sin mapear no da error al configurar: bloquea la venta en el TPV la primera vez que se usa. Mapea todos los que existan en Ágora, aunque se usen poco.

En Ágora#

1. Copia los dos informes descargados, sin modificarlos, en la carpeta custom-queries del servidor de Ágora.
2. En Herramientas → Activar módulos adicionales → Servicios de integración, pega la URL para enviar facturas desde Ágora en la integración de documentos con sistemas externos y actívala para las facturas.
3. En Herramientas → Acciones personalizadas, crea una acción de tipo Url/Aplicación por cada botón, con Mostrar Urls en un diálogo de Ágora marcado: Dados da fatura, Proforma, Exportar ano, Exportar período y Mudar password, cada una con su URL. A la de la proforma añádele al final, detrás de printer_name=, el nombre exacto de la impresora de Ágora.
4. Coloca las acciones en Herramientas → Configuración de botones y da el permiso de cada acción a los perfiles de usuario que deban usarla.
5. Comprueba que las plantillas de impresión de los documentos son ESC/POS.

[!WARNING] Ágora lee la carpeta custom-queries al arrancar sus componentes de servidor, y un informe mal formado puede impedir que el servicio arranque. Copia los ficheros tal cual se descargan.

Cómo funciona#

Al emitir un documento, Ágora lo manda a Connect Manager. Connect Manager comprueba serie, número, NIF, formas de pago, límites e impuestos; si algo falla, contesta con el motivo y Ágora no cierra el documento. Si todo está bien, lo registra en efsta, que le devuelve el número fiscal del documento; con ese número pide a efsta el ticket certificado en formato ESC/POS y se lo entrega a Ágora para imprimirlo.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant EF as efsta
    TPV->>CM: Documento emitido
    CM->>CM: Valida NIF, pagos, límites e impuestos
    CM->>EF: Registro del documento
    EF-->>CM: Resultado OK y número fiscal
    CM->>EF: Documento certificado en ESC/POS
    EF-->>CM: Ticket maquetado
    CM-->>TPV: Aceptado con los datos de impresión
    TPV->>TPV: Cierra e imprime el documento

Qué se envía#

• Fecha, local (TL), terminal (TT: el TPV, o el local si está marcada la opción), tipo (FT, FS o NC), número de Ágora (serie/número), total y usuario.
• Cliente: NIF, nombre, dirección y país de la ficha de Ágora o de los datos añadidos con Dados da fatura.
• Líneas con cantidad, precio, grupo de impuesto y descuentos; descuentos del ticket; pagos con su código; impuestos con su grupo y porcentaje.
• En las notas de crédito, el número fiscal del documento original.

Si efsta devuelve un error de NIF, el TPV muestra «O NIF inserido não está correto» o «O cliente não possui NIF»; cualquier otro error se muestra con su código. Si efsta no contesta, el documento queda como «Sin enviar» en el listado y Ágora recibe el rechazo.

Botones del TPV#

• Dados da fatura: ventana con País, NIF, Nome y Endereço y los botones Manter y Cancelar. Antes de guardar busca el NIF entre los clientes de Ágora con el informe de clientes; si existe, avisa con el nombre del cliente para que se asigne ese cliente. Los datos quedan ligados al ticket abierto, así que se rellenan antes de emitir el documento.
• Proforma: lee el ticket abierto y los datos del cliente desde Ágora, registra la proforma en efsta y la imprime en la impresora indicada en la URL.
• Exportar ano y Exportar período: piden el año o las fechas y abren la exportación de documentos de efsta para el local.
• Mudar password: cambia la contraseña del usuario de Ágora que pulsa el botón.

Las ventanas de datos del cliente y de proforma hablan con Ágora a través del propio TPV, así que no necesitan que la API de Ágora esté abierta a Internet.

Comprobar que funciona#

1. Emite una factura simplificada sin cliente: debe imprimirse el documento certificado de efsta.
2. En Listados fiscales → Efsta documentos debe aparecer como Aceptado, con su código; abre Exportar PDF y comprueba el documento.
3. En un ticket nuevo, pulsa Dados da fatura, introduce un NIF portugués válido de pruebas, nombre y dirección, guarda y emite: debe salir como factura con esos datos.
4. Haz una devolución de la primera venta: debe certificarse como nota de crédito.
5. Cobra con una forma de pago sin mapear o vende un producto con un IVA sin mapear: el TPV debe bloquear el cierre con el mensaje correspondiente.
6. Pulsa Proforma en un ticket abierto: debe imprimirse en la impresora configurada.
7. Prueba las dos exportaciones desde el TPV.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Ágora con la AT de Portugal?#

A través de efsta: Connect Manager envía cada documento de Ágora a efsta, que lo certifica, y devuelve a Ágora el documento certificado para imprimirlo.

¿Qué pasa si efsta no responde?#

El documento se rechaza en el TPV y queda «Sin enviar» en el listado. Connect Manager no tiene modo de contingencia para efsta.

¿Puedo poner el NIF del cliente sin crearlo en Ágora?#

Sí, con el botón Dados da fatura, antes de emitir el documento.

¿Se pueden anular las proformas?#

No. Si el importe del ticket cambia, se emite una proforma nueva; la anterior no se anula.

¿Dónde consigo el PDF de una factura certificada?#

En Listados fiscales → Efsta documentos, desde el detalle del documento: Exportar PDF o Enviar mail.

Referencias#

• Ficha de la integración: Portugal (AT, efsta) en el catálogo de Connect Manager.
• Integración de ARCA con Ágora, la otra integración fiscal con la misma pantalla de configuración.
• Zero Connect: publicar servicios del local sin abrir puertos.
• Direcciones IP salientes de Connect Manager.
• efsta: https://www.efsta.eu.