Hotel Hub: cómo funcionan los cargos a habitación desde Ágora

Hotel Hub es la parte de Connect Manager que conecta el TPV Ágora con el PMS del hotel para cargar los consumos del restaurante, el bar o el room service a la habitación del huésped. Este manual explica lo que tienen en común todas las integraciones de PMS (la acción personalizada que abre la pantalla de cargo, el albarán, las anulaciones, el envío de las ventas de clientes no alojados, los mapeos, la pausa y los avisos) y compara qué hace cada PMS. Es el punto de partida para el técnico antes de abrir el manual de su PMS.

Qué hace Hotel Hub#

• Pone en el TPV un botón (una acción personalizada de Ágora) que abre, sobre el ticket abierto, la pantalla de cargo a habitación de Connect Manager.

• Busca en el PMS la habitación o el huésped y muestra los datos de la reserva antes de cargar.

• Aplica las comprobaciones que ofrece cada PMS: reservas alojadas, bloqueos, reservas que no admiten cargos, crédito o fechas.

• Recoge la firma del huésped en los PMS que lo permiten.

• Convierte el ticket en un albarán de Ágora a nombre de un cliente genérico, con el nombre del huésped y su habitación.

• Envía el cargo al PMS con el detalle que acepta cada uno: un total, líneas por producto, por familia o por servicio.

• Anula el cargo en el PMS cuando se cancela el albarán en Ágora, en los PMS que lo admiten.

• Envía al PMS las ventas de clientes no alojados, factura a factura en tiempo real o en un cierre diario, según el PMS.

• Traduce familias, centros de venta, formas de pago y turnos de comida de Ágora a los códigos del PMS.

• Guarda cada cargo, factura y cierre enviados, con lo que se mandó y lo que contestó el PMS, para revisarlos desde el panel.

Qué no hace#

• No sincroniza reservas ni disponibilidad, no hace check-in ni check-out y no crea huéspedes en el PMS ni clientes en Ágora: en ningún PMS.

• La pausa del envío de cargos solo bloquea la pantalla de cargo: las facturas y cancelaciones que Ágora manda a la URL de documentos se siguen procesando.

• Hoy la opción Nº de días para cerrar albaranes no cierra nada y el cierre diario de ventas (Z-cierre) no se envía solo: las tareas programadas que los hacen están desactivadas en el planificador de la versión actual del motor (ver más abajo).

• Algunas integraciones dan el cargo por bueno sin leer la respuesta del PMS: Winhotel y Ofi-Hotel solo miran que no haya un error de comunicación y Noovy ni siquiera avisa en el TPV si el PMS lo rechaza.

Las piezas#

• Connect Manager (app.connectmanager.es): guarda la ficha del local con la URL y la API key de Ágora, la integración de hoteles con las credenciales del PMS y sus opciones, sirve la pantalla de cargo y recibe los documentos de Ágora.

• Ágora: la acción personalizada abre la pantalla de cargo con los datos del ticket; la integración de documentos con sistemas externos avisa a Connect Manager de cada albarán y cada factura; la API del integrador permite leer el ticket y crear el albarán.

• El PMS: responde a las búsquedas y recibe los cargos, las anulaciones y las ventas.

Hay, por tanto, dos caminos: el de la pantalla de cargo, que el camarero abre a mano, y el de la URL de documentos, que Ágora usa sola cada vez que crea o cancela un albarán o emite una factura.

flowchart LR
    TPV[TPV Ágora] -- Acción personalizada --> P[Pantalla de cargo]
    P -- Búsqueda y cargo --> PMS[PMS del hotel]
    P -- Crea el albarán --> TPV
    TPV -- Albaranes y facturas --> D[URL de documentos]
    D -- Anulaciones y ventas --> PMS

Cómo funciona un cargo a habitación#

El camarero abre el ticket del huésped y pulsa la acción personalizada. La pantalla de Connect Manager se abre dentro del TPV con el ticket, el TPV y el usuario. El camarero busca la habitación o el huésped, revisa los datos de la reserva, recoge la firma si se pide y pulsa Cargar. Connect Manager crea el albarán en Ágora y envía el cargo al PMS. Si todo va bien, la pantalla muestra el resultado y se cierra sola a los dos segundos.

sequenceDiagram
    participant C as Camarero
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant PMS as PMS
    C->>TPV: Pulsa la acción personalizada en el ticket
    TPV->>CM: Abre la pantalla con el ticket, el TPV y el usuario
    C->>CM: Busca la habitación o el huésped
    CM->>PMS: Consulta la reserva
    PMS-->>CM: Huésped, fechas y datos de la reserva
    CM-->>C: Reserva o motivo por el que no admite cargos
    C->>CM: Firma si se pide y pulsa Cargar
    CM->>TPV: Crea el albarán a nombre del cliente genérico
    CM->>PMS: Envía el cargo
    PMS-->>CM: Cargo aceptado o rechazado
    CM-->>C: Mensaje y cierre de la ventana

