Integración de Hospedium con Ágora: cargos a habitación

La integración de Hospedium con Ágora permite cargar en la cuenta de la habitación lo que el huésped 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 Hospedium, desglosado por tipo de IVA y con el detalle de productos. 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 por dentro, 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.
• Pide a Hospedium las cuentas abiertas del hotel y enseña las que coinciden con lo que se escribe en Nº de habitación: una tarjeta por cuenta, con la habitación y la tarifa.
• Deja añadir una propina en cada tarjeta antes de cargar.
• Crea el albarán en Ágora desde el propio TPV, a nombre del cliente configurado con el número de habitación (HUÉSPEDES HOTEL (Nº hab.: 101)), y lo imprime.
• Envía el cargo a la cuenta de Hospedium desglosado por tipo de IVA: un concepto por cada tipo, con el número de albarán, el importe con IVA, la fecha y la hora, el nombre del TPV, el identificador del ticket y el detalle de productos (nombre, cantidad, precio con IVA, importe, IVA y referencia del formato de venta).
• Envía la propina como concepto aparte, Propina SERIE/000123, con IVA 0.
• Puede trabajar contra el entorno de pruebas de Hospedium (staging) o contra el real.
• Guarda en Connect Manager cada operación: el ticket, el albarán y lo que se envió a Hospedium.

Qué no hace#

• No comprueba si el huésped sigue alojado, su crédito ni bloqueos: lista las cuentas que Hospedium devuelve.
• No anula en Hospedium el cargo de un albarán anulado. Si devuelves el albarán en Ágora, el cargo hay que quitarlo en Hospedium.
• No pide la firma del huésped.
• No envía facturas ni el cierre de ventas del día, y no hay familias ni formas de pago que asociar.
• No sincroniza reservas, disponibilidad ni tarifas.
• La búsqueda no es exacta: el texto se compara con el nombre de la habitación, así que «1» encuentra la 1, la 10 o la 101. Hay que pulsar Cargar en la tarjeta correcta.

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 de hoteles 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.
• Conectividad: el cargo lo hace el propio TPV a través del diálogo, con su API local, así que la API de Ágora no tiene que estar abierta a Internet para cargar. Sí la necesita el panel para buscar el Cliente al configurar: Connect Manager debe llegar al puerto 8984 de Ágora, publicado o con Zero Connect. Los TPV necesitan salida a Internet para abrir la pantalla de cargo.
• Hospedium: la URL de su API, la firma de integración y el identificador del hotel, y que el hotel abra cuenta a cada habitación ocupada.

Reparto de tareas: FOS da de alta el local y la integración; el distribuidor rellena los campos y configura Ágora; el hotel o Hospedium facilita la URL, la firma y el Id. del hotel, y dice si son de producción o de pruebas.

Datos que necesitamos#

Configuración paso a paso#

En Hospedium#

1. Pide a Hospedium (o al hotel) la URL de la API, la firma de integración y el identificador del hotel.
2. Pregunta si esos datos son del entorno real o del de pruebas: de eso depende la casilla Usar API staging.
3. Confirma con el hotel que las habitaciones ocupadas tienen cuenta abierta en Hospedium: es lo que lista la pantalla de cargo.

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. 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 integración de Hospedium o, si eres administrador, pulsa Añadir y elige el Proveedor Hospedium.
2. En Conf. general rellena URL Api:, Firma: e Id. del hotel. El Email de receptor de notificaciones se puede dejar vacío: con Hospedium no hay ningún proceso que envíe avisos.
3. En Conf. de cargos, revisa Usar API staging y elige el Cliente de Ágora para los albaranes.
4. Pulsa Guardar: sale Se ha guardado la integración de hoteles. Hospedium no tiene pestañas de familias ni de formas de pago.
5. En Enlaces, copia la URL botón acción personalizada.

[!WARNING] Al crear una integración de Hospedium, Usar API staging viene marcada. Con ella marcada los cargos van al entorno de pruebas de Hospedium (/api/external/staging/accounts) y no aparecerán en el PMS real. Desmárcala antes de ponerla en producción.

Los campos 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.

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}…
3. Marca Mostrar Urls en un diálogo de Ágora. Es imprescindible: la pantalla lee el ticket y crea el albarán a través de ese diálogo.
4. En Herramientas → Configuración de Botones, coloca la acción en un botón del perfil que usa el local (o en el menú Otros).
5. Da el permiso de la acción 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/hospedium/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}. Hospedium no necesita la integración de documentos de Ágora.

