Índice

La plataforma de integración hotelera de Oracle (Hospitality Integration Platform), en adelante OHIP, ofrece un conjunto sólido de API's de hostelería y gestión de cualquier unidad hotelera alojada en los servidores de Oracle, a las que pueden suscribirse las aplicaciones/soluciones creadas por cualquier partner de Oracle debidamente dado de alta como tal y que haya solicitado el acceso a las API's de OHIP. Este conjunto de endpoints ofrece a los terceros softwares la posibilidad de comunicar la práctica totalidad de las operaciones de gestión hotelera realizadas a través de este a la propiedad del cliente/hotelero, de manera directa y sin necesidad de softwares interpuestos.

A diferencia de otros esquemas, como el esquema Opera On Premise, el contenido de las comunicaciones con OHIP se envía y recibe en formato JSON y no en formato SOAP XML, lo cual facilita enormemente el procesado de los cuerpos de las peticiones y respuestas dadas las circunstancias de nuestro entorno de desarrollo.

De este modo, los clientes de Golfmanager que dispongan de una cuenta de gestión hotelera con Oracle, tendrán la posibilidad de instalar este módulo de integración y centralizar los aspectos más básicos del día a día de la gestión de la propiedad hotelera, tales como los cargos a habitación, devoluciones, envío manual y automático configurable de cobros, etc.

Hoy en día, de la redacción de este manual, las funcionalidades de gestión hotelera implementadas en el plugin de Oracle son las siguientes:

Volver arriba

Por razones de economía y facilidad en el desarrollo, el flujo básico del esquema de peticiones y respuestas empleado en el plugin se basa exclusivamente en el uso de dos operaciones del conjunto de módulos API que OHIP ofrece, más concretamente los módulos CSH (cashiering) y RSV (reservations).

El primero de ellos, el módulo CSH, ofrece las API's necesarias para notificar al sistema gestor de la propiedad los movimientos y operaciones de flujo de caja que se vayan realizando.

El segundo, el módulo RSV, facilita las API's adecuadas para la gestión de las reservas tales como su obtención, ya sea en masa, ya sea filtrando por cualquier criterio de búsqueda, así como aquéllas para notificar nuevas reservas, modificarlas, etc...

En nuestro caso, todo el sistema pivota exclusivamente en torno a la operación getHotelReservations del módulo RSV y la operación postBillingCharge del módulo CSH.

Esto es así porque el patrón de estilo empleado para comunicar los flujos de caja de las formas de pago alternativas al cargo habitación consiste, valga la redundancia, en realizar cargos a una pseudoreserva de una habitación ficticia, en las que las operaciones de check-in y check-out hacen las veces de apertura y cierre diarios de caja. Dichas habitaciones se identifican como pay master rooms por las siglas PM dentro de la terminología propia de Oracle OHIP.

En materia de autenticación, la API empleada no forma parte del conjunto de API's de Oracle OHIP sino del de oAuth. El sistema de autenticación empleado por Oracle puede resultar contraintuitivo e incluso arbitrario en algunos puntos. A continuación, simplemente se describe qué es lo que debe incluir está petición según la documentación de la propia Oracle.

El método empleado es basic auth, es decir, codificar usuario y contraseña en el encabezado Authorization de la petición. Dichos usuario y contraseña se corresponden con nuestro clientId y clientSecret, que podemos obtener a través de nuestro portal de desarrollador de Oracle. Además, deberemos incluir en los encabezados de la petición la propiedad x-app-key que identifica a qué aplicación del Partner de Oracle, en este caso nosotros, queremos acceder.

Además, en el cuerpo de la petición de autorización, han de incluirse las credenciales del usuario de integración que se debió solicitar y crear previamente en la tabla de usuarios de la propiedad y que realmente son los que apuntan a la propiedad hotelera del cliente final.

En una sola petición de token de acceso, estamos enviando básicamente dos cosas:

