Integración de Ulyses con Ágora: cargos a habitación y facturas

La integración de Ulyses con Ágora permite cargar a la habitación los consumos del restaurante o la cafetería sin salir del TPV: el camarero busca la habitación, Connect Manager consulta los folios en Ulyses (el PMS de Tesipro) y el ticket se cierra en Ágora como albarán y se apunta en el folio del huésped. Además envía a Ulyses las facturas que emite Ágora y anula el cargo cuando se anula el albarán.

Este manual es para el técnico de FOS o del distribuidor que deja la integración funcionando en un local. Cómo encajan en general 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 folios de Ulyses y enseña huésped, entrada, salida, régimen y crédito. Si hay varios folios, deja elegir y preselecciona el que está en fechas.
• Puede ocultar los folios fuera de fechas y bloquear el cargo si el folio no tiene crédito suficiente.
• Cierra el ticket en Ágora como albarán a nombre del cliente configurado, con el nombre del folio y la habitación en el nombre fiscal, y lo imprime.
• Apunta el cargo en el folio con el detalle de líneas, los comensales y la serie y número del albarán; si se pide, reparte el importe entre comida, bebida y otros.
• Elige el servicio de Ulyses por centro de venta, por franja horaria o por familia, y manda un apunte por servicio si el ticket los mezcla.
• Al anular en Ágora el albarán de un cargo, manda a Ulyses un apunte de anulación con las mismas líneas y las unidades en negativo.
• Envía a Ulyses las facturas que emite Ágora a un folio de facturación (las rectificativas, a uno de devolución), con un cobro por forma de pago, en el momento o cinco minutos después.
• Guarda cada cargo y cada factura con lo enviado y lo respondido, y avisa por correo de los fallos de los envíos en segundo plano.

Qué no hace#

• No busca por nombre del huésped, tarjeta ni localizador: solo por número de habitación o, con una variante, por código de folio.
• No envía propinas ni el desglose de IVA, ni sincroniza reservas, disponibilidad o tarifas.
• No deja cargar tickets con descuento en importe, ni con descuento por línea y a pie de ticket a la vez.
• No reintenta sola un envío en segundo plano que falla: avisa por correo y el reenvío lo hace FOS.
• No cierra por sí sola los albaranes abiertos. «Nº de días para cerrar albaranes» depende de una tarea nocturna del motor que en la versión actual no está activada: confírmalo con FOS antes de contar con ella.

Requisitos#

• Ágora con Herramientas → Acciones personalizadas y, para anulaciones y facturas, el módulo Servicios de integración.
• Conectividad con Ágora. La ventana lee el ticket y crea el albarán a través de la API local del TPV, así que para cobrar no hace falta abrir Ágora a Internet. Para configurar, sí: los selectores del panel (Cliente, Familia, Centro de venta, Método de pago) leen Ágora desde Connect Manager con la URL de API y la API key del local, que tienen que ser accesibles desde fuera (puerto abierto a las IP de Connect Manager o publicado con Zero Connect).
• Acceso a la API de Ulyses: URL, usuario, contraseña, id. de cadena e id. de hotel.
• Quién hace qué. El cliente pide a Ulyses el acceso de integración y Ulyses manda los datos a FOS. FOS da de alta el local y la integración y rellena esos datos. El distribuidor revisa la configuración de cargos, hace las asociaciones, configura Ágora y prueba con el cliente.

Datos que necesitamos#

Configuración paso a paso#

1. En Ulyses#

1. El cliente solicita a Ulyses el acceso de integración con Connect Manager; Ulyses envía a FOS la URL, el usuario, la contraseña y los ids. de cadena y hotel.
2. Comprueba con el hotel que existen en Ulyses los servicios, los folios de punto de venta y las formas de pago que se van a usar: el panel los carga de Ulyses, no se escriben a mano.

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

1. En Administración → Locales, abre el local y rellena Cliente, Nombre, URL de API y API key de Ágora, Dirección, Ciudad y Zona horaria. Con la zona horaria se comprueban las fechas de la reserva y se fecha el albarán.
2. Pulsa el icono de prueba del campo URL de API (sale con la URL y la API key rellenas): debe salir «Conexión con éxito».
3. Guardar → Integraciones de hoteles → Añadir → proveedor Ulyses.

3. En Connect Manager: Conf. general#

1. Proveedor: Ulyses. No se puede cambiar después de guardar.
2. 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 (o desde el día siguiente a esa fecha), el botón del TPV abre el aviso «Integración pausada» en vez de la ventana de cargo.
3. URL Api, Usuario, Password, Id. de la cadena e Id. del hotel: los de Ulyses. La URL es obligatoria: no hay ninguna por defecto.
4. Email de receptor de notificaciones: escribe cada dirección y pulsa Intro.
5. Pulsa Guardar: la integración se abre en modo edición y aparecen los desplegables de Ulyses y las pestañas de asociaciones, que antes de guardar no salen.