Cómo funciona#

Al pulsar la acción, el diálogo carga la pantalla de Connect Manager y esta pide al TPV el ticket abierto con su API local. El camarero escribe la habitación y Connect Manager trae de Hospedium las cuentas abiertas, filtradas por ese texto. En la tarjeta elegida puede poner una propina y pulsar Cargar: el TPV crea el albarán, Connect Manager lo guarda y envía el cargo a esa cuenta de Hospedium. Si todo va bien sale «Se generó el siguiente cargo:» seguido del número interno de Connect Manager (Hospedium no devuelve uno propio) y el diálogo se cierra a los dos segundos.

sequenceDiagram
    participant C as Camarero
    participant AG as TPV Ágora
    participant CM as Connect Manager
    participant HO as Hospedium
    C->>AG: Pulsa la acción Cargo habitación
    AG->>CM: Abre la pantalla de cargo en un diálogo
    CM->>AG: Pide el ticket abierto por la API local
    C->>CM: Escribe el nº de habitación
    CM->>HO: Pide las cuentas abiertas
    HO-->>CM: Cuentas con habitación y tarifa
    CM-->>C: Tarjetas que coinciden con el texto
    C->>CM: Propina opcional y Cargar
    CM->>AG: Crea el albarán por la API local
    AG-->>CM: Albarán con serie y número
    CM->>HO: Cargo en la cuenta por tipo de IVA
    HO-->>CM: Respuesta correcta
    CM-->>C: Se generó el siguiente cargo

Connect Manager se identifica ante Hospedium como agora-pos y firma cada petición con la Firma y el Id. del hotel (cabecera X-Signature). La consulta va a …/api/external/accounts y el cargo a …/api/external/accounts/{cuenta}/; con Usar API staging, a las mismas rutas con /staging detrás de /external. El cargo lleva un concepto por cada tipo de IVA del albarán (SERIE/000123, cantidad 1 y el importe con IVA de ese tipo) con sus líneas de producto, y la propina como concepto propio con IVA 0.

El albarán se crea antes de enviar el cargo. Si Hospedium no responde o lo rechaza, el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…»: comprueba en Ágora si el albarán está creado y, si lo está, devuélvelo o carga el importe a mano en Hospedium. No hay reintentos ni anulación automática. Si el TPV no contesta a la pantalla en 60 segundos, la petición se corta con «Request timed out».

Comprobar que funciona#

1. En los datos del local, la prueba de la URL de API da Conexión con éxito y en la integración el buscador de Cliente lista clientes de Ágora.
2. Usar API staging está en el valor que corresponde al entorno que te dio Hospedium.
3. Abre en Ágora un ticket de prueba con un producto de cada tipo de IVA que se use (comida y bebida, por ejemplo) y pulsa la acción.
4. Escribe una habitación con cuenta abierta: aparece su tarjeta con la tarifa.
5. Pon una propina de prueba (con coma decimal, por ejemplo 1,50) y pulsa Cargar. Debe salir «Se generó el siguiente cargo:» y cerrarse el diálogo.
6. En Ágora queda el albarán impreso a nombre del cliente genérico con «(Nº hab.: …)».
7. En Hospedium, la cuenta tiene un concepto por tipo de IVA y otro de propina.
8. En Connect Manager, Operaciones hoteleras → Cargos muestra la operación con Pedido externo (request) y Pedido externo (response).
9. Anula el albarán de prueba en Ágora y quita el cargo en Hospedium.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Hospedium con Ágora?#

FOS da de alta la integración de hoteles con el proveedor Hospedium; tú pones la URL Api, la firma y el Id. del hotel, desmarcas Usar API staging para producción, eliges el cliente y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo.

¿Por qué viene marcada «Usar API staging»?#

Es el valor por defecto al crear la integración, pensado para probar contra el entorno de pruebas de Hospedium. En producción hay que desmarcarla.

¿Se anula el cargo en Hospedium si anulo el albarán en Ágora?#

No. La integración no envía anulaciones: el cargo hay que quitarlo a mano en Hospedium.

¿Por qué el cargo llega en varios conceptos?#

Porque se envía un concepto por cada tipo de IVA del ticket, con sus productos dentro, y otro para la propina si la hay.

¿Hay que abrir el puerto de la API de Ágora?#

Para cargar no: lo hace el TPV desde el diálogo. Para que el panel busque el cliente al configurar, Connect Manager necesita llegar a la API, publicada o con Zero Connect.

Referencias#

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