Using the Oracle Hospitality APIs

Oracle Payment Interface APIs

Overview

Reservations created via third-party channels often include a credit card number to secure the booking. The OPI Token Exchange API openPaymentBulkTokenExchange will allow partners to exchange credit card numbers for tokens, using the Payment Service Provider that OPERA Cloud is integrated to for payment processing. The tokens are then stored in OPERA Cloud against the reservation and can be used for subsequent payments as needed.

Prerequisites

To call the OPI Token Exchange API, the hotel must purchase and enable the Oracle Payment Interface Cloud Service.

Calling the Oracle Payment Interface APIs

Oracle Payment Interface APIs are called in the same way as Oracle Hospitality Property APIs.

If the hotel does not have the Oracle Payment Interface Cloud Service enabled, the following error is returned:

HTTP status: 404

Response body: OPICS-NOT_FOUND

Refer to the explanation of this error for resolution steps.

Parent topic: Using the Oracle Hospitality APIs

Oracle Hospitality Nor1 Integrated Upsell APIs

Obtaining Details from Oracle Hospitality Nor1

You must request access to the Nor1 Upgrades APIs by emailing the Nor1 team (hgbu_nor1_partner_rqs_grp@oracle.com) and providing the following details:

Partner Organization Name
Oracle Cloud Account Name
Oracle Cloud Account ID

Provide the following details if you are an OPERA Cloud Foundation customer:

Tenant / Chain Code
SSD URL
Indicate if the chain is a Production or UAT chain

After sending the email, you will receive further instructions within 5 business days. Once access is granted, Oracle will send you the following:

providerId — This is your Nor1 unique provider code that is global and used across all hotels.

Authenticating to Oracle Hospitality Nor1 Upgrades APIs

The Nor1 Upgrades APIs are secured the same way as the Oracle Hospitality Property APIs. For further details, refer to the following topics:

Related Topics

Parent topic: Using the Oracle Hospitality APIs

Changing Your Integration User Password

Integration User passwords expire after 1 year and must be changed every year. To change your password:

Find the email you received when the hotel approved your integration user. This includes a URL for the Shared Security Domain identity server. Go to this URL.
Log in using your integration username and password.
Go to the “My Information” panel. This will show you basic information about your integration user.
Expand the “Change Password” section.
Reenter your current integration user password.
Enter your new integration user password twice. Please note the password policy, which can be viewed by clicking the “i” icon next to the New Password field.

Parent topic: Using the Oracle Hospitality APIs

API Troubleshooting

If you are experiencing issues when consuming APIs, check the following:

API

Verify the API you are calling is visible in the APIs tab of the developer portal.
Verify the API version in the URL matches the version v0 or v1 listed in the developer portal.
If connecting to OPERA Cloud, verify the functionality being used is active and available for the relevant OPERA Cloud PMS version by reviewing the following guides:
- OPERA Cloud Services Release Readiness Guide 23.2
- OPERA Cloud Services Release 23.2
Verify the input variables are relevant to the OPERA Cloud solution being called and are not a copy of Postman samples. Note that each OPERA Cloud environment is uniquely configured. You can determine the configuration specific to the hotel you are calling by reviewing the List of Values and Enterprise Configuration APIs.

Environment and Credentials

Verify the environment (chain) card is on the Environments tab in the developer portal.
- If you are an integration partner and the environment is not listed, then follow the steps in the Obtaining Details from the Hotel topic to gain access.
- If you are an integration partner and this is a production environment, verify you have followed the steps in the Moving to Production topic.

Verify the application's second tab shows the plans expected in the developer portal.
Verify the application key being used matches the application checked in step 2 in the developer portal.
Verify the clientId and clientSecret correspond to those on the Environment card under the Environments tab in the developer portal.
Verify the following for the integration user:
1. The user is in the organization I<SSD org code>
  1. The user was created from the SSD URL ending "?apiuser=y"
2. The username does not have spaces in it.
  1. If spaces in the current username exist, create a new integration user with a shorter username with no spaces.
3. The user has the <SSD org code>-WSACCESS role.
  1. Log in to SSD using the link in the "Thank you" email and then go to "My Access" to see if the user has the WSACCESS role.
  2. If not, contact the environment owner and ask for approval for this role.
4. Verify if the oAuth token is still valid (note the token lasts for 60 minutes). Obtain a new oAuth token to ensure it is valid.

Mandatory Headers

Verify the required headers:

Calling OPERA Cloud Property APIs — Ensure the x-hotelid header matches a hotel in the chain being called.
- OPERA Cloud Property APIs for OPERA Cloud 22.1+ — When verifying data for the hub level, ensure you send x-hubid and not x-hotelid.
Calling Oracle Hospitality Distribution APIs — Verify the x-channelCode header matches the header provided via email by the Oracle Hospitality Distribution team.
Calling NOR1 Upgrade API — Ensure the providerId header matches the header provided via email by the NOR1 team.
If sending a POST request, ensure you are sending the "accept" header as "application/json."