4. En Connect Manager: Conf. de cargos#

• Comprobar fechas de reserva: al buscar solo salen los folios cuya estancia incluye hoy (de la llegada a la salida, con la zona horaria del local). Desmarcado salen todos los que devuelva Ulyses, también reservas pasadas o futuras. Recomendado: marcado.
• Dejar abierto el albarán: el albarán se crea en Ágora permitiendo facturarlo después. Es lo que permite anular el cargo más tarde desde Ágora y que la anulación llegue a Ulyses. Recomendado: marcado.
• Nº de días para cerrar albaranes (7 por defecto): la tarea nocturna que lo usa anula en Ágora los albaranes de cargo que siguen abiertos pasados esos días, sin tocar Ulyses, y solo si «Dejar abierto el albarán» está marcado. Hoy esa tarea no está activa.
• Cliente: el cliente genérico de Ágora al que se emiten los albaranes. Su nombre fiscal se sustituye por el del folio y la habitación, por ejemplo «Huésped Demo (Nº hab.: 101)».
• Servicio: el servicio de Ulyses por defecto para los cargos.
• Folio de facturación y Folio de devolución: donde se apuntan las facturas y las rectificativas que llegan de Ágora. No intervienen en los cargos a habitación.
• Enviar facturas en diferido: Ágora recibe la factura como aceptada al momento y el envío a Ulyses sale cinco minutos después, en segundo plano. Así una caída de Ulyses no bloquea el cobro en el TPV. Recomendado: marcado.
• Contabilizar por separado: añade a cada apunte los importes de comida, bebida y otros. Cada línea va a lo que diga su familia en la pestaña Familias o, si no está asociada, a Contabilizar por defecto como (Comida, Bebida u Otras), que aparece al marcarla.
• Comprobar si hay crédito disponible: el botón Cargar se bloquea si el folio no tiene crédito, si es menor que el total del ticket o si Ulyses no devuelve un importe de crédito.

5. En Connect Manager: asociaciones#

• Centros de venta (opcional): por cada Centro de venta de Ágora, su Servicio; un Servicio alternativo con su Hora de inicio del servicio alternativo y su Hora de finalización del servicio alternativo (dentro de esa franja se usa el alternativo); y un Folio de facturación y Folio de devolución propios para sus facturas.
• Familias (opcional): por cada Familia, Contabilizar por Comida, Bebida u Otras; para repartir, un porcentaje y un Contabilizar por (2ª) con el suyo, que deben sumar 100. Con un Servicio propio, sus líneas van en un apunte aparte.
• Métodos de pago: cada Método de pago de Agora con su Método de pago Ulyses. Si se envían facturas, asócialos todos: una factura con una forma de pago sin asociar se rechaza.

6. En Ágora#

