Integración de Guest Pro con Ágora: cargos a habitación

La integración de Guest Pro (GuestPro) con Ágora permite cargar a la habitación del huésped lo que consume en el restaurante o el bar del hotel: el camarero busca la habitación desde el TPV, pulsa Cargar y el ticket pasa a un albarán en Ágora y a un cargo en Guest Pro, agrupado por extras. Todo pasa por Connect Manager, que guarda el registro de cada cargo.

Este manual es para el técnico de FOS o del distribuidor que la configura: qué datos pedir, dónde meterlos, cómo funciona, cómo comprobarla y qué hacer cuando falla.

Qué hace la integración#

• Abre desde Ágora, con una acción personalizada, la pantalla de cargo de Connect Manager dentro de un diálogo del TPV.
• Busca la habitación en Guest Pro por número y muestra el huésped y las fechas de la estancia (Desde y Hasta).
• Si activas Solicitar firma, recoge la firma del huésped en pantalla y envía a Guest Pro el enlace de la imagen con el cargo.
• Pasa el ticket a un albarán de Ágora sobre el cliente que configures, con el nombre del huésped y la habitación (Nombre Apellido (Nº hab.: 101)), y lo imprime.
• Envía el cargo a Guest Pro agrupado por extras: cada familia de Ágora puede ir a un extra distinto y el resto va al extra por defecto. Cada extra lleva el importe, con los descuentos del ticket repartidos, y en el comentario la lista de productos con unidades e importes.
• Guarda en Connect Manager cada operación: el ticket, el albarán, lo enviado a Guest Pro y su respuesta.
• Puede mandar a Guest Pro el cierre de ventas del día (las facturas de Ágora de la jornada) como una factura genérica, agrupada por extras y formas de pago. Lee antes sus limitaciones.

Qué no hace#

• No anula en Guest Pro un cargo ya enviado. Si devuelves o anulas el albarán en Ágora, el cargo hay que quitarlo en Guest Pro.
• No busca por número de tarjeta. La pantalla enseña el buscador Nº de tarjeta, pero Connect Manager no envía ese dato a Guest Pro: solo funciona Nº de habitación.
• No comprueba crédito ni bloqueos de la reserva, no envía propinas (no hay campo) y no envía las facturas de Ágora una a una.
• No sincroniza reservas, disponibilidad ni tarifas.
• Cierre del día: el envío automático a la Hora de generación fich. contable depende de una tarea programada del motor que hoy no está activa, y el panel no tiene botón para generar un cierre nuevo de Guest Pro (el de la pantalla de Inicio es solo para Sihot y UbikOS): solo se puede reenviar uno que ya exista en Cierres de caja. Confírmalo con FOS antes de ofrecerlo.

Requisitos#

• Connect Manager: el local dado de alta en app.connectmanager.es con la URL de la API y la API key de Ágora. El alta del local y de la integración la hace FOS (el botón Añadir solo lo ven los administradores); el distribuidor revisa y completa el resto.
• Ágora: acceso para crear acciones personalizadas y botones, y un cliente genérico para los cargos a habitación (por ejemplo, HUÉSPEDES HOTEL).
• Conectividad: Connect Manager tiene que llegar a la API de Ágora (puerto 8984), publicada o con Zero Connect. La usan el panel (búsqueda de clientes, familias y formas de pago), el cierre del día y, con Usar el API externa de Ágora marcada, que es el valor por defecto, el propio cargo. Si el cliente filtra por IP, consulta las direcciones IP de Connect Manager.
• Guest Pro: acceso a su API (Access Token y Access Token Secret), el identificador del hotel y los extras de los cargos ya creados.

Reparto de tareas: FOS da de alta el local y la integración; el distribuidor rellena los campos, asocia familias y formas de pago y configura Ágora; el hotel o Guest Pro facilita credenciales, Id. del hotel, extras y, si se usa el cierre, la serie de facturación.

Datos que necesitamos#

Configuración paso a paso#

En Guest Pro#

1. Pide al hotel o a Guest Pro el Access Token, el Access Token Secret y el identificador del hotel.
2. Comprueba que existen los extras de los cargos: uno por defecto y, si se quiere separar conceptos, uno por grupo de familias (bar, restaurante…).
3. Si se va a usar el cierre, pide el identificador de la serie de facturación y las formas de pago de Guest Pro.

En Connect Manager: datos del local#

1. Entra en https://app.connectmanager.es y ve a Administración → Locales. Abre el local.
2. Revisa URL de API y API key (las de Ágora o las del ACMS si es un grupo) y pulsa el botón de prueba junto a la URL: debe salir Conexión con éxito.
3. Pulsa Guardar.