Hay dos excepciones. En Protel sin albaranes, el botón solo elige la reserva y el cargo viaja dentro de la factura al cobrar con una forma de pago de cargo a habitación. ACI Hotel no habla con el PMS: busca la habitación entre los clientes de Ágora y deja el albarán con la firma en Ágora.

La acción personalizada#

La URL que da Connect Manager lleva unos marcadores entre llaves ({user_id}, {pos_id}, {ticket_id}, {ticket_global_id}, {ticket_line_index} e {introduced_value}) que Ágora sustituye por los datos del ticket al pulsar el botón. Hay que pegarla tal cual. En TPV que no son móviles, la pantalla muestra un teclado en pantalla al tocar los buscadores.

Buscar la habitación o el huésped#

Todos los PMS buscan por número de habitación. Algunos añaden búsqueda por nombre o apellido, por tarjeta, por grupo o por folio; la tabla comparativa lo resume. Cuando la búsqueda devuelve varias reservas, unos PMS muestran una lista para elegir (Cloudbeds, Noovy, Hospedium, Redforts…) y otros toman la primera.

Comprobaciones antes de cargar#

No hay una comprobación común: cada integración usa lo que devuelve su PMS. Por ejemplo, Ulyses tiene las opciones Comprobar fechas de reserva y Comprobar si hay crédito disponible; Protel no deja cargar a reservas bloqueadas salvo con Permitir cargos bloqueados; Shiji y Lean avisan con «La reserva no admite cargos» cuando el PMS lo indica; Cloudbeds y Redforts solo encuentran reservas con check-in hecho; Sihot solo carga en habitaciones ocupadas. Otros, como Mews o Noovy, no comprueban crédito ni bloqueos.

La firma#

En los PMS con firma (Mews, Sihot y Guest Pro con Solicitar firma; ACI Hotel siempre), la pantalla muestra un recuadro para firmar con el dedo y un botón Borrar. La firma se guarda como imagen junto al cargo. En Mews, Sihot y ACI Hotel, cuando Ágora envía el albarán a la URL de documentos, Connect Manager le devuelve la firma para imprimirla en el propio albarán.

El albarán en Ágora#

El albarán se crea desde el ticket abierto, a nombre del Cliente que se elige en la integración (un cliente genérico de Ágora), pero con el nombre del huésped y su habitación, por ejemplo «Ana López (Nº hab.: 101)», y se imprime. La opción Dejar abierto el albarán decide si queda pendiente, que es lo que permite cancelarlo después desde Ágora para anular el cargo. Mews, Lean y ACI Hotel lo dejan siempre abierto.

En la mayoría de los PMS el albarán se crea antes de enviar el cargo. Si el PMS rechaza el cargo, el albarán ya existe en Ágora y hay que devolverlo (varias pantallas lo piden en el propio mensaje). Antes de hacerlo, revisa el manual del PMS: en algunos la anulación se envía al PMS aunque el cargo no hubiera entrado.

Usar el API externa de Ágora#

En Guest Pro, Lean, Protel, Mews y ACI Hotel existe la casilla Usar el API externa de Ágora. Activada, Connect Manager lee el ticket y crea el albarán llamando a la API de Ágora desde internet, así que esa API tiene que ser accesible desde fuera (puerto abierto o Zero Connect). Desactivada, es la propia pantalla la que pide al TPV que lo haga, sin salir de la red del local. En los demás PMS no hay casilla: cada integración lo hace siempre de la misma forma, casi siempre a través del TPV. En todos los casos la API de Ágora tiene que estar accesible para las listas del panel (clientes, formas de pago, familias, centros de venta) y para las tareas programadas.

Anular un cargo#

El cargo se anula cancelando el albarán en Ágora. Ágora envía el documento de cancelación a la URL para enviar facturas desde Ágora; Connect Manager busca el cargo original por serie y número de albarán y manda al PMS la anulación (el mismo cargo en negativo o la anulación de la línea, según el PMS). Si el PMS la rechaza, Connect Manager rechaza la cancelación y Ágora no la completa.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant PMS as PMS
    TPV->>CM: Albarán de cancelación a la URL de documentos
    CM->>CM: Busca el cargo original por serie y número
    CM->>PMS: Envía la anulación
    PMS-->>CM: Respuesta
    CM-->>TPV: Acepta o rechaza la cancelación

Para que funcione hacen falta tres cosas: que el PMS admita anulaciones (ver la tabla), que el albarán se haya dejado abierto y que la integración de documentos de Ágora envíe los albaranes a esa URL.