1. Copia del bloque Enlaces la URL botón acción personalizada con su botón de copiar. Si empieza por /venues/, antepón la dirección del panel (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 que Ágora rellena solo ({user_id}, {pos_id}, {ticket_global_id}…), y marca Mostrar Urls en un diálogo de Ágora.
3. Coloca la acción en Herramientas → Configuración de botones y da el permiso que genera a los perfiles que vayan a cargar.
4. Para anulaciones y facturas, en Herramientas → Activar módulos adicionales → Servicios de integración pega la URL para enviar facturas desde Ágora y activa Habilitar integración de documentos y Enviar albaranes.

[!WARNING] Con la integración de documentos activa, todas las facturas que emite Ágora se envían a Ulyses. Asocia antes las formas de pago y elige los folios, o Ágora no dejará cerrar esas ventas.

[!TIP] Para cargar a folios que no son de habitación (grupos, eventos), crea una segunda acción con la misma URL y &search-by-folio=1 al final: la ventana busca por «Cód. de folio», con la casilla «Búsqueda exacta». Su campo «Propina» no se envía a Ulyses.

Cómo funciona#

Al pulsar el botón, Ágora abre la ventana con el usuario, el TPV y el identificador del ticket. La ventana pide el ticket a la API local de Ágora y lo guarda en Connect Manager. El camarero escribe la habitación y Connect Manager trae sus folios de Ulyses. Al pulsar Cargar, la ventana crea primero el albarán en Ágora, lo guarda y pide el cargo; Connect Manager apunta el ticket en el folio elegido y responde «Se generó el siguiente cargo» con el número de Ulyses. La ventana se cierra a los dos segundos.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant PMS as Ulyses
    TPV->>CM: Abre la ventana con el ticket
    TPV->>TPV: Lee el ticket por la API local
    TPV->>CM: Guarda el ticket
    TPV->>CM: Busca la habitación
    CM->>PMS: Pide los folios de la habitación
    PMS-->>CM: Huésped, fechas, régimen y crédito
    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: Apunte en el folio
    PMS-->>CM: Número del apunte
    CM-->>TPV: Se generó el siguiente cargo

Qué se envía: el servicio, la serie y el número del albarán, los comensales, el total con IVA y, por línea, el nombre del formato, las unidades y el precio unitario ya descontado (las unidades no enteras van como una unidad con el importe total). Con «Contabilizar por separado» se añaden comida, bebida y otros. Si hay varios servicios, el primer apunte sale en el momento y el resto un segundo después, en segundo plano; si alguno falla llega un correo «Error en aplicación» con «Enviar cargo adicional de Ulyses (Error)».

Si Ulyses no responde: la búsqueda da error en la ventana. Si falla el cargo, 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.

Anulaciones#

Al anular en Ágora un albarán de cargo, Ágora lo comunica a la URL de facturas. Connect Manager lo reconoce por su serie y número, rehace el apunte con las mismas líneas y las unidades en negativo y lo manda al mismo folio. Si Ulyses no contesta, Ágora recibe un rechazo y la anulación no se completa.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant PMS as Ulyses
    TPV->>CM: Albarán anulado por la URL de facturas
    CM->>PMS: Apunte con las unidades en negativo
    PMS-->>CM: Respuesta
    CM-->>TPV: Aceptado o rechazado

Facturas#

Cada factura que emite Ágora llega a la misma URL. Connect Manager comprueba que sus formas de pago estén asociadas y que haya folio, y la apunta en el folio de facturación (el de devolución si es rectificativa; el del centro de venta si lo tiene) con las líneas agrupadas por servicio. Después manda un cobro por forma de pago, con importe, fecha de cobro y día de negocio. En diferido, Ágora recibe la aceptación al instante y el envío sale a los cinco minutos; si falla, llega el correo «Enviar factura diferida de Ulyses (Error)». En Operaciones hoteleras → Facturas salen como «Aceptado» cuando Ulyses las ha recibido, y sin estado mientras esperan el envío diferido.

Comprobar que funciona#

1. En la integración guardada, los desplegables Servicio y Folio muestran datos de Ulyses.
2. En Ágora, abre un ticket con un par de productos y pulsa el botón. Busca una habitación con huésped en casa: deben salir folio, cliente, entrada, salida, régimen y crédito.
3. Pulsa Cargar: sale «Se generó el siguiente cargo: …», la ventana se cierra y se imprime el albarán con el nombre y la habitación.
4. En Ulyses, el folio tiene el apunte con las líneas y la serie y número del albarán; en Operaciones hoteleras → Cargos aparece el cargo con su Id. de pedido externo.
5. Anula el albarán de prueba en Ágora y comprueba en Ulyses el apunte de anulación.
6. Emite una factura de una venta normal y comprueba el apunte y el cobro en el folio de facturación (a los cinco minutos si está en diferido).

Errores frecuentes y solución#

[!WARNING] Si el cargo falló después de crear el albarán, no anules ese albarán sin revisar antes el folio: la anulación se manda a Ulyses aunque el cargo original no llegara.

Preguntas frecuentes#

¿Cómo conecto Ulyses con Ágora?#

Con Connect Manager: FOS da de alta la integración con los datos de Ulyses, se hacen las asociaciones y en Ágora se crea una acción personalizada con la URL de cargo y, para anulaciones y facturas, la URL de facturas en Servicios de integración.

¿Qué tiene que ver Tesipro con Ulyses?#

Ulyses es el PMS de Tesipro. En el panel sale como «Ulyses»; en las URL de la integración aparece como tesipro.

¿Si anulo el albarán en Ágora se anula el cargo en Ulyses?#

Sí, si la URL de facturas está configurada con «Enviar albaranes»: Connect Manager manda al folio un apunte de anulación con las mismas líneas y las unidades en negativo.

¿Se pueden enviar a Ulyses las ventas de clientes no alojados?#

Sí, como facturas: van al folio de facturación con un cobro por forma de pago.

¿Qué pasa si Ulyses está caído?#

No se puede buscar ni cargar. Las facturas en diferido se aceptan en Ágora y se intentan enviar a los cinco minutos; si fallan, llega un aviso por correo.

Referencias#

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