Integración de UbikOS con Ágora: cargos a habitación y cierre

La integración de UbikOS (Ubikos) con Ágora carga en la reserva del huésped lo que consume en el restaurante o el bar del hotel, línea a línea y con el servicio de UbikOS que corresponda a cada familia, y permite enviar a UbikOS el cierre del día con las facturas del TPV y sus formas de pago. El camarero busca la habitación desde el TPV y pulsa Cargar; Connect Manager hace el resto y guarda el registro.

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.
• Búsqueda normal, por número de habitación exacto: enseña los Datos de la reserva (Nº de hab., Cliente, Checkin, Checkout, Regimen y Lím. Créd.) y avisa «La reserva no admite cargos» si UbikOS no los permite.
• Con Mostrar todas las habitaciones: lista al abrirse todas las habitaciones con reserva y deja buscar por habitación o por nombre del cliente. Cada tarjeta muestra habitación, cliente, tarifa, fechas y crédito, y Cargar sale desactivado si la reserva no admite cargos o su crédito es menor que el total del ticket.
• Avisa al abrir si el ticket lleva descuentos que UbikOS no admite: por importe, o por línea y a pie de ticket a la vez.
• Crea el albarán en Ágora desde el propio TPV, con el nombre del huésped y la habitación (Nombre Apellido (Nº hab.: 101)) sobre el cliente configurado, y lo imprime.
• Envía el cargo a la reserva línea a línea: cantidad, precio unitario, IVA, porcentaje de descuento (el de la línea o el general del ticket), descripción y el servicio de UbikOS de la familia (o el servicio por defecto), con el número de albarán, el identificador del ticket y el centro de venta de Ágora.
• Puede omitir los platos de menú sin precio y, con un informe personalizado instalado en Ágora, añadir al cargo el cliente del ticket y su código.
• Envía el cierre del día: las facturas de Ágora de la jornada, con líneas, cliente y formas de pago, a una cuenta diversa de UbikOS. Se lanza desde la pantalla de Inicio del panel.
• Guarda en Connect Manager cada cargo (ticket, albarán, envío y respuesta de UbikOS) y cada cierre.

Qué no hace#

• No pide la firma del huésped ni envía propinas.
• Anulaciones: el motor tiene preparada la orden que borra en UbikOS el cargo de un albarán anulado, pero se dispara desde la integración de documentos de Ágora y el panel no da esa URL para UbikOS. Tal como se configura desde el panel, anular el albarán no toca UbikOS; si el hotel lo necesita, consúltalo con FOS.
• El envío automático del cierre a la Hora de generación fich. contable y la cancelación automática de albaranes abiertos tras Nº de días para cerrar albaranes dependen de tareas programadas del motor que hoy no están activas. El cierre se lanza a mano desde el panel.
• En la búsqueda normal la habitación debe escribirse exactamente como en UbikOS.
• No sincroniza reservas, disponibilidad ni tarifas.

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, un cliente genérico para los albaranes y, si se usa Buscar datos de reservas, acceso al servidor para instalar un informe personalizado.
• Conectividad: el cargo lo hace el TPV a través del diálogo, con su API local. Connect Manager sí necesita llegar a la API de Ágora (puerto 8984, publicada o con Zero Connect) para las listas del panel (clientes, familias y formas de pago) y para el cierre, que lee las facturas de Ágora desde fuera.
• UbikOS: la Api Key, el identificador del hotel y los identificadores de servicios, formas de pago y cuenta diversa.

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 UbikOS facilita la Api Key y los identificadores.

Datos que necesitamos#

Configuración paso a paso#

En UbikOS#

1. Pide a UbikOS (o al hotel) la Api Key y el identificador del hotel.
2. Pide los identificadores de servicio de los cargos: uno por defecto y, si se quiere separar, uno por grupo de familias.
3. Si se va a enviar el cierre, el identificador de la cuenta diversa y los de las formas de pago.

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 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 UbikOS o, si eres administrador, pulsa Añadir y elige el Proveedor UbikOS.
2. En Conf. general rellena URL Api: (vacía para la de UbikOS), Api Key:, Id. del hotel y, si quieres avisos, Email de receptor de notificaciones, donde llegan los errores del cierre.
3. En Conf. de cargos ajusta las opciones de la tabla, elige el Cliente y pon el Id. del servicio por defecto.
4. Para el cierre: en Conf. de Z-cierre marca Z-cierre y rellena Cuenta diversa, Método de pago por defecto y Hora de generación fich. contable.
5. Pulsa Guardar: sale Se ha guardado la integración de hoteles y se activan las pestañas Familias y Métodos de pago.
6. En Familias, pulsa Añadir por cada familia con servicio propio: Familia (de Ágora) e Id. del servicio (de UbikOS).
7. En Métodos de pago (solo para el cierre), por cada forma de pago de Ágora: Método de pago de Agora y External id., la de UbikOS. Las que no asocies van con el Método de pago por defecto.
8. 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.

En Ágora#

1. Si no existe, crea el cliente genérico para los albaranes 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: la pantalla lee el ticket, ejecuta el informe 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 del local (o en el menú Otros) y da su permiso a los perfiles que vayan a cargar.
5. Solo con Buscar datos de reservas: descarga el informe desde Informes personalizados (Informe de reserva de cliente), cópialo en [Carpeta de instalación de Ágora]\custom-queries del servidor (o del ACMS central) y da el permiso de esa consulta al perfil del usuario cuyo token usa el local.

[!WARNING] Copia el informe tal cual se descarga. Un XML de consulta mal formado en custom-queries (por ejemplo, sin el nodo Columns) impide que arranque el servicio de Ágora del cliente hasta que se retira.

