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

La integración de Winhotel con Ágora permite cargar a la habitación el total de un ticket desde el TPV: el camarero busca la habitación, elige a qué titular con crédito se carga y Connect Manager manda el cargo a Winhotel mientras el ticket se cierra en Ágora como albarán. La ventana enseña además el límite de crédito, las fechas y las tarifas de la reserva.

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 por número de habitación los titulares con crédito en Winhotel y enseña el límite de crédito del que se elija.
• Enseña la entrada y la salida de la reserva vigente hoy y, con el botón de tarifas, sus tipos de tarifa.
• Deja elegir a qué titular se carga cuando hay varios.
• Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el titular y la habitación en el nombre fiscal.
• Carga en Winhotel el total del ticket con IVA, con el producto de Winhotel configurado y la serie y número del albarán como documento de origen.

Qué no hace#

• No envía el detalle de productos ni la propina: solo el total.
• No anula en Winhotel el cargo de un albarán anulado en Ágora: hay que anularlo a mano en el PMS.
• No envía facturas ni sincroniza reservas o disponibilidad.
• No impide cargar por encima del límite de crédito: lo enseña, pero no bloquea.
• No lee la respuesta de Winhotel más allá del código HTTP: si Winhotel contesta sin error técnico, el cargo se da por hecho.

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.
• Acceso a la API de consultas de Winhotel: usuario, contraseña y los dos códigos de hotel (source y target).
• Quién hace qué. FOS da de alta el local y la integración con los datos que facilita Winhotel. El distribuidor elige el producto y 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 Winhotel#

1. Pide a Winhotel el acceso a su API de consultas para Ágora: usuario, contraseña, Hotel source code, Hotel target code y, si no es la pública, la URL.
2. Confirma con el hotel qué producto de Winhotel recibirá los cargos del restaurante.

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 Winhotel.

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: déjala vacía para usar la API pública de Winhotel, o pon la que te indiquen.
3. Usuario y Password: los de Winhotel.
4. Hotel source code y Hotel target code: los dos códigos del mapa de hotel que te dé Winhotel. Van en todas las consultas y en los cargos.
5. Email de receptor de notificaciones: esta integración no envía avisos en segundo plano, pero puedes dejar el correo del cliente.
6. Pulsa Guardar: la integración se abre en modo edición y aparece el desplegable Producto, que antes de guardar no sale.

4. En Connect Manager: Conf. de cargos#

• Cliente: el cliente genérico de Ágora para los albaranes. Su nombre fiscal se sustituye por el del titular y la habitación, por ejemplo «Huésped Demo (Nº hab.: 101)».
• Producto: el producto de Winhotel al que van los cargos. Es obligatorio: sin él no se puede cargar.

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 Winhotel los titulares con crédito y la reserva vigente hoy. Al pulsar Cargar, la ventana crea el albarán en Ágora, lo guarda y pide el cargo; Connect Manager lo inserta en Winhotel como cargo externo 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 Winhotel
    TPV->>TPV: Lee el ticket por la API local
    TPV->>CM: Guarda el ticket
    TPV->>CM: Busca la habitación
    CM->>PMS: Titulares con crédito de la habitación
    CM->>PMS: Reserva vigente hoy
    PMS-->>CM: Titulares, límites, fechas y tarifas
    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: Cargo externo con el total
    PMS-->>CM: Respuesta
    CM-->>TPV: Se generó el siguiente cargo

Qué se envía: el titular elegido (identificador y nombre), el número de habitación, la serie y número del albarán, la fecha del albarán, el total con IVA y el código del producto. Todas las llamadas llevan el usuario, la contraseña y los dos códigos de hotel. El número que enseña la ventana al terminar es siempre el mismo (10000): no es un identificador de Winhotel.

Si Winhotel 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. Tras guardar, el desplegable Producto muestra los productos de Winhotel: credenciales y códigos correctos.
2. En Ágora, abre un ticket, pulsa el botón y busca una habitación ocupada: salen los titulares en el desplegable Cliente, el crédito, el checkin y el checkout.
3. Pulsa Cargar: sale «Se generó el siguiente cargo: 10000» y se imprime el albarán con el titular y la habitación.
4. En Winhotel, el titular tiene el cargo con el total y el número del albarán.
5. En Operaciones hoteleras → Cargos, «Pedido externo (response)» guarda lo que contestó Winhotel: revísalo en la primera prueba.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Winhotel con Ágora?#

Con Connect Manager: FOS crea la integración con el acceso a la API de Winhotel, se elige el producto y el cliente y, en Ágora, se añade una acción personalizada con la URL de cargo.

¿Qué titular recibe el cargo si la habitación tiene varios?#

El que elija el camarero en el desplegable Cliente; por defecto, el primero que devuelve Winhotel.

¿Se manda el detalle de lo consumido?#

No. Winhotel recibe el total con IVA y el número del albarán; el detalle queda en el albarán de Ágora.

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

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

¿Bloquea el cargo si se supera el crédito?#

No: la ventana enseña el límite de crédito del titular, pero deja cargar.

Referencias#

• Ficha de la integración con Winhotel
• 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