Direct Connect - Hotel Service v4 - Getting Started
Hotel Service v4 API provides a method for Custom Hotel Source suppliers to provide hotel inventory, rates, and booking related functionality to users of the SAP Concur Online Booking Tool (OBT).
This guide provides information on how the hotel supplier can make their content available for Concur Travel users. Once the interface has been developed and certified with SAP Concur, the inventory will begin appearing in hotel searches by opted-in Travel users.
This API has client/server architecture, where SAP Concur services act as client, pulling information from the hotel suppliers, who acts as server, responding to requests.
Limitations
Access to this documentation does not provide access to the API. SAP Concur products are highly configurable, and not all clients will have access to all features.
Prior Versions
Hotel Service v2 documentation is available here.
Process Flow
This is a basic scenario encompassing all the functionality provided by Hotel Service v4 incorporated into Concur Travel starting from a hotel search through to confirmation of a booking, modification of booking, and ending with a cancellation.
Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Scope Usage
- None
Dependencies
- None
Access Token Usage
- None
Reservation and Read Requests
If a Read request does not arrive within five minutes for a given reservation, the supplier should treat that reservation as an orphan and should seek to cancel it.
Supported Operations
| Operation | Description |
|---|---|
/hotels/search |
Perform the initial search for hotels. |
/hotels/rates |
Retrieve hotel rates. |
/hotels/ratedetails |
Retrieve details the rates of a property, guarantee, cancellation penalty, or nightly prices. This action is required if these details are missing from the /hotels/rates response. |
/hotels/details |
Retrieve hotel description info including media. |
/hotels/reservation |
Reserve hotel rate. |
/hotels/reservation/read |
Read reservation details. Used to acknowledge the receipt of booking confirmation, as well as write information to itinerary while reserving a hotel. |
/hotels/reservation/modify |
Modify given reservation. |
/hotels/reservation/cancel |
Cancel specified reservation. |
Supported OTA Codes
The current list of supported OTA codes for different code list types (RMA, HAC etc.) can be found here.
Supported Error Codes
The current list of supported OTA error codes can be found here.
Non Functional Requirements
Payload Limits
Please note that any responses higher than the suggested content-length may be dropped/truncated and result in an error.
| Operation | Maximum Response (content-length) |
|---|---|
/hotels/search |
5 MB |
/hotels/rates |
5 MB |
/hotels/details |
5 MB |
/hotels/ratedetails |
5 MB |
Recommended Response Times and Retries
All endpoints carry a timeout of 55 seconds. Some operations below support retries in case of 5xx errors as noted. No endpoints will attempt a retry in the event there is a timeout.
SAP Concur services have monitoring in place for each endpoint and will open a ticket with suppliers if a significant degradation or variance of service quality is detected.
| Operation | Recommended Response Times | Support Retries (for 5xx errors) |
|---|---|---|
/hotels/search |
< 5 seconds | Yes |
/hotels/rates |
< 5 seconds | Yes |
/hotels/details |
< 1 second | Yes |
/hotels/ratedetails |
< 1 second | Yes |
/hotels/reservation |
< 5 seconds | No |
/hotels/reservation/read |
< 1 second | Yes |
/hotels/reservation/modify |
< 5 seconds | No |
/hotels/reservation/cancel |
< 5 seconds | No |
Recommended Throughput
Higher throughput allows system to scale and serve large number of travelers. We recommend suppliers provision for resources to support the following throughput.
| Operation | Recommended Throughput (Requests Per Minute) |
|---|---|
/hotels/search |
< 50 |
/hotels/rates |
< 100 |
/hotels/details |
< 100 |
/hotels/ratedetails |
< 50 |
/hotels/reservation |
< 20 |
/hotels/reservation/read |
< 20 |
/hotels/reservation/modify |
< 10 |
/hotels/reservation/cancel |
< 10 |
Note: To prevent no show fees, duplicate bookings and other similar issues, we requires the Hotel Supplier auto-cancel a reservation if a corresponding /hotels/reservations/read call is not made by SAP Concur systems within 5 minutes after the /hotels/reservation call was made.
Emergency Technical Contact
The hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.
Testing Environment
We require the hotel supplier to provide a testing URL or specify properties for testing in a production URL. We require the ability to preform test bookings with test credit cards.
Security
PCI DSS Compliance
As sensitive data and payment card details are transferred via API, hotel suppliers are required to comply with PCI DSS standards.
HTTPS
We require Transport Layer Security v1.2 (TLS 1.2) or higher SSL protocol for data transfers. The hotel supplier is required to provide HTTPS URLs of its endpoint. Standard HTTPS port 443 should be used.
URLs
We will receive a single URL for each environment (Test and Production) from the hotel supplier. All requests will go to that URL.
Authentication
SAP Concur services will send a username and password in the HTTP header (Authorization) where the value of the header will be a base64 encoded string in the form of Basic <username:password>. If the username and password generates an authentication error, then there will be a HTTP 401 response.
HTTP Headers
SAP Concur services will send the following HTTP headers in every request. Please note that some libraries used to handle the requests may be case sensitive and that the SAP Concur login-id and traveler uuid are now part of the payload for each request and no longer available as headers.
| Name | Type | Format | Description |
|---|---|---|---|
Authorization |
string |
base64 |
An encoded string in the form of Basic <username:password>. |
Content-Type |
string |
- | All communication with the HS4 API is by way of a application/json content type. |
Accept |
string |
- | SAP Concur will always set the Accept header to application/json. |
concur-correlationid |
string |
- | In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. This unique code can be used during troubleshooting as it identifies the API call in the log files. |