Cierre de albaranes a los N días#

Los albaranes abiertos se quedan pendientes a nombre del cliente genérico. El campo Nº de días para cerrar albaranes fija cuántos días pueden seguir así: pasado ese plazo, una tarea nocturna de Connect Manager marca esos albaranes como cancelados en Ágora, sin tocar el PMS. En la práctica, el plazo es hasta cuándo se puede anular un cargo desde el TPV. Con el campo vacío o a cero, no se cierran.

[!WARNING] En la versión actual del motor, la tarea que cierra los albaranes y la que lanza el Z-cierre están desactivadas en el planificador. Confirma con FOS que están en marcha antes de contar con ellas.

Ventas de clientes no alojados#

Además de los cargos, varios PMS reciben las ventas que no se cargan a habitación. Hay dos formas:

• En tiempo real: Ágora envía cada factura a la URL de documentos y Connect Manager la reenvía al PMS con sus líneas y sus cobros (Protel, Shiji, Lean y Ulyses). Si el PMS la rechaza, o una forma de pago no está asignada, Connect Manager rechaza la factura y Ágora no deja cerrarla. En los PMS que no reciben facturas, la URL las acepta sin hacer nada; Cloudbeds es la excepción: contesta con error, así que no hay que enviarle facturas.

• Cierre diario (Z-cierre): en el bloque Conf. de Z-cierre se activa Z-cierre y se elige la Hora de generación fich. contable. Una tarea que se ejecuta cada 10 minutos por la noche busca las integraciones cuya hora coincide, lee de Ágora las facturas del día de negocio (el mismo día si se ejecuta a partir de las 22:00 y el anterior si es de madrugada) y las envía al PMS. Elige, por tanto, una hora nocturna. En Protel la casilla se llama Enviar facturas diferidas y sustituye al envío en tiempo real.

Los cierres generados se ven en Operaciones hoteleras → Cierres de caja (Creado, Enviado, Error o No hay datos) y las facturas enviadas una a una en Operaciones hoteleras → Facturas. El botón Exportar de Cierres de caja reenvía un día ya generado, y solo funciona para Sihot, Guest Pro, Prestige y Ubikos.

[!NOTE] Como la tarea del Z-cierre está desactivada en la versión actual del motor, hoy no se generan días nuevos de forma automática. Si el hotel necesita el cierre diario, habla antes con FOS.

Familias, centros de venta, métodos de pago y turnos de comida#

Después de guardar la integración se habilitan unas pestañas para traducir los datos de Ágora a los del PMS. Qué pestañas salen depende del PMS:

Algunos PMS no tienen pestañas porque reciben los identificadores de Ágora tal cual (Protel, y Shiji para el centro de ingresos y los códigos de ingreso): ahí la correspondencia la hace el propio PMS.

Pausar el envío de cargos#

Los administradores de FOS ven en Conf. general dos campos: Pausar el envío de cargos al PMS (casilla) y Pausar el envío de cargos al PMS después de (fecha). Cada madrugada, una tarea marca como pausadas las integraciones cuya fecha ya ha pasado. Con la integración pausada, la pantalla de cargo muestra «Integración pausada» y no deja cargar, y el resto de usuarios ve en la integración el aviso «El envío de cargos al PMS está actualmente suspendido. Por favor, contacte con el soporte para reactivarlos.»

Avisos por correo#

El campo Email de receptor de notificaciones admite varias direcciones. Ahí llegan, con el asunto «Error en aplicación», los fallos de las tareas en segundo plano: Z-cierre, cierre de albaranes, envíos diferidos e importaciones de datos de Mews. En Cloudbeds llega además el aviso «Aplicación de Cloudbeds desconectada» si el hotel desconecta la aplicación. Los errores al cargar desde el TPV no se envían por correo: se ven en la propia pantalla y en Operaciones hoteleras → Cargos.

Comparativa de PMS#

Resumen de lo que hace cada integración según el código del motor. El detalle y las condiciones están en el manual de cada PMS.

«Cierre diario (Z-cierre)» depende de la tarea programada que hoy está desactivada (ver el aviso de la sección anterior). En Winhotel, Ofi-Hotel y Noovy, comprueba en el PMS los primeros cargos: las dos primeras no leen lo que contesta el PMS y Noovy no avisa en el TPV de los rechazos. Ningún PMS sincroniza reservas ni disponibilidad.

Requisitos y reparto de tareas#

• Ágora: licencia del Módulo de Servicios de Integración (activa la API del integrador y la integración de documentos), un cliente genérico para los albaranes y los perfiles de usuario con el permiso de la acción personalizada.