Errors

Verify the list of errors and follow the suggested resolution paths.

Logging an Issue

Before reporting an issue, first exhaust the self-service troubleshooting.

If you still have an issue with an API, ensure you include the following information when logging the issue:

Full CURL request (with credentials redacted)
Response code
OPERA Cloud environment version number (via this API)
OPERA Cloud environment name or gateway URL
Context of what is being attempted (for example, type of integration, task being carried out, and so on).

Parent topic: Using the Oracle Hospitality APIs

Common HTTP Errors and Messages

Common error codes produced by Oracle Hospitality APIs are listed in the following table.

For a complete list of OPERA Cloud REST API error codes, refer to the Web Service Error Codes topic.

Table 6-1 Common HTTP Error Messages

Error Status	Error Response Body	How to Resolve
400	Response body details which fields are at fault.	Change the fields mentioned in the error response, such that they align with the specifications; referencing the swagger spec will help here. In some cases the values are determined by a (hotel specific) configured List of Values (LOV), so ensure you supply a value that is in the LOV for that hotel; the List Of Values Oracle Hospitality APIs will help here.
400	This API is not supported for the current database version.	Contact Oracle Customer Support at the Customer Support Portal stating the gateway being called and the error message received.
401	No response body	Ensure your oAuth token is valid and latest. Also, ensure your Application Key is valid. Check it by Viewing the Application Key
401	"invalid_grant", "[Wrong Password]"	Check the password of the integration user. See Changing Your Integration User Password for more information.
401	UnAuthorized to access the resource	This could be caused by the integration user missing the WSACCESS role. Ensure the environment owner has approved the integration user. This could also occur if you are sending the wrong hotelId. Ensure the hotel ID being sent in the x-hotelid header matches a hotel in the environment being called.
403	No response body	Ensure your oAuth token is valid and up to date. Re-request it by using Authenticating to Oracle Hospitality Property APIs. Also ensure your integration user in OPERA Cloud Services has access to the property (hotel) you supplied in the "x-hotelid" header.
403	No Subscribed Plan or API found	This occurs when accessing an API to which you do not have access. If this is an early adopter (v0) API and you think you already have access to the Early Adopter API Program, check that the application specified in the x-app-key header has access to the Early Adopter APIs by following this process: In the Developer Portal, click the Applications tab. Choose the application whose key matches the x-app-key being sent (double check against the end of the application key that appears in the list of applications). Click View details Click the Subscriptions tab and verify it shows all of the following: Early Adopter Hospitality APIs OAuth If you have not yet called the v0 APIs but would like to, contact us as explained in the Early Adopter API Program. If this is a Distribution API, you must register in the Developer Portal to use the API.
403	User is not authorized to access data for resort	Check that your integration user has the WSACCESS role: Find the email you received when the hotel approved your integration user. This includes a URL for the Shared Security Domain identity server. Go to this URL. Log in using your integration username and password. If the login fails, click the "Can't Sign In?" link to reset your password. Verify the hotelId supplied in the "x-hotelid" header matches the one provided by the hotel. See Obtaining Details from the Hotel for more information.
404	No response body	If you are calling an Asynchronous API: Once you have sent the final GET call to obtain the results of the async processing, the data is no longer available on the same summaryId, so you will receive a 404 error. To retrieve the data again, you must restart the request sequence at step one.
404	OPICS-NOT_FOUND	Contact the environment owner to verify that Oracle Payment Interface Cloud Service has been set up by checking for product ID 14308 and ensuring that Token Exchange Service is selected. Customers can contact Oracle Consulting or a reseller to configure Oracle Payment Interface Cloud as needed.
405	No response body	Ensure the HTTP verb you are using is supported by the Oracle Hospitality APIs by checking the Oracle Hospitality APIs documentation.
406	No response body	Set your "accept" header to "application/json" as the Oracle Hospitality APIs will produce only "application/json".
413	No response body	Ensure your request matches the documented request body schema. If your scenario requires "bulk" fetch or update then consider the jobbed Oracle Hospitality APIs.
414	No response body	Consider whether you need to specify all the query parameters being specified; there may be more efficient resources or ways to structure your query.
415	Unsupported Media Type	Ensure your request payload has a content-type of "application/json".
500	Response body details the error.	Try your request again in a few moments or contact Oracle Customer Support at the Customer Support Portal.
502	No response body	Try your request again in a few moments or contact Oracle Customer Support at the Customer Support Portal.
503	No response body	Try your request again in a few moments or contact Oracle Customer Support at the Customer Support Portal.