De este modo, los sistemas de Oracle tienen todo lo necesario para hacer funcionar el conjunto de API’s de OHIP contra la propiedad del Club. Si todo está ok, obtendremos un token, que deberemos acompañar al resto de llamadas, esta vez ya, al conjunto de API’s de Oracle OHIP. Estas llamadas utilizan el método bearer-token para autenticarse, a diferencia de la propia solicitud de token, que emplea el método basic auth.

El token de acceso se solicita siempre previamente a cualquier otra llamada que el plugin realice. Esto no es técnicamente necesario, ya que tiene una validez para una hora. Además de tener que escribir más código para refrescarlo cada cierto tiempo, obtenerlo previamente supone una primera barrera contra posibles caídas del servicio o errores de credenciales, de manera que no tengan que manejarse estas posibilidades para cada una del resto de las llamadas a las API’s de OHIP. Si la petición del token de acceso falla por cualquier razón, simplemente no se intentará la operación y se lanzará el correspondiente mensaje de error.

Volver arriba

El flujo de llamadas que se realiza cuando se hacen cargos a habitación consiste en la petición previa de reservas, empleando la operación API getHotelReservations con un filtro que se detalla en el epígrafe 4 de este manual, para mostrarlas en un selector al usuario Admin del TPV.

Obtenidas estas habitaciones y escogida una válida, cuando se pulsa Aceptar, antes de realizar petición OHIP alguna, se intenta realizar el pago internamente en nuestro sistema. Si este pago falla, el proceso de notificación a OHIP simplemente no continúa. Si el pago se ha podido realizar internamente en nuestro software, entonces realizamos una petición para ejecutar la operación postBillingCharge del módulo CSH de las API’s de OHIP. Si por cualquier razón ajena a nuestro software, la respuesta obtenida de Oracle es de rechazo expreso o de error, entonces nuestro software deshará la venta consolidada internamente. En la tabla de transacciones de Oracle quedarán reflejados los resultados de estas operaciones, así como las peticiones y respuestas obtenidas, y las ventas y/o cobros implicados.

En cuanto al resto de formas de pago, el plugin contiene una suscripción al evento de onTicketCreated. De este modo, cada vez que se crea un ticket la función que maneja la suscripción al evento comprueba si proviene de una forma de pago que tenga configurada una payMasterReservationId, es decir, la ID de una pseudoreserva de una habitación maestra de pago. Si es el caso, esta función pasará el ticket recién creado a la función del plugin que realiza el cargo habitación, para que este se tramite contra la habitación maestra de la reserva configurada en la forma de pago.

De estas operaciones, al igual que con el Cargo Habitación, queda constancia en la tabla de transacciones. No obstante, hay una diferencia sutil pero fundamental que conviene destacar. Cuando realizamos un cargo a una habitación específica y real, y Oracle nos contesta con un rechazo por respuesta, obviamente desharemos el pago en Golfmanager. No obstante, cuando comunicamos el flujo de caja de otras formas de pago, que Oracle nos conteste con un rechazo no debe importarnos en absoluto a nivel interno. Simplemente se dejará constancia del rechazo de Oracle OHIP en la tabla de transacciones.

No obstante, para estas formas de pago alternativas, y para casos de caídas del servicio inesperadas o programadas, si la comunicación no pudo realizarse por falta simple de conectividad o por estar el servicio deshabilitado desde la configuración del plugin, de tal modo que no se haya podido obtener respuesta positiva o negativa por parte del servicio en la nube, podrá intentarse su reenvío desde el botón de reenviar agregado a la vista de cobros.

Este botón intentará reenviar la información de las transacciones marcadas como fallidas y que contengan la información de un ticket, de nuevo al servidor de Oracle. De este modo, como las transacciones fallidas de cargo a habitación real no guardan ticket, no se reenviarán lo cual, además, no tendría sentido alguno, pues el pago no llegó a consolidarse en GM, ya que en el caso de cargo a habitación real la confirmación del pago en GM está condicionada a la aceptación por parte del sistema de Oracle OHIP, mientras que en las transacciones fallidas que guardan un ticket esto es representativo de que sí se llegó a consolidar un pago en Golfmanager y, por tanto, tiene sentido reintentar su comunicación a Oracle si esta falló por falta de respuesta expresa de Oracle (errores HTTP).

Debido a que si el servicio está caído no se quieren andar recibiendo mensajes de error constantemente, desde la configuración del plugin se puede deshabilitar el servicio. Los cargos a habitación obviamente no podrán realizarse. No obstante, el resto de las formas de pago seguirá generando en la tabla de transacciones de Oracle un intento fallido de comunicación, con un código de error que indica que no se pudieron enviar porque el servicio estaba deshabilitado, de tal modo que puedan reenviarse en tanto en cuanto el servicio se restablezca mediante el botón mencionado.

Si se usa el botón de reenviar transacciones estando el servicio deshabilitado, se "reiniciará" el estado de error de las transacciones fallidas que contengan un ticket. Es decir, que aquellas transacciones fallidas que contengan un ticket y que hayan fallado por haber recibido una respuesta expresa de rechazo de las APIs de Oracle OHIP, actualizarán su estado de error al estado de "no enviado por servicio deshabilitado". Esto puede tener utilidad, pero solamente en un número muy reducido de casos. No debe usarse a la ligera. El sistema nos advertirá adecuadamente de esto cuanto intentemos hacer un reenvío de transacciones fallidas estando el servicio deshabilitado desde la configuración del plugin.

Volver arriba

Para poder autorizar la integración entre la empresa y el sistema a través de una API, previamente tendrás que enviar el documento cumplimentado y firmado por ambas partes a Golfmanager. Para más información, dirígete al siguiente link.

Volver arriba

Del lado de GM, en la vista de configuración del plugin únicamente deberemos introducir la moneda en la que queremos realizar las transacciones, la dirección URL de la puerta de enlace de Oracle CLOUD a la propiedad del hotelero/club/cliente y las credenciales de usuario integrador que ya explicamos en el punto anterior. Para obtener dicha URL y credenciales hay que seguir el proceso de registro de Oracle OHIP que consiste, resumidamente, en dar de alta el entorno del hotel que quiere integrarse y obtener para nuestra aplicación de Oracle unas credenciales de usuario de integración de dicho entorno.

Brevemente explicadas, la URL es la dirección del HOST de la puerta de enlace al servicio al que GM enviará las peticiones. A esta URL se le agregarán las correspondientes rutas/endpoints dependiendo de la operación que se pretenda realizar. Las credenciales de usuario y contraseña son las necesarias para obtener el token de acceso, que debe incluirse en las subsiguientes peticiones que se hagan. Si el token de acceso no puede obtenerse, bien porque no hay conectividad o respuesta del servidor, o bien porque las credenciales no son las adecuadas, no podrá realizarse ninguna operación.

Además, de nuestro lado, se han agregado tres propiedades al archivo config.json del servidor, que contienen nuestra id de cliente, la clave y el identificador de nuestra aplicación de Oracle (que en este caso es siempre la misma, la de integración de OHIP).

El plugin instala también los siguientes campos personalizados (todos con el prefijo oracle_):

Volver arriba

Para que el sistema gestor de la propiedad pueda distinguir correctamente la procedencia de cada cargo/pago enviado a través de Golfmanager, es necesario facilitarle, con cada cargo/pago que se realiza un código de transacción que identifique a la subfamilia del producto que se está cargando/pagando y que sea único para cada caja y subfamilia.

Para ello se ha creado una tabla nueva llamada ohiptxcodemap a la que se puede acceder desde la configuración de Golfmanager, en el mismo menú donde se puede acceder a la configuración del plugin.

En ella podremos asociar los códigos de transacción del sistema gestor de la propiedad a las cajas y subfamilias que tengamos creadas en Golfmanager.

Volver arriba