• API de Ágora accesible desde Connect Manager con la URL y la API key del local (puerto abierto o Zero Connect).

• PMS: credenciales de su API para el hotel y, según el PMS, los códigos de productos, servicios, formas de pago o turnos.

• FOS da de alta el local y la integración de hoteles: el botón Añadir de Integraciones de hoteles solo lo ven sus administradores, igual que la pausa.

• El distribuidor revisa la ficha del local, completa las opciones y los mapeos y configura Ágora.

• El hotel (o su PMS) facilita las credenciales y decide cómo quiere ver los cargos en el PMS.

Datos que necesitamos#

Configuración común paso a paso#

En Connect Manager#

1. En Administración → Locales, abre el local y revisa Cliente, Nombre, URL de API, API key, Dirección, Ciudad y Zona horaria. Pulsa Guardar. La zona horaria se usa para las fechas de los albaranes y los cargos.

2. Entra en Integraciones de hoteles. FOS pulsa Añadir y elige el Proveedor.

3. En Conf. general, rellena las credenciales que pida el PMS y el Email de receptor de notificaciones, y pulsa Guardar.

4. En Conf. de cargos, elige el Cliente, decide Dejar abierto el albarán y el Nº de días para cerrar albaranes si el PMS los muestra, y las opciones propias del PMS.

5. Si el PMS tiene Conf. de Z-cierre, decide si se usa (ver el aviso).

6. Completa las pestañas de mapeo, que se habilitan después de guardar.

7. Copia del bloque Enlaces la URL botón acción personalizada y, si aparece, la URL para enviar facturas desde Ágora.

En Ágora#

1. En Herramientas → Acciones personalizadas, crea la acción con la URL tal cual y marca que se muestre en un diálogo.

2. La acción crea un permiso: añádelo a los perfiles de los usuarios que vayan a cargar a habitación.

3. En la integración de documentos con sistemas externos (Activar módulos adicionales → Servicios de integración), pega la URL para enviar facturas desde Ágora, habilita la integración de documentos y marca el envío de albaranes (anulaciones e impresión de la firma) y, si el PMS las recibe, de facturas.

Comprobar que funciona#

1. Las listas del panel (Cliente, formas de pago, familias) cargan datos: hay conexión con la API de Ágora.

2. En el TPV, con un usuario de prueba, la acción personalizada aparece y abre la pantalla de cargo.

3. La búsqueda de una habitación ocupada devuelve el huésped.

4. Al cargar, aparece el albarán en Ágora a nombre del huésped y el cargo en el PMS.

5. En Operaciones hoteleras → Cargos, el registro tiene el Id. de pedido externo relleno.

6. Si el PMS admite anulaciones, cancelar el albarán de prueba anula el cargo en el PMS.

7. Si el PMS recibe facturas, una factura de prueba se cierra en Ágora y aparece en Operaciones hoteleras → Facturas como «Aceptado».

Errores frecuentes y solución#

Preguntas frecuentes#

¿Qué es Hotel Hub de Connect Manager?#

Es el conjunto de integraciones que conectan Ágora con el PMS del hotel para cargar consumos a la habitación, anularlos y, según el PMS, enviar las ventas del TPV.

¿Qué PMS se pueden conectar con Ágora?#

Los de la tabla comparativa: Mews, Cloudbeds, Protel, Shiji, Lean, Noovy, Ulyses, Millenium, Prestige, Winhotel, Ofi-Hotel, ACI Hotel, Guest Pro, Hospedium, Ubikos, Redforts y Sihot. El motor también tiene código para RoomRaccoon, Amenitiz y Oracle OHIP, que no entran en esta comparativa.

¿Cómo se carga un ticket a la habitación desde Ágora?#

Con el ticket abierto, se pulsa la acción personalizada, se busca la habitación, se firma si se pide y se pulsa Cargar. El ticket pasa a un albarán en Ágora y el cargo llega al PMS.

¿Se puede anular desde Ágora un cargo a habitación?#

Sí en los PMS que lo admiten: cancelando el albarán, si se dejó abierto y la integración de documentos de Ágora está configurada.

¿Las ventas de clientes no alojados llegan al PMS?#

En Protel, Shiji, Lean y Ulyses, factura a factura en tiempo real. En otros hay un cierre diario que hoy depende de una tarea desactivada. Algunos PMS no las reciben.

¿Hotel Hub sincroniza las reservas del hotel con Ágora?#

No. Las reservas solo se consultan en el PMS en el momento de cargar; no se copian a Ágora.

Referencias#

• Integración de Mews con Ágora, Cloudbeds, Protel, Shiji, Lean y Noovy

• Integración de Sihot con Ágora

• Direcciones IP salientes de Connect Manager

• Glosario de Connect Manager