Parent topic: Using the Oracle Hospitality APIs

HTTP Methods Supported

The Oracle Hospitality APIs use the following HTTP verbs:

GET to retrieve resources.
HEAD to query the status of jobbed requests.
POST to create resources.
PUT to replace resources.
DELETE to delete resources.

Parent topic: Using the Oracle Hospitality APIs

HTTP Response Headers

POST always returns the location of the newly created resource in a Location header.

Parent topic: Using the Oracle Hospitality APIs

Github and Postman Collections

Oracle Hospitality has a Github repository containing both Oracle Hospitality REST API specifications and accompanying Postman Collections.

You can access Github and locate the REST API specifications and Postman Collections at the following URL: https://github.com/oracle/hospitality-api-docs.

REST API Specifications

In the rest-api-specs folder in Github, you can view the published V1 APIs for OPERA Cloud and/or download the json specifications for the Oracle Hospitality APIs.

Postman Collections

In the postman-collections folder in Github, you can download and use the Postman Collection to help you get you started with our APIs and become more familiar with using them. The postman-collections folder contains the following content:

Postman collections with many different API call samples on how to perform different functional workflows (for example, digital check-in and checkout).
Postman Environment defining the main environment variables required to use the postman collections against our Hospitality APIs. Ensure you update this file with the relevant credentials and data for the environment to which you are connecting.
Document describing the different workflows supported in the postman collections.

The Postman collection is also available at the following URL: https://www.postman.com/hospitalityapis/workspace/oracle-hospitality-apis/overview.

Setting Up Your Postman Collection

To start calling the APIs, proceed to set up a postman environment collection using the below information. You might want to configure one environment collection for UAT and another one for Production as the variables will differ.

Table 6-2 Information for Postman Environment Collection

Hostname	This is the API gateway URL that can be viewed by logging into the Developer portal and viewing the environments tab.
Username & Password	This is the Integration username and password. See Authenticating to Oracle Hospitality Property APIs for the steps to obtain these.
CLIENT_ID & CLIENT_SECRET	The Client ID obtained from the OHIP Developer portal. See Viewing the Client Secret for details.
AppKey	The application key that was previously obtained. See Viewing Application Details for the specific steps.
HotelId	The Hotel ID against which you want to perform actions (for example, obtaining reservation data).

Once you have added these values into your postman environment, you can begin to call the oAuth Token. If everything is set up correctly, OHIP will respond with a HTTP 200 OK response, including the oAuth token. Now you can proceed to try out the collections as required.

Parent topic: Using the Oracle Hospitality APIs

Date Formats

Dates in the Oracle Hospitality APIs are expressed in the RFC3339 “full-date” format (that is, date-fullyear "-" date-month "-" date-mday. "T" time-hour ":" time-minute ":" time-second "Z" / ("+" / "-") time-hour ":" time-minute). The following are examples of this format:

2023-06-05 for 5th of June 2023
2023-06-05T08:43Z or 2023-06-05T09:43+01:00 for 5th of June 2023 at 8:43 AM in the UTC time zone or 9:43 in the local time zone

Most times are expressed in local time zones, not in Coordinated Universal Time (UTC).

Asynchronous APIs return times in Coordinated Universal Time (UTC).

For Profiles APIs, the time depends on where the profile was created. For example:

If the profile was created at the hub level, then Profiles APIs return times in the hub time zone if the time zone is set. If no hub time zone is set, then for a profile created at the hub level, Profiles APIs return in Coordinated Universal Time (UTC).
If the profile was created at the property level, then Profiles APIs return times in the property time zone if the time zone is set. If no property time zone is set, then for a profile created at the property level, Profiles APIs return in Coordinated Universal Time (UTC).

Table 6-3 Asynchronous API Times Zones

API	Where was the Profile Created?	Is the Time Zone Set?	Time Zone Returned
Asynchronous APIs	n/a	n/a	Coordinated Universal Time (UTC)
Profiles APIs	Hub	No	Coordinated Universal Time (UTC)
Profiles APIs	Hub	Yes	Hub timezone
Profiles APIs	Property	No	Coordinated Universal Time (UTC)
Profiles APIs	Property	Yes	Property timezone
All other property APIs	n/a	n/a	Property timezone

Parent topic: Using the Oracle Hospitality APIs

Special Characters in URLs

Query parameters for some Hospitality API operations require text to be entered, for example, a rate code name or a person's name. If the text includes special or multibyte characters, these characters must be URL encoded. For example, an asterisk URL encodes as %2A.

For encoding standards, refer to the RFC Series on the RFC Editor website. The standard that defines when to encode is RFC3986 (section 2.4, When to Encode or Decode).

Parent topic: Using the Oracle Hospitality APIs