En Connect Manager: la integración de hoteles#

1. En la columna de la derecha, entra en Integraciones → Integraciones de hoteles. Abre la de Guest Pro o, si eres administrador, pulsa Añadir y elige el Proveedor Guest Pro.
2. En Conf. general rellena URL Api: (vacía para la de Guest Pro), Access Token:, Access Token Secret:, Id. del hotel y, si quieres avisos, Email de receptor de notificaciones (escribe cada dirección y pulsa Intro). Ahí llegan los errores del cierre del día; los fallos de un cargo no se avisan por correo.
3. En Conf. de cargos ajusta las opciones de la tabla de abajo y elige el Cliente.
4. Pulsa Guardar: sale Se ha guardado la integración de hoteles y se activan las pestañas Familias y Métodos de pago.
5. Ya guardada, aparece Entidad externa (servicio, etc.) con los extras de Guest Pro: elige el extra por defecto y guarda otra vez.
6. En Familias, pulsa Añadir por cada familia con extra propio: Familia (de Ágora) y Entidad externa (servicio, etc.).
7. Métodos de pago solo lo usa el cierre: por cada forma de pago de Ágora, Método de pago de Agora y Método de pago Guest pro. Las que no asocies van como la forma de pago 1 de Guest Pro.
8. Solo con cierre: en Conf. de Z-cierre marca Z-cierre y rellena Serie de facturación, Nombre de cliente fact., CIF fact., Dirección fact., Cód. postal fact., Ciudad fact., Región fact. y Hora de generación fich. contable. El país va fijo a España.
9. En Enlaces, copia la URL botón acción personalizada.

Pausar el envío de cargos al PMS y Pausar el envío de cargos al PMS después de solo los ven los administradores de FOS; con el envío pausado, el TPV muestra Integración pausada.

[!NOTE] En el hub (hub.connectmanager.es, /admin → Locales → Añadir integración) hay un proveedor GuestPro (PMS) con Código Interno del Hotel, Client Secret (Token) y Forma de Pago Ágora ID. Ese formulario solo guarda datos: ningún proceso los usa ni da URLs para Ágora. No lo des de alta: la integración que carga en Guest Pro es la de app.connectmanager.es, que aparece en el hub en solo lectura tras Sincronizar Integraciones.

En Ágora#

1. Si no existe, crea el cliente genérico para los cargos a habitación y comprueba que es el elegido en Cliente.
2. Ve a Herramientas → Acciones personalizadas y pulsa + Nuevo: Texto «Cargo habitación», Tipo Url/Aplicación y, en Acción, la URL copiada tal cual, con sus marcadores {user_id}, {pos_id}, {ticket_global_id}… que rellena Ágora.
3. Marca Mostrar Urls en un diálogo de Ágora. Es obligatorio: la pantalla habla con el TPV a través de ese diálogo y, en un navegador aparte, no puede leer el ticket.
4. En Herramientas → Configuración de Botones, coloca la acción en un botón del perfil del local (o en el menú Otros) y da su permiso a los perfiles de los usuarios que vayan a cargar.

La URL tiene esta forma, precedida del dominio que muestre el panel: /venues/123/hotels/guest-pro/query-chargeable-room/?user={user_id}&pos_id={pos_id}&ticket_id={ticket_id}&ticket_global_id={ticket_global_id}&ticket_line_index={ticket_line_index}&introduced_value={introduced_value}. Guest Pro no necesita la integración de documentos de Ágora.

Cómo funciona#

El camarero pulsa la acción con el ticket del huésped abierto. Se abre en un diálogo la pantalla de Connect Manager («Busque por nº de habitación o nº de tarjeta.»). Al escribir la habitación, Connect Manager consulta a Guest Pro y enseña habitación, cliente y fechas. Si se pide, el huésped firma. Al pulsar Cargar, primero se crea el albarán en Ágora, que cierra el ticket, y después se envía el cargo a Guest Pro. Si Guest Pro lo acepta, sale «Se generó el siguiente cargo:» con su identificador y el diálogo se cierra a los dos segundos.