La URL de la acción tiene esta forma, precedida del dominio que muestre el panel: /venues/123/hotels/ubikos/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}.

Cómo funciona#

Al pulsar la acción, el diálogo carga la pantalla de Connect Manager, que pide al TPV el ticket abierto (y, si está activado, ejecuta el informe de reserva). Si el ticket lleva descuentos que UbikOS no admite, avisa y no guarda el ticket: hay que cerrar el diálogo y corregirlo, porque el botón no se bloquea y, si se carga igualmente, se crea el albarán pero el cargo no sale. El camarero busca la habitación y Connect Manager pide a UbikOS las habitaciones con reserva. Al pulsar Cargar, el TPV crea el albarán, Connect Manager lo guarda y envía el cargo a la reserva. Si UbikOS lo acepta, sale «Se generó el siguiente cargo:» con el número de ticket de UbikOS 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 UB as UbikOS
    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 por la API local y revisa descuentos
    C->>CM: Escribe el nº de habitación
    CM->>UB: Pide las habitaciones con reserva
    UB-->>CM: Reserva, régimen y crédito
    C->>CM: Pulsa Cargar
    CM->>AG: Crea el albarán por la API local
    AG-->>CM: Albarán con serie y número
    CM->>UB: Cargo a la reserva línea a línea
    UB-->>CM: Número de ticket de UbikOS
    CM-->>C: Se generó el siguiente cargo

La consulta va a …/pos/revo/{Id. del hotel}/bookingrooms y el cargo a …/pos/revo/{Id. del hotel}/bookingcharge/{reserva}, con la Api Key. El albarán se crea antes del cargo: si UbikOS lo rechaza, el albarán ya existe en Ágora y la pantalla dice «No se ha podido generar el albarán…». La respuesta de UbikOS queda guardada en Cargos también cuando falla.

El cierre del día#

Se lanza desde Inicio, en el recuadro Generar cierre Z del hotel (Ubikos): eliges Local y Fecha y pulsas Click para generar. Connect Manager pide a Ágora las facturas de ese día de negocio y envía cada una a la cuenta diversa de UbikOS (…/invoicecharge/{cuenta diversa}) con su número, día de negocio, centro de venta, cliente, líneas con los servicios de las familias y formas de pago. El resultado queda en Operaciones hoteleras → Cierres de caja: Enviado, Error (si UbikOS rechaza alguna factura) o No hay datos.

flowchart TD
    A[Inicio: Generar cierre Z del hotel] --> B{Cierre de ese día ya enviado}
    B -->|sí| X[No se vuelve a enviar]
    B -->|no| C[Lee de Ágora las facturas del día]
    C --> D[Envía cada factura a la cuenta diversa de UbikOS]
    D --> E{Alguna factura con error}
    E -->|no| F[Estado Enviado]
    E -->|sí| G[Estado Error]

Un cierre ya enviado no se repite, ni desde Inicio ni con Exportar en Cierres de caja, que sirve para relanzar los que quedaron en error o sin datos. El aviso de Inicio es siempre el mismo («La petición para generar el cierre se ha enviado…»), así que el resultado se mira en Cierres de caja. Si falla la lectura de Ágora, se avisa por correo.

[!NOTE] Las facturas del día se piden sin filtrar por local: si la URL de API del local es la de un ACMS central con varios locales, el cierre incluye las de todos.

Comprobar que funciona#

1. La prueba de la URL de API del local da Conexión con éxito y los buscadores de Cliente y de familias listan datos de Ágora.
2. Abre en Ágora un ticket de prueba sin descuentos y pulsa la acción: se abre el diálogo de búsqueda.
3. Busca una habitación ocupada: salen los datos de la reserva (o su tarjeta, con Mostrar todas las habitaciones).
4. Pulsa Cargar: debe salir «Se generó el siguiente cargo:» con un número y cerrarse el diálogo.
5. En Ágora queda el albarán impreso con «huésped (Nº hab.: …)» y en UbikOS la reserva tiene una línea por producto con el servicio esperado.
6. En Operaciones hoteleras → Cargos aparece la operación con lo enviado y la respuesta.
7. Si usas el cierre, genera desde Inicio el de un día con ventas y comprueba en Cierres de caja que queda Enviado y en UbikOS que las facturas están en la cuenta diversa.
8. Anula el albarán de prueba en Ágora y quita el cargo a mano en UbikOS.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto UbikOS con Ágora?#

FOS da de alta la integración de hoteles con el proveedor UbikOS; tú pones Api Key, Id. del hotel, cliente y servicio por defecto, asocias familias y formas de pago y creas en Ágora una acción personalizada con la URL del panel, mostrada en un diálogo.

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

Sí, con Mostrar todas las habitaciones: la pantalla lista las habitaciones con reserva y deja buscar por habitación o por nombre del cliente.

¿Cómo envío a UbikOS las ventas del día?#

Activa el Z-cierre con la cuenta diversa y las formas de pago, y lánzalo desde Inicio con Generar cierre Z del hotel (Ubikos). El resultado se ve en Cierres de caja.

¿Se anula el cargo en UbikOS si anulo el albarán?#

Con la configuración que da el panel, no: el cargo hay que quitarlo en UbikOS. El motor tiene la anulación preparada, pero necesita una URL de documentos de Ágora que el panel no muestra para UbikOS.

¿Por qué sale un aviso al cargar un ticket con descuento?#

Porque UbikOS solo recibe descuentos en porcentaje y en un único nivel, por línea o a pie de ticket, nunca por importe. Si sale el aviso, no pulses Cargar: cierra el diálogo, corrige el descuento y vuelve a abrir la acción.

Referencias#

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