La integración de Noovy con Ágora permite cargar un ticket del TPV a la reserva de un cliente alojado en Noovy desde una acción personalizada de Ágora: el camarero busca por habitación o por nombre, elige la reserva y Connect Manager crea el albarán en Ágora y envía el consumo a Noovy, en un solo importe o repartido por familias. Este manual es para el técnico que la configura: qué datos pedir, cómo rellenar Connect Manager y Ágora, cómo comprobarla y qué vigilar.
Qué hace la integración#
Busca los clientes alojados por número de habitación o por nombre y muestra una lista con la habitación, el cliente y el número de reserva, cada uno con su botón Cargar.
Crea el albarán en Ágora a nombre del cliente con su número de habitación.
Envía el consumo a la reserva en Noovy de una de estas dos formas:
Sin agrupar: un único importe con el total del ticket y el ID producto Noovy por defecto.
Con Agrupar productos por familia: un importe por cada familia de Ágora con el producto de Noovy que le hayas asignado; las familias sin asignar se suman al producto por defecto.
Pone en la descripción de cada importe el número del albarán de Ágora.
Anula el cargo al cancelar el albarán en Ágora, enviando los mismos importes en negativo, si la integración de documentos de Ágora apunta a la integración (ver el aviso de la configuración).
Renueva sola la sesión con Noovy cuando caduca.
Qué no hace#
No avisa en el TPV si Noovy rechaza el cargo: la pantalla dice «Albarán enviado correctamente» aunque el cargo no haya entrado. Hay que comprobarlo en Connect Manager (ver Comprobar que funciona).
No descuenta los descuentos a pie de ticket: envía la suma de las líneas, así que si el ticket lleva un descuento global, a Noovy llega el importe sin ese descuento.
No envía propinas, comensales ni el desglose de IVA.
No comprueba el crédito ni el estado de la reserva, ni recoge la firma.
No envía facturas ni hace Z-cierre.
Si no hay ID producto Noovy por defecto y no se agrupa por familia, no se envía nada a Noovy.
El cierre de albaranes a los N días depende de una tarea nocturna que en la versión actual del motor está desactivada.
No sincroniza reservas ni disponibilidad.
Requisitos#
Noovy: el Código PMS del hotel y los productos de Noovy donde se cargarán los consumos. Connect Manager se identifica en Noovy con unas credenciales de Ágora que ya trae configuradas: no hay que pedir usuario ni contraseña al hotel.
Ágora: licencia del Módulo de Servicios de Integración, una acción personalizada en el TPV y, para las anulaciones, la integración de documentos con sistemas externos enviando albaranes.
Conectividad: el albarán se crea desde el propio TPV. Aun así, el local tiene que tener en Connect Manager la URL de API y la API key de Ágora, accesible desde fuera (puerto abierto o Zero Connect), para las listas del panel y las tareas programadas.
Quién hace qué: FOS da de alta el local y la integración (el botón Añadir solo lo ven los administradores de FOS). El distribuidor elige productos y opciones y configura Ágora. El hotel facilita el Código PMS y decide los productos.
Datos que necesitamos#
| Dato | Quién lo facilita / dónde se saca | Ejemplo o formato | Obligatorio |
|---|---|---|---|
| URL de la API de Noovy | FOS | La que indique FOS | Sí |
| Código PMS del hotel | El hotel o Noovy | hotel-demo | Sí |
| ID del producto de Noovy por defecto | El hotel, desde Noovy | Identificador del producto «Restaurante» | Sí en la práctica |
| Producto de Noovy por familia de Ágora | El hotel, de la lista que trae Noovy | Bebidas → «Bar» | Solo si se agrupa por familia |
| Cliente genérico de Ágora para los albaranes | Distribuidor, en Ágora | «CLIENTES HOTEL» | Sí |
| URL de API y API key de Ágora del local | Distribuidor | http://servidor:8984 | Sí (en la ficha del local) |
| Email para los avisos | Cliente o distribuidor | avisos@hotel-demo.es | Recomendado |
Configuración paso a paso#
En Noovy#
Pide al hotel su Código PMS en Noovy.
Que el hotel decida en qué producto de Noovy se cargan los consumos y, si quiere separarlos, qué producto corresponde a cada familia.
En Connect Manager: alta de la integración (FOS)#
Entra en Administración → Locales, abre el local y revisa URL de API, API key y Zona horaria. Pulsa Guardar.
Pulsa Integraciones de hoteles → Añadir y elige el Proveedor Noovy.
Rellena URL Api: y Código PMS, y añade el Email de receptor de notificaciones. Las credenciales de Noovy no aparecen en el formulario: las pone Connect Manager.
Pulsa Guardar.
En Connect Manager: opciones de los cargos#
En el bloque Conf. de cargos:
Agrupar productos por familia: desmarcada, todo el ticket va en un importe con el producto por defecto; marcada, un importe por familia según la pestaña Productos.
ID producto Noovy por defecto: el identificador del producto de Noovy. Como indica el propio campo, se usa cuando una familia no está asignada o cuando no se agrupa por familia. Rellénalo siempre.
Dejar abierto el albarán: márcalo para poder anular los cargos cancelando el albarán en Ágora.
Nº de días para cerrar albaranes: plazo tras el que la tarea de cierre marcaría como cancelados los albaranes abiertos (ver el aviso).
Cliente: el cliente genérico de Ágora de los albaranes. El nombre del albarán se sustituye por el del cliente y su habitación.
Si vas a agrupar por familia, guarda y entra en la pestaña Productos: por cada Familia de Ágora, elige su Producto Noovy en la lista, que se carga desde Noovy.
Copia del bloque Enlaces la URL botón acción personalizada.
[!WARNING] En Noovy el panel no muestra la URL para enviar facturas desde Ágora, que es la que usa Ágora para avisar de las cancelaciones. Sin ella no se anulan cargos en Noovy. Tiene la misma forma que en el resto de PMS (
…/api/venues/ID-DEL-LOCAL/hotels/noovy/generate-invoice): pídesela a FOS si el hotel quiere anular desde Ágora.
[!WARNING] El cierre automático de albaranes depende de una tarea programada de Connect Manager que, en la versión actual del motor, está desactivada.
En Ágora#
En Herramientas → Acciones personalizadas, crea una acción con la URL botón acción personalizada tal cual, con los marcadores entre llaves: Ágora los rellena solo. Marca que la URL se muestre en un diálogo y añade el permiso que crea a los perfiles de usuario.
Si se van a anular cargos, en la integración de documentos con sistemas externos (Activar módulos adicionales → Servicios de integración) pega la URL de documentos que te dé FOS, habilita la integración de documentos y marca el envío de albaranes.
Cómo funciona#
Al abrir la acción personalizada, la pantalla lee el ticket desde el TPV. El camarero busca por habitación o por nombre y Connect Manager consulta a Noovy los clientes de ese hotel. La pantalla lista las reservas encontradas; al pulsar Cargar en una, el TPV crea el albarán y Connect Manager envía el consumo a Noovy. Después la pantalla muestra «Albarán enviado correctamente» y se cierra.
sequenceDiagram
participant C as Camarero
participant TPV as TPV Ágora
participant CM as Connect Manager
participant N as Noovy
C->>TPV: Pulsa la acción personalizada
TPV->>CM: Abre la pantalla y le pasa el ticket
C->>CM: Busca por habitación o por nombre
CM->>N: clients con el código PMS
N-->>CM: Clientes, habitaciones y reservas
C->>CM: Pulsa Cargar en una reserva
CM->>TPV: Pide crear el albarán desde el TPV
TPV-->>CM: Albarán creado
CM->>N: add-extras con los importes
N-->>CM: Resultado de cada importe
CM-->>C: Albarán enviado correctamente
Cada importe enviado lleva el número de reserva, el grupo si lo hay, una unidad, el producto de Noovy, la descripción con el número del albarán y el importe en euros. Solo cuentan los productos y las cabeceras de menú; con la agrupación por familia, las líneas a cero se ignoran. Connect Manager guarda la respuesta de Noovy, pero si Noovy rechaza algún importe no lo comunica al TPV: el albarán queda creado en Ágora y el mensaje es el mismo.
Anulaciones#
Si Ágora envía las cancelaciones a la URL de documentos de la integración, al cancelar el albarán Connect Manager vuelve a mandar a Noovy los mismos importes en negativo. Si Noovy los rechaza, la cancelación se rechaza en Ágora. Connect Manager no comprueba si el cargo original llegó: si había fallado, la anulación se envía igualmente.
sequenceDiagram
participant TPV as TPV Ágora
participant CM as Connect Manager
participant N as Noovy
TPV->>CM: Albarán de cancelación
CM->>CM: Busca el cargo por serie y número
CM->>N: add-extras con los importes en negativo
N-->>CM: Resultado
CM-->>TPV: Acepta o rechaza la cancelación
Comprobar que funciona#
Si agrupas por familia, al entrar en Productos la lista Producto Noovy debe cargar los productos del hotel: eso confirma la URL y el Código PMS.
En Ágora, abre un ticket de prueba sin descuento a pie de ticket y pulsa la acción personalizada.
Busca una habitación ocupada: debe salir la reserva con su cliente y su número.
Pulsa Cargar: debe salir «Albarán enviado correctamente» y cerrarse la ventana.
En Connect Manager, en Operaciones hoteleras → Cargos, abre el registro: el Id. de pedido externo debe tener el número de reserva y en Pedido externo (response) no debe haber importes fallidos. Si el Id. está vacío, el cargo no entró en Noovy.
En Noovy, comprueba el consumo en la reserva con la descripción del albarán.
Si configuraste las anulaciones, cancela el albarán de prueba y comprueba el importe en negativo en Noovy.
Errores frecuentes y solución#
| Síntoma | Causa | Solución |
|---|---|---|
| «Albarán enviado correctamente» pero el consumo no está en Noovy | Noovy rechazó el importe, no hay producto por defecto o el total es cero. La pantalla no lo distingue. | Mira la respuesta en Operaciones hoteleras → Cargos, corrige el producto y haz el cargo directamente en Noovy. |
| «No se han encontrado clientes con el criterio especificado» | Noovy no tiene clientes que coincidan con la búsqueda. | Prueba con la habitación o con otra parte del nombre. |
| «Debe introducir un criterio de búsqueda» | Se buscó con los campos vacíos. | Rellena habitación o nombre. |
| Un texto de error de Noovy, o un mensaje que empieza por «NoovyApiProxy:», al buscar | Noovy devolvió un error o no respondió (URL o Código PMS incorrectos, problema de sesión). | Revisa URL Api y Código PMS. |
| El importe en Noovy es mayor que el del ticket | El ticket tenía un descuento a pie de ticket, que no se aplica. | Aplica los descuentos por línea o corrige el importe en Noovy. |
| Cancelar el albarán no anula nada en Noovy | Ágora no envía las cancelaciones a la URL de documentos de la integración. | Pide la URL a FOS y configúrala en la integración de documentos de Ágora. |
| Aparece en Noovy un importe negativo sin cargo previo | Se canceló el albarán de un cargo que nunca entró en Noovy. | Elimina ese importe en Noovy. |
| «No se ha podido generar el albarán. Cierre esta ventana e intente generar el ticket de nuevo.» | El TPV no pudo crear el albarán o Connect Manager no pudo guardarlo. | Mira en Ágora si el albarán existe antes de repetir; si no existe, vuelve a intentarlo desde el ticket. |
| La pantalla muestra «Integración pausada» | FOS ha pausado el envío de cargos. | Contacta con soporte de FOS. |
Preguntas frecuentes#
¿Cómo conecto Noovy con Ágora?#
FOS da de alta la integración con la URL de Noovy y el Código PMS del hotel. Después se elige el producto por defecto, opcionalmente los productos por familia, y se crea en Ágora la acción personalizada.
¿Necesito usuario y contraseña de Noovy?#
No. Connect Manager usa unas credenciales de Ágora que ya trae configuradas; para cada hotel basta con su Código PMS.
¿Se puede buscar en Noovy por el nombre del huésped?#
Sí. La pantalla tiene dos búsquedas: por número de habitación y por nombre del cliente.
¿Cómo sé si un cargo ha llegado a Noovy?#
En Operaciones hoteleras → Cargos de Connect Manager: si el Id. de pedido externo está relleno y la respuesta no tiene importes fallidos, el cargo entró. El mensaje del TPV no sirve para saberlo.
¿Se pueden repartir los consumos por familias en Noovy?#
Sí, marcando Agrupar productos por familia y asignando en la pestaña Productos un producto de Noovy a cada familia.