sequenceDiagram
    participant C as Camarero
    participant AG as Ágora
    participant CM as Connect Manager
    participant GP as Guest Pro
    C->>AG: Pulsa la acción Cargo habitación
    AG->>CM: Abre la pantalla de cargo en un diálogo
    C->>CM: Escribe el nº de habitación
    CM->>GP: Consulta la habitación con el Id. del hotel
    GP-->>CM: Huésped y fechas de la estancia
    C->>CM: Firma si se pide y pulsa Cargar
    CM->>AG: Crea el albarán del ticket
    AG-->>CM: Albarán con serie y número
    CM->>GP: Envía el cargo agrupado por extras
    GP-->>CM: Cargo aceptado con su identificador
    CM-->>C: Se generó el siguiente cargo

El cargo lleva el Id. del hotel, la habitación devuelta por la búsqueda, serie, número y fecha del albarán, el enlace de la firma si la hay y una línea por extra (una unidad, el importe y un comentario del tipo Agua (2 unid.): 4,00€ por producto). Solo cuentan las líneas normales y las cabeceras de menú con importe. Cada petición a Guest Pro se intenta hasta tres veces, con medio segundo entre intentos.

Como el albarán se crea antes del cargo, si Guest Pro lo rechaza el albarán ya existe en Ágora y no hay anulación automática: hay que devolverlo a mano (en un rechazo de Guest Pro, el mensaje indica su serie y número). Con Usar el API externa de Ágora marcada, si Connect Manager no llega a la API de Ágora el cargo no se hace.

El cierre del día#

Al lanzarse un cierre, Connect Manager pide a Ágora las facturas de ese día de negocio, suma los importes por extra (con las asociaciones de familias) y por forma de pago, y crea en Guest Pro una factura genérica con la serie y los datos fiscales configurados. El resultado queda en Operaciones hoteleras → Cierres de caja (Creado, Enviado, Error o No hay datos), con la solicitud, la respuesta y el error en el detalle. Si falla la lectura de Ágora, se avisa por correo.

flowchart TD
    A[Lanzamiento del cierre de un día] --> B[Connect Manager pide a Ágora las facturas del día]
    B --> C[Suma importes por extra y por forma de pago]
    C --> D[Crea una factura genérica en Guest Pro]
    D --> E{Respuesta de Guest Pro}
    E -->|success| F[Estado Enviado]
    E -->|error| G[Estado Error con el mensaje]

[!WARNING] Reenviar con Exportar un cierre de Guest Pro ya Enviado lo manda otra vez entero: Connect Manager no lo impide y en Guest Pro quedaría duplicado. Y si la URL de API del local es la de un ACMS con varios locales, solo se envía el primero que devuelve Ágora.

Comprobar que funciona#

1. La prueba de la URL de API del local da Conexión con éxito; en la integración, Cliente lista clientes de Ágora y Entidad externa (servicio, etc.) lista extras de Guest Pro.
2. Abre en Ágora un ticket de prueba con un producto barato y pulsa la acción: se abre el diálogo con los buscadores.
3. Busca una habitación ocupada de prueba: salen cliente y fechas.
4. Pulsa Cargar (y firma si está activado): debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo.
5. En Ágora queda el albarán impreso a nombre de «huésped (Nº hab.: …)».
6. En Guest Pro, el cargo está en la habitación con el extra correcto y el detalle en el comentario.
7. En Operaciones hoteleras → Cargos aparece la operación con Pedido externo (request) y Pedido externo (response).
8. Anula el albarán de prueba en Ágora y quita el cargo a mano en Guest Pro.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Guest Pro con Ágora?#

FOS da de alta la integración de hoteles con el proveedor Guest Pro en Connect Manager; tú rellenas Access Token, Access Token Secret e Id. del hotel, eliges el cliente y el extra por defecto y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo.

¿Se puede anular desde Ágora un cargo enviado a Guest Pro?#

No. Anular o devolver el albarán en Ágora no toca Guest Pro: el cargo hay que quitarlo a mano allí.

¿Se puede buscar al huésped por tarjeta o por nombre?#

No. Aunque la pantalla muestra el buscador de tarjeta, solo funciona la búsqueda por número de habitación.

¿Qué pasa si no asocio las familias?#

Todo el ticket va al extra por defecto, en una línea con el detalle de productos en el comentario. Asócialas solo si el hotel quiere separar conceptos.

¿Para qué sirve el proveedor GuestPro (PMS) del hub?#

Para nada operativo: guarda datos pero no carga nada en Guest Pro. La integración que funciona es la de app.connectmanager.es.

Referencias#

• Ficha del catálogo: Guest Pro
• Visión general de los cargos a habitación: Hotel Hub: cómo funciona
• Otros PMS: Sihot, Hospedium, UbikOS y Redforts
• Zero Connect: conectar Ágora sin abrir puertos
• Direcciones IP de Connect Manager