La integración de ACI Hotel con Ágora no se conecta con el PMS: todo pasa dentro de Ágora. El camarero busca la habitación entre los clientes de Ágora que tienen el número de habitación como nombre fiscal, el ticket se cierra como albarán a nombre de esa habitación y el huésped puede firmar en pantalla; la firma se guarda con el albarán y se imprime en él. Lo que el hotel haga después con esos albaranes queda fuera de Connect Manager.
Este manual es para el técnico de FOS o del distribuidor que configura la integración en un local. La visión general de los PMS con Ágora está en Hotel Hub: cómo funciona.
Qué hace la integración#
- Añade a Ágora un botón (acción personalizada) que abre la ventana de cargo dentro del TPV.
- Busca la habitación entre los clientes de Ágora con la consulta personalizada
Customers_Filtered_By_Tax_Name: el cliente cuyo nombre fiscal es el número de habitación. Enseña número, nombre, teléfono y correo. - Recoge la firma del huésped en la pantalla (opcional) y la guarda con el cargo.
- Cierra el ticket en Ágora como albarán abierto a nombre de ese cliente.
- Devuelve la firma a Ágora para que se imprima en el albarán.
- Ofrece una página para consultar los albaranes y sus firmas por habitación y fechas.
Qué no hace#
- No envía nada a ACI Hotel: ni cargos, ni facturas, ni anulaciones. El albarán se queda en Ágora.
- No comprueba la estancia, las fechas ni el crédito del huésped.
- No crea ni actualiza los clientes-habitación de Ágora: tienen que existir antes.
- No sincroniza reservas ni disponibilidad.
Requisitos#
- Ágora con Herramientas → Acciones personalizadas y, para imprimir la firma, el módulo Servicios de integración y una plantilla de albarán ESC/POS (Ágora solo añade datos externos a la impresión en esas plantillas).
- Clientes-habitación en Ágora: un cliente por habitación cuyo nombre fiscal sea el número, por ejemplo «101». Alguien tiene que mantenerlos: confírmalo con el hotel.
- La consulta personalizada
Customers_Filtered_By_Tax_Nameinstalada en Ágora: es la que hace la búsqueda. Confirma con FOS cómo se instala si el local no la tiene. - Conectividad. En el modo normal todo va por la API local del TPV y no hace falta abrir Ágora a Internet. Con «Usar el API externa de Ágora», Connect Manager llama a la API de Ágora desde sus servidores: tiene que ser accesible a las IP de Connect Manager o por Zero Connect.
- Quién hace qué. FOS da de alta el local y la integración. El distribuidor configura Ágora (acción, URL de documentos y plantilla). El hotel mantiene los clientes-habitación.
Datos que necesitamos#
| Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio |
|---|---|---|---|
| Clientes de Ágora con la habitación como nombre fiscal | Hotel, en Ágora | Nombre fiscal 101 | Sí |
Consulta personalizada Customers_Filtered_By_Tax_Name | Confírmalo con FOS | Instalada en Ágora | Sí |
| URL de API y API key de Ágora del local | Distribuidor | http://servidor-demo:8984/ | Sí |
| URL Api y Api Token (los de la API de Ágora) | Distribuidor | http://servidor-demo:8984/, acabada en barra | Solo con «Usar el API externa de Ágora» |
| Plantilla de albarán ESC/POS | Distribuidor, en Ágora | — | Para imprimir la firma |
Configuración paso a paso#
1. En Ágora, antes de nada#
- Comprueba que existen los clientes-habitación (nombre fiscal = número de habitación) y quién los da de alta y de baja.
- Comprueba que la consulta personalizada
Customers_Filtered_By_Tax_Nameestá instalada.
2. En Connect Manager: el local (lo hace FOS)#
- En Administración → Locales, abre el local y rellena Cliente, Nombre, URL de API, API key, Dirección, Ciudad y Zona horaria. La API key es la que usa la ventana para hablar con Ágora.
- Guardar → Integraciones de hoteles → Añadir → proveedor Aci Hotel.
3. En Connect Manager: Conf. general#
- Pausar el envío de cargos al PMS después de y Pausar el envío de cargos al PMS: solo los ve FOS. Con la integración pausada, el botón del TPV abre el aviso «Integración pausada».
- URL Api y Api Token: pese al nombre, son la URL de la API de Ágora (acabada en
/) y su token, no datos de ACI Hotel. Solo se usan con «Usar el API externa de Ágora». - Email de receptor de notificaciones: esta integración no envía avisos.
4. En Connect Manager: Conf. de cargos#
- Usar el API externa de Ágora: desmarcado, la ventana busca la habitación y crea el albarán a través de la API local del TPV. Marcado, lo hace Connect Manager desde sus servidores con la URL Api y el Api Token para la búsqueda y la URL de API del local para el ticket y el albarán. Recomendado: desmarcado, salvo que el TPV no pueda usar la API local. Al crear la integración viene marcado.
El albarán siempre se crea abierto: esta opción no se puede cambiar para ACI Hotel.
5. En Ágora#
- Copia del bloque Enlaces la URL botón acción personalizada. Si empieza por
/venues/, antepónhttps://app.connectmanager.es. - En Herramientas → Acciones personalizadas pulsa Nuevo: Texto «Cargo habitación», Tipo «Url/Aplicación», Acción la URL copiada (sin tocar los marcadores entre llaves) y marca Mostrar Urls en un diálogo de Ágora. Colócala en Configuración de botones y da su permiso a los perfiles que vayan a cargar.
- Para imprimir la firma, en Herramientas → Activar módulos adicionales → Servicios de integración pega la URL para enviar facturas desde Ágora y activa Habilitar integración de documentos y Enviar albaranes.
- Si el hotel quiere consultar firmas, crea otra acción con la URL consulta de cargos habitación, o ábrela en un navegador.
Cómo funciona#
El botón abre la ventana con el ticket y la ventana lo lee por la API local de Ágora. El camarero escribe la habitación; la ventana ejecuta en Ágora la consulta personalizada y toma el primer cliente cuyo nombre fiscal coincide. El huésped firma, si se quiere, y al pulsar Cargar Connect Manager guarda la firma y registra el cargo. Después la ventana crea el albarán abierto a nombre de ese cliente. Al crearse, Ágora manda el albarán a la URL de facturas, Connect Manager lo acepta y le devuelve la firma para imprimirla, y la ventana se cierra.
sequenceDiagram
participant TPV as TPV Ágora
participant CM as Connect Manager
TPV->>TPV: Lee el ticket por la API local
TPV->>CM: Guarda el ticket
TPV->>TPV: Busca el cliente con la consulta personalizada
TPV->>CM: Cargar con la firma
CM->>CM: Guarda la firma y registra el cargo
TPV->>TPV: Crea el albarán a nombre de la habitación
TPV->>CM: Envía el albarán a la URL de facturas
CM-->>TPV: Aceptado con la firma para imprimir
TPV->>CM: Guarda el albarán
Con «Usar el API externa de Ágora» el recorrido es el mismo, pero la búsqueda, la lectura del ticket y la creación del albarán las hace Connect Manager contra la API de Ágora, y la ventana termina con «Se generó el siguiente cargo».
Qué se guarda: el ticket, el albarán, la habitación y la imagen de la firma. Las facturas y las anulaciones que lleguen a la URL se aceptan sin hacer nada más.
Consulta de firmas: la página de la URL de consulta pide «Desde», «Hasta» y «Nº de habitación» y lista los albaranes de esa habitación con su firma y sus líneas.
Comprobar que funciona#
- En Ágora, abre un ticket, pulsa el botón y busca una habitación con cliente: salen número, cliente, teléfono y correo.
- Firma en la pantalla y pulsa Cargar: la ventana confirma y se cierra.
- En Ágora, el ticket es un albarán abierto a nombre del cliente-habitación; en la copia impresa sale «FIRMA:» con la imagen.
- En la página de consulta de firmas, busca la habitación y la fecha de hoy: aparece el albarán con la firma.
Errores frecuentes y solución#
| Síntoma | Causa | Solución |
|---|---|---|
| «No se ha encontrado el nº de habitación especificado.» o «No se han encontrado reservas con el criterio especificado» | No hay cliente en Ágora con ese nombre fiscal, o falta la consulta personalizada | Revisa el cliente-habitación y la consulta en Ágora. |
| La ventana se queda cargando y sale «Request timed out» | La acción no se abre dentro de Ágora | Marca «Mostrar Urls en un diálogo de Ágora». |
| «El cliente es obligatorio. Realice la búsqueda para poder realizar el cargo.» | Se pulsó Cargar sin buscar | Busca primero la habitación. |
| «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | Ágora no creó el albarán | Revisa que el ticket siga abierto y que el cliente-habitación sea válido. |
| La firma no sale impresa | Falta la URL de facturas o «Enviar albaranes», la plantilla no es ESC/POS o no se firmó | Revisa Servicios de integración y la plantilla del albarán. |
| «Ocurrió un error: …» con «Usar el API externa de Ágora» | URL Api, Api Token o URL de API del local inaccesibles | Revisa la conexión, o desmarca la opción. |
| «Integración pausada» | FOS ha pausado la integración | Contacta con soporte. |
Preguntas frecuentes#
¿Qué hace la integración de ACI Hotel con Ágora?#
Cierra el ticket como albarán a nombre del cliente de Ágora que representa la habitación, con la firma del huésped. No se comunica con ACI Hotel.
¿El cargo llega a ACI Hotel?#
No. El albarán se queda en Ágora; cómo lo recoge después el hotel depende de su forma de trabajar, no de Connect Manager.
¿Cómo encuentra la habitación?#
Con una consulta personalizada de Ágora que busca el cliente cuyo nombre fiscal es el número de habitación, y toma el primero.
¿Cómo se imprime la firma en el albarán?#
Ágora envía el albarán a la URL de facturas de Connect Manager y la respuesta incluye la firma; hace falta «Enviar albaranes» y una plantilla ESC/POS.
¿Dónde consulto las firmas de una habitación?#
En la URL de consulta de cargos de habitación, por número de habitación y fechas.
Referencias#
- Ficha de la integración con ACI Hotel
- Hotel Hub: cómo funciona
- Integración de Sihot con Ágora: la misma configuración de acción personalizada y URL de documentos en Ágora
- Direcciones IP de Connect Manager