Integración de Ofi Hotel con Ágora: cargos a habitación

La integración de Ofi Hotel con Ágora permite cargar a la habitación el total de un ticket desde el TPV: el camarero busca al huésped alojado por número de habitación y, al cargar, el ticket se cierra en Ágora como albarán y Connect Manager añade el cargo en Ofi Hotel con el código de cargo configurado. Si la reserva no admite cargos desde el TPV, la ventana lo avisa y no deja seguir.

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 en Ofi Hotel al huésped alojado en la habitación y enseña nombre, teléfono, régimen y tipo de tarjeta de fidelización.
• Avisa con «La reserva no admite cargos» cuando Ofi Hotel marca la reserva sin crédito en TPV.
• Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con la habitación en el nombre fiscal.
• Añade en Ofi Hotel un cargo por el total del ticket con IVA, con el código de cargo configurado y la descripción «Bar/Rest/Room Service – » seguida de la serie y número del albarán.

Qué no hace#

• No envía el detalle de productos, el IVA ni la propina: solo el total.
• No anula en Ofi Hotel el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS.
• No envía facturas ni el cierre del día, ni sincroniza reservas o disponibilidad.
• No busca por nombre ni por tarjeta: solo por número de habitación.
• No lee la respuesta de Ofi Hotel al cargo más allá del código HTTP.

Requisitos#

• Ágora con Herramientas → Acciones personalizadas. La ventana lee el ticket y crea el albarán por la API local del TPV.
• API de Ágora accesible desde Connect Manager solo para configurar (el selector de Cliente). Abre el puerto a las IP de Connect Manager o usa Zero Connect.
• Suscripción a la API de integración de reservas de Ofi Hotel: URL, id. de suscripción, clave (Api Key), código del hotel y código del cargo.
• Quién hace qué. FOS da de alta el local y la integración con los datos que facilita Ofi Hotel. El distribuidor elige el cliente y configura el botón en Ágora. El cliente valida con una prueba real.

Datos que necesitamos#

Configuración paso a paso#

1. En Ofi Hotel#

1. Pide a Ofi Hotel la suscripción a su API de integración de reservas: URL, id. de suscripción, clave y código del hotel.
2. Pide al hotel el código de cargo con el que quiere ver los consumos del restaurante, y que las reservas que se vayan a cargar admitan cargos desde el TPV.

2. En Connect Manager: el local (lo hace FOS)#

1. En Administración → Locales, abre el local y rellena Cliente, Nombre, URL de API, API key, Dirección, Ciudad y Zona horaria. Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): «Conexión con éxito».
2. Guardar → Integraciones de hoteles → Añadir → proveedor Ofi Hotel.

3. En Connect Manager: Conf. general#

1. 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».
2. URL Api: la de Ofi Hotel, acabada en /. Es obligatoria y la barra final importa: Connect Manager firma cada petición con la URL tal cual está escrita y, sin la barra, la firma no coincide.
3. Api Key: la clave de la suscripción, tal cual la entrega Ofi Hotel.
4. Id. del hotel: el código del hotel en Ofi Hotel.
5. Email de receptor de notificaciones: esta integración no envía avisos en segundo plano, pero puedes dejar el correo del cliente.

4. En Connect Manager: Conf. de cargos#

• Id. de la suscripción: el identificador de la suscripción. Se usa para firmar las peticiones y va también en su cabecera.
• Código del cargo: el código con el que Ofi Hotel registra el cargo.
• Cliente: el cliente genérico de Ágora para los albaranes. Al nombre fiscal se le añade la habitación, por ejemplo «Cargos a habitación (Nº hab.: 101)».

5. En Ágora#

1. Copia del bloque Enlaces la URL botón acción personalizada. Si empieza por /venues/, antepón https://app.connectmanager.es.
2. 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.
3. Coloca la acción en Herramientas → Configuración de botones y da su permiso a los perfiles que vayan a cargar.

Cómo funciona#

El botón abre la ventana con el ticket; la ventana lo lee por la API local de Ágora y lo guarda en Connect Manager. Al buscar la habitación, Connect Manager pide a Ofi Hotel el cliente alojado, firmando la petición con la clave de la suscripción. Si la reserva admite cargos, al pulsar Cargar la ventana crea el albarán en Ágora, lo guarda y pide el cargo; Connect Manager lo añade en Ofi Hotel y la ventana dice «Se generó el siguiente cargo» antes de cerrarse.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant PMS as Ofi Hotel
    TPV->>TPV: Lee el ticket por la API local
    TPV->>CM: Guarda el ticket
    TPV->>CM: Busca la habitación
    CM->>PMS: Cliente alojado en la habitación
    PMS-->>CM: Nombre, teléfono, régimen y si admite cargos
    CM-->>TPV: Datos de la reserva
    TPV->>TPV: Crea el albarán por la API local
    TPV->>CM: Guarda el albarán y pide el cargo
    CM->>PMS: Agrega cargo a la habitación
    PMS-->>CM: Respuesta
    CM-->>TPV: Se generó el siguiente cargo

Qué se envía: el código del hotel, el número de habitación, el código del cargo, cantidad 1, el total con IVA y la descripción «Bar/Rest/Room Service – A/000123». El número que enseña la ventana al terminar es el del ticket de Ágora.

Si Ofi Hotel no responde: el albarán ya está creado en Ágora, la ventana dice «No se ha podido generar el albarán…» y el cargo no se repite solo. Revisa el caso en Operaciones hoteleras → Cargos.

Comprobar que funciona#

1. En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen cliente, teléfono, régimen y fidelización.
2. Pulsa Cargar: sale «Se generó el siguiente cargo: …» y se imprime el albarán con la habitación.
3. En Ofi Hotel, la habitación tiene el cargo con el código y la descripción con el número del albarán.
4. En Operaciones hoteleras → Cargos aparece el cargo con lo enviado y la respuesta de Ofi Hotel.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Ofi Hotel con Ágora?#

Con Connect Manager: FOS crea la integración con los datos de la suscripción de Ofi Hotel, se elige el cliente y, en Ágora, se añade una acción personalizada con la URL de cargo.

¿Qué ve el hotel en la habitación?#

Un cargo por el total del ticket con el código configurado y la descripción con la serie y número del albarán.

¿Por qué sale «La reserva no admite cargos»?#

Porque Ofi Hotel indica que esa reserva no tiene crédito en TPV. Se cambia en Ofi Hotel.

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

No. La anulación hay que hacerla también en Ofi Hotel.

Referencias#

• Ficha de la integración con Ofi Hotel
• Hotel Hub: cómo funciona
• Integración de Sihot con Ágora: la misma configuración de acción personalizada en Ágora
• Direcciones IP de Connect Manager