Index

Oracle's Hospitality Integration Platform (OHIP), offers a solid set of hospitality and management APIs for any hotel unit hosted on Oracle servers, to which applications/solutions created by anyone can subscribe. An Oracle partner, duly registered as such, can request access to the OHIP APIs. This set of endpoints offers third-party software the possibility of communicating practically all hotel management operations carried out through it to the client/hotelier's property, directly and without the need for interposed software.

Unlike other schemes, such as the Opera On Premise scheme, the content of communications with OHIP is sent and received in JSON format and not in SOAP XML format, which greatly facilitates the processing of request and response bodies given the circumstances of our development environment.

In this way, Golfmanager clients who have a hotel management account with Oracle will have the possibility of installing this integration module and centralizing the most basic aspects of the day-to-day management of the hotel property, such as charges to room, returns, configurable manual and automatic sending of charges, etc.

Today, as of the writing of this manual, the hotel management functionalities implemented in the Oracle plugin are the following:

- Room charges : Includes the possibility of refunds, as well as the possibility of making negative charges.

- Sending charges from other payment methods configured to be sent to the property's servers.

Go back up

For reasons of economy and ease of development, the basic flow of the request and response scheme used in the plugin is based exclusively on the use of two operations from the set of API modules that OHIP offers, more specifically the CSH ( cashiering ) and RSV ( reservations ).

The CSH module , offers the necessary APIs to notify the property management system of the movements and cash flow operations that are carried out.

The RSV module , provides the appropriate APIs for managing reservations such as obtaining them, either en masse, or filtering by any search criteria, as well as those to notify new reservations, modify them, etc...

In our case, the entire system pivots exclusively around the getHotelReservations operation of the RSV module and the postBillingCharge operation of the CSH module .

This is because the style pattern used to communicate the cash flows of the alternative payment methods to the room charge consists, pardon the redundancy, of making charges to a pseudo-reservation of a fictitious room, in which the check-in operations and check-out serve as daily cash opening and closing. These rooms are identified as pay master rooms by the acronym PM within Oracle OHIP's own terminology.

In terms of authentication, the API used is not part of the Oracle OHIP set of APIs but rather that of oAuth. The authentication system used by Oracle can be counterintuitive and even arbitrary at some points. Below, we simply describe what this request should include according to Oracle's own documentation.

The method used is basic auth , that is, encoding username and password in the Authorization header of the request. These username and password correspond to our clientId and clientSecret , which we can obtain through our Oracle developer portal. Additionally, we must include in the request headers the x-app-key property that identifies which Oracle Partner application, in this case us, we want to access.

Additionally, in the body of the authorization request, the credentials of the integration user must be included that must have been previously requested and created in the property's user table and that are actually the ones that point to the final client's hotel property.

In a single access token request, we are basically sending two things:

1- Through the headers we specify which of the Oracle Market-Place applications we want to access, in this case, our production OHIP application, using our app-publisher credentials in Oracle.

2- In the body of the request, we will provide the data of the requested integration user to the client through the identity self-service portal of their Oracle Cloud account.

In this way, Oracle systems have everything necessary to operate the set of OHIP APIs against the Club's property. If everything is ok, we will obtain a token, which we must accompany the rest of the calls, this time, to the set of Oracle OHIP APIs. These calls use the bearer-token method to authenticate, unlike the token request itself, which uses the basic auth method .

The access token is always requested before any other call that the plugin makes. This is not technically necessary, as it is valid for one hour. In addition to having to write more code to refresh it from time to time, obtaining it in advance represents a first barrier against possible service outages or credential errors, so that these possibilities do not have to be handled for each of the rest of the calls to the API's of OHIP. If the access token request fails for any reason, the operation will simply not be attempted and a corresponding error message will be thrown.

Go back up

The call flow that is made when room charges are made consists of the prior request for reservations, using the API operation getHotelReservations with a filter detailed in section 4 of this manual, to display them in a selector to the Admin user of the POS. .

Once these rooms have been obtained and a valid one is chosen, when you press Accept, before making any OHIP request, an attempt is made to make the payment internally in our system. If this payment fails, the OHIP notification process simply does not continue. If the payment could be made internally in our software, then we make a request to execute the postBillingCharge operation of the CSH module of the OHIP APIs. If for any reason beyond our control, the response obtained from Oracle is an express rejection or error, then our software will undo the internally consolidated sale. The results of these operations will be reflected in the Oracle transactions table, as well as the requests and responses obtained, and the sales and/or collections involved.

As for the rest of the payment methods, the plugin contains a subscription to the onTicketCreated event . In this way, every time a ticket is created, the function that handles the event subscription checks if it comes from a payment method that has a payMasterReservationId configured , that is, the ID of a pseudo-reservation of a paying master room. If this is the case, this function will pass the newly created ticket to the plugin function that performs the room charge, so that it is processed against the master room of the reservation configured in the payment method.

These operations, as with the Room Charge, are recorded in the transaction table. However, there is a subtle but fundamental difference that should be highlighted. When we charge a specific, real room, and Oracle responds with a rejection response, we will obviously undo the payment in GolfManager. However, when we communicate the cash flow of other payment methods, if Oracle responds with a rejection we should not care at all internally. The Oracle OHIP rejection will simply be recorded in the transaction table.

However, for these alternative payment methods, and in cases of unexpected or scheduled service outages, if the communication could not be carried out due to a simple lack of connectivity or because the service was disabled from the plugin configuration, in such a way that the If you have been able to obtain a positive or negative response from the cloud service, you can try to resend it from the resend button added to the collections view.

This button will attempt to forward the information for transactions marked as failed and containing ticket information back to the Oracle server. In this way, since the failed transactions of charge to the real room do not save a ticket, they will not be resent which, in addition, would not make any sense, since the payment was not consolidated in GM, since in the case of charge to the real room The confirmation of the payment in GM is conditional on acceptance by the Oracle OHIP system, while in failed transactions that save a ticket this is representative of the fact that a payment was consolidated in GolfManager and, therefore, makes sense retry your communication to Oracle if it failed due to lack of express response from Oracle (HTTP errors).

Because if the service is down you do not want to constantly receive error messages, you can disable the service from the plugin configuration. Room charges obviously cannot be made. However, the rest of the payment methods will continue to generate a failed communication attempt in the Oracle transaction table, with an error code indicating that they could not be sent because the service was disabled, so that they can be resend in as long as the service is restored using the aforementioned button.

Using the Resend Transactions button while the service is disabled will "reset" the error status of failed transactions containing a ticket. That is, those failed transactions that contain a ticket and that have failed due to having received an express rejection response from the Oracle OHIP APIs, will update their error status to the status of "not sent due to disabled service". This may be useful, but only in a very small number of cases. It should not be used lightly. The system will adequately warn us about this when we try to resend failed transactions when the service is disabled from the plugin configuration.

Go back up

In order to authorize the integration between the company and the system through an API, you will first have to send the document completed and signed by both parties to Golfmanager. Select the following Document to download it:

Go back up

On the GM side, in the plugin configuration view we will only have to enter the currency in which we want to carry out the transactions, the URL address of the Oracle CLOUD gateway to the hotelier/club/client property and the user credentials integrator that we already explained in the previous point. To obtain said URL and credentials, you must follow the Oracle OHIP registration process, which consists, in short, of registering the environment of the hotel that you want to integrate and obtaining user credentials for the integration of said environment for our Oracle application.

Briefly explained, the URL is the HOST address of the gateway to the service to which GM will send the requests. The corresponding routes/endpoints will be added to this URL depending on the operation to be performed. The user and password credentials are necessary to obtain the access token, which must be included in subsequent requests made. If the access token cannot be obtained, either because there is no connectivity or response from the server, or because the credentials are not appropriate, no operation can be performed.

Additionally, on our side, three properties have been added to the server's config.json file , which contain our client id, the key and the identifier of our Oracle application (which in this case is always the same, the integration of OHIP).

The plugin also installs the following custom fields (all prefixed with oracle _):

- In the payment method:

- payMasterReservationId : This field represents the pseudo-reservation ID of the fictitious room designated to receive charges for said payment method. It should only be completed if you want the charges made with said payment method in GM to be sent to Oracle Cloud. Those payment methods that have this field empty will not send their charges to Oracle Cloud .

- In the sales line:

- reservationID - Reservation ID: If it has a value, it is the id of the reservation to which said line was charged/charged. If a sales line not paid with the Oracle charge to room payment method has a value in this field then said id is representative of the fictitious reservation made to a master charge room.

- roomChargePaid - Contains a true/false value. Indicates whether the sales line was paid by Oracle room charge. It allows us to know which lines were paid with this payment method.

- In the collection line:

- sent : True or false. Indicates whether the payment has been sent to the Opera Cloud servers.

Go back up

In order for the property management system to correctly distinguish the origin of each charge/payment sent through GolfManager, it is necessary to provide, with each charge/payment that is made, a transaction code that identifies the subfamily of the product being processed. loading/paying and that is unique for each box and subfamily.

ohiptxcodemap has been created that can be accessed from the GolfManager configuration, in the same menu where you can access the plugin configuration.

In it we can associate the transaction codes of the property management system to the boxes and subfamilies that we have created in GolfManager.

Go back up