<commit_before>---
title: Hotel Direct Connect
layout: reference
---

## Disclaimer
This version is a draft only. Hotel Service 2.0 API is not final and is a subject to change.

## Description
The Hotel Services v2 Direct Connect from Concur Connect provides a method for Travel users to access hotel inventory.

The Hotel Service 2.0 API from Concur is a specification based on OTA 2015 standard for Hotel Suppliers.
Please refer to XSD schema of the service and WSDL service description.
This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. 
Once the Hotel Supplier has developed and certified their interface with Concur, their inventory will begin appearing in hotel searches by opted-in Travel users.
This API has client/server architecture, where Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to Concur’s requests. This guide specifies the request and response format required by Concur.


This callout differs from the inbound Concur web services in the following ways:

* It uses an outbound message where Concur calls a public facing API endpoint provided by the hotel supplier.
* The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by Concur.

## Works with these Concur products
* **Travel for Concur Professional/Premium desktop**
* **Travel for Concur Standard desktop**

## Product Restrictions

Hotel Service 2 API inventory is not accessible from Concur mobile.
Concur products are highly configurable, and not all clients will have access to all features.

## API Implementation Process Overview
The configuration process has the following steps:

1.  Concur shares API specification (this guide), schema and all necessary documentation with Hotel content partner.
2.	Concur and The Hotel Supplier agrees on scope and timeline of development to Concur API specification.
3.	Concur provides range of IP addresses of sandbox endpoint for the Hotel Suppliers whitelist.
4.	The Hotel Supplier creates testing endpoint on their system that Concur uses to access their inventory. The Hotel Supplier provides the URIs and credentials for their test system to Concur.
5.	Concur creates a sandbox account for the Hotel Supplier.
6.	The Hotel Supplier creates the application on their system that will accept the requests from Concur and return the appropriate responses. During development Concur provides support by clarifying  API usage and scenarios, and by testing interim milestones. 
7.	Concur and the Hotel Supplier validate the application: Concur sets up the vendor in the certification systems and runs a series of tests to validate the interaction between the two systems.
8.	Once certification passes, the Hotel supplier sends Concur the production URIs and credentials.
9.	Concur updates the production servers with the supplier’s production data.
10.	Upon successful completion, the supplier will be live in Concur for any customer to enable.
11.	The Travel client opts in to the Hotel callout (within the Travel Configuration) to allow their users to view and book the available inventory. Travel client sets ID which will identify them at Hotel suppliers for features like Corporate rates. 

## Non-Functional Requirements

### 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
To allow Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. Concur needs to be able to perform test bookings with testing credit cards.

### Security 
#### PCI DSS compliance
As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. Concur is compliant with PCI DSS standard and undergoes regular security audits.

#### HTTPS
The Hotel Supplier needs to support secure communication of TLS 1.1 or newer. The Hotel Supplier will provide Concur HTTPS URL of its endpoint.
Standard HTTPS port 443 should be used.


#### Concur IP ranges
If Hotel Supplier is using IP whitelisting policy, Concur will use following addresses to access Supplier’s systems from.

* `172.16.58.3/24` -	Production
* `172.16.17.32` -	Production
* `192.168.127.1224/28` -	Production
* `192.168.127.12` -	Production
* `172.16.17.32/22` -	Production
* `172.16.31.10` -	Production
* `172.16.31.10` -	Production
* `192.168.3.11` -	Production
* `192.168.3.11` -	Production
* `192.168.127.12/25` -	Production
* `192.168.127.12` -	Production
* `192.168.127.12` -	Production
* `172.16.58.3/27` -	Production

* `192.168.3.11/28` -	QA
* `172.16.17.32/25` -	QA
* `192.168.127.12` -	QA 
* `192.168.127.12/24` -	QA
* `192.168.3.11` -	QA
* `172.16.31.10/24` -	QA
* `172.16.17.32` -	QA
* `172.16.58.3` - QA
* `172.16.17.32/24` - QA
* `192.168.3.11/29` -	QA

#### Authentication

As authentication, Concur sends userID and password in each message SOAP header: 

```xml
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> 
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <authentication xmlns="http://www.concur.com/webservice/auth">
    <userid>testLogin123</userid>
    <password><PASSWORD></password> 
  </authentication>
</Header>
```

### Authentication.xsd:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.concur.com/webservice/auth" targetNamespace="http://www.concur.com/webservice/auth" elementFormDefault="qualified" version="1.0" id="TransactionControlHeader">
	<xsd:element name="authentication">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="userid" type="xsd:string"/>
				<xsd:element name="password" type="xsd:string"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>
</xsd:schema>
```

### URLs and headers
Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL. 
Content Type is application/xml.
To define, what operation needs to be performed, HTTP headers are used, as example:
`SOAPAction:availability.`

CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped.
The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID. 

Concur is using date as xs:date XML type "2017-05-01".


### Response Times
Concur needs to receive all responses within 55 seconds, otherwise it causes timeout. To prevent no show fees, duplicate bookings and other similar issues, Concur recommends to perform Auto-Cancel by the Hotel Supplier if ReadRQ message is not sent by Concur 5 minutes after HotelResRS message was sent to Concur. 

## Supported operations
Hotel Service API 2.0 supports following operations:
1.	Search RQ and RS – to get list of hotels
2.	Descriptive Info RQ and RS – to get hotel description and photos
3.	Availability RQ and RS– to get rates for selected hotels
4.	Reservation RQ and RS – to book a selected rate
5.	Read Itinerary RQ – to get information for Itinerary. Response message in HotelResRS.
6.	Cancel RQ and RS – to cancel a reservation.


### Message flow

#### Hotel search and reservation
1.	Search. Sent after user clicks on button Search.
2.  Availability. Sent after Search message if configured, or after user clicks on Get Rates button.	
3.  Descriptive Info. Sent after user click on hotel details button or hotel thumbnail picture.
4.	Reservation. Sent after user click on Reserve button.
5.	Read Itinerary. Sent automatically after Reservation message.

#### Hotel itinerary check
1. Read Itinerary. Supplier replies with Reservation response.

#### Hotel cancel
1. Read Itinerary. Supplier replies with Reservation response.
2. Cancel. After user agrees with Cancellation policy and clicks on Cancel button.


Use cases and message structure
---------

#### Company Identification

It is possible to setup specific ID – Requestor ID - to identify Company or it's organizational subunit, a
customer that is using Concur API. Requestor IDs are issued by the Hotel
supplier and are configured by TMC or entity responsible for vendor setting in
Concur Travel. That Requestor ID allows suppliers to shape Preference Level,
specific rates etc. for customers. As not all suppliers require such features,
this is optional setting in Concur Travel.


### OTA operations 

### **Hotel Search**

>   **SOAPAction:**  **search**

>   **OTA name:** HotelSearch

#### Message structure

OTA_HotelSearchRQ

|  Element |	Required	|  Description |
|----------|---------------------------------------|-|
|  RequestorID |	N	| The corporate identifier|
|  Position |	Y	|  The Position element contains three attributes, Latitude, Longitude, used to indicate the geographic location(s) requested by the search, expressed in notation specified by ISO standard 6709.|
|  Radius |	Y	| Used to specify the extent of a search area. The extent is relative to an element (position, address, hotel reference, etc.) present in this ItemSearchCriterionType that specifies a location.|
|UnitOfMeasureCode| Y | The unit of measure in a code format. Refer to OpenTravel Code List Unit of Measure Code | 
|  HotelRef |	N	| Indicates the detail of hotel reference information.|
|  StayDateRange |	Y	| Range of dates, or fixed set of dates for Availability Request.|

OTA_HotelSearchRS

|  Element |	Required	|  Description |
|----------|---------------------------------------|-|
|  ChainCode |	N	| 2 letter GDS chain code. The code that identifies a hotel chain or management group. Used for Chain filter in UI, and for Travel Rules based on GDS codes|
|  ChainName |	N	| Detailed property level information.|<commit_msg>languages<commit_after>---
title: Hotel Direct Connect
layout: reference
---

## Disclaimer
This version is a draft only. Hotel Service 2.0 API is not final and is a subject to change.

## Description
The Hotel Services v2 Direct Connect from Concur Connect provides a method for Travel users to access hotel inventory.

The Hotel Service 2.0 API from Concur is a specification based on OTA 2015 standard for Hotel Suppliers.
Please refer to XSD schema of the service and WSDL service description.
This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. 
Once the Hotel Supplier has developed and certified their interface with Concur, their inventory will begin appearing in hotel searches by opted-in Travel users.
This API has client/server architecture, where Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to Concur’s requests. This guide specifies the request and response format required by Concur.


This callout differs from the inbound Concur web services in the following ways:

* It uses an outbound message where Concur calls a public facing API endpoint provided by the hotel supplier.
* The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by Concur.

## Works with these Concur products
* **Travel for Concur Professional/Premium desktop**
* **Travel for Concur Standard desktop**

## Product Restrictions

Hotel Service 2 API inventory is not accessible from Concur mobile.
Concur products are highly configurable, and not all clients will have access to all features.

## API Implementation Process Overview
The configuration process has the following steps:

1.  Concur shares API specification (this guide), schema and all necessary documentation with Hotel content partner.
2.	Concur and The Hotel Supplier agrees on scope and timeline of development to Concur API specification.
3.	Concur provides range of IP addresses of sandbox endpoint for the Hotel Suppliers whitelist.
4.	The Hotel Supplier creates testing endpoint on their system that Concur uses to access their inventory. The Hotel Supplier provides the URIs and credentials for their test system to Concur.
5.	Concur creates a sandbox account for the Hotel Supplier.
6.	The Hotel Supplier creates the application on their system that will accept the requests from Concur and return the appropriate responses. During development Concur provides support by clarifying  API usage and scenarios, and by testing interim milestones. 
7.	Concur and the Hotel Supplier validate the application: Concur sets up the vendor in the certification systems and runs a series of tests to validate the interaction between the two systems.
8.	Once certification passes, the Hotel supplier sends Concur the production URIs and credentials.
9.	Concur updates the production servers with the supplier’s production data.
10.	Upon successful completion, the supplier will be live in Concur for any customer to enable.
11.	The Travel client opts in to the Hotel callout (within the Travel Configuration) to allow their users to view and book the available inventory. Travel client sets ID which will identify them at Hotel suppliers for features like Corporate rates. 

## Non-Functional Requirements

### 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
To allow Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. Concur needs to be able to perform test bookings with testing credit cards.

### Security 
#### PCI DSS compliance
As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. Concur is compliant with PCI DSS standard and undergoes regular security audits.

#### HTTPS
The Hotel Supplier needs to support secure communication of TLS 1.1 or newer. The Hotel Supplier will provide Concur HTTPS URL of its endpoint.
Standard HTTPS port 443 should be used.


#### Concur IP ranges
If Hotel Supplier is using IP whitelisting policy, Concur will use following addresses to access Supplier’s systems from.

* `172.16.58.3/24` -	Production
* `172.16.17.32` -	Production
* `192.168.127.12/28` -	Production
* `192.168.127.12` -	Production
* `172.16.17.32/22` -	Production
* `172.16.31.10` -	Production
* `172.16.31.10` -	Production
* `192.168.3.11` -	Production
* `192.168.3.11` -	Production
* `192.168.127.12/25` -	Production
* `192.168.127.12` -	Production
* `192.168.127.12` -	Production
* `172.16.58.3/27` -	Production

* `192.168.3.11/28` -	QA
* `172.16.17.32/25` -	QA
* `192.168.127.12` -	QA 
* `192.168.127.12/24` -	QA
* `192.168.3.11` -	QA
* `172.16.31.10/24` -	QA
* `172.16.17.32` -	QA
* `172.16.58.3` - QA
* `172.16.17.32/24` - QA
* `192.168.3.11/29` -	QA

#### Authentication

As authentication, Concur sends userID and password in each message SOAP header: 

```xml
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/"> 
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <authentication xmlns="http://www.concur.com/webservice/auth">
    <userid>testLogin123</userid>
    <password><PASSWORD></password> 
  </authentication>
</Header>
```

### Authentication.xsd:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.concur.com/webservice/auth" targetNamespace="http://www.concur.com/webservice/auth" elementFormDefault="qualified" version="1.0" id="TransactionControlHeader">
	<xsd:element name="authentication">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="userid" type="xsd:string"/>
				<xsd:element name="password" type="xsd:string"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>
</xsd:schema>
```

### URLs and headers
Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL. 
Content Type is application/xml.
To define, what operation needs to be performed, HTTP headers are used, as example:
`SOAPAction:availability.`

CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped.
The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID. 

Concur is using date as xs:date XML type "2017-05-01".


### Response Times
Concur needs to receive all responses within 55 seconds, otherwise it causes timeout. To prevent no show fees, duplicate bookings and other similar issues, Concur recommends to perform Auto-Cancel by the Hotel Supplier if ReadRQ message is not sent by Concur 5 minutes after HotelResRS message was sent to Concur. 

## Supported operations
Hotel Service API 2.0 supports following operations:
1.	Search RQ and RS – to get list of hotels
2.	Descriptive Info RQ and RS – to get hotel description and photos
3.	Availability RQ and RS– to get rates for selected hotels
4.	Reservation RQ and RS – to book a selected rate
5.	Read Itinerary RQ – to get information for Itinerary. Response message in HotelResRS.
6.	Cancel RQ and RS – to cancel a reservation.


### Message flow

#### Hotel search and reservation
1.	Search. Sent after user clicks on button Search.
2.  Availability. Sent after Search message if configured, or after user clicks on Get Rates button.	
3.  Descriptive Info. Sent after user click on hotel details button or hotel thumbnail picture.
4.	Reservation. Sent after user click on Reserve button.
5.	Read Itinerary. Sent automatically after Reservation message.

#### Hotel itinerary check
1. Read Itinerary. Supplier replies with Reservation response.

#### Hotel cancel
1. Read Itinerary. Supplier replies with Reservation response.
2. Cancel. After user agrees with Cancellation policy and clicks on Cancel button.


Use cases and message structure
---------

#### Company Identification

It is possible to setup specific ID – Requestor ID - to identify Company or it's organizational subunit, a
customer that is using Concur API. Requestor IDs are issued by the Hotel
supplier and are configured by TMC or entity responsible for vendor setting in
Concur Travel. That Requestor ID allows suppliers to shape Preference Level,
specific rates etc. for customers. As not all suppliers require such features,
this is optional setting in Concur Travel.

#### Languages

Concur will send two letter PrimaryLangID and AltLangID in ISO 639-1 format in all requests to specify in which language information is requested.
If Hotel Supplier doesn't support PrimaryLangID, AltLangID should be used.
Concur [supported languages](https://developer.concur.com/tools-support/reference/hotel-direct-connect-codes.html#method5)  


### OTA operations 

### **Hotel Search**

>   **SOAPAction:**  **search**

>   **OTA name:** HotelSearch

#### Message structure

OTA_HotelSearchRQ

|  Element |	Required	|  Description |
|----------|---------------------------------------|-|
|  RequestorID |	N	| The corporate identifier|
|  Position |	Y	|  The Position element contains three attributes, Latitude, Longitude, used to indicate the geographic location(s) requested by the search, expressed in notation specified by ISO standard 6709.|
|  Radius |	Y	| Used to specify the extent of a search area. The extent is relative to an element (position, address, hotel reference, etc.) present in this ItemSearchCriterionType that specifies a location.|
|UnitOfMeasureCode| Y | The unit of measure in a code format. Refer to OpenTravel Code List Unit of Measure Code | 
|  HotelRef |	N	| Indicates the detail of hotel reference information.|
|  StayDateRange |	Y	| Range of dates, or fixed set of dates for Availability Request.|

OTA_HotelSearchRS

|  Element |	Required	|  Description |
|----------|---------------------------------------|-|
|  ChainCode |	N	| 2 letter GDS chain code. The code that identifies a hotel chain or management group. Used for Chain filter in UI, and for Travel Rules based on GDS codes|
|  ChainName |	N	| Detailed property level information.|
{'fraction_non_alphanumeric': 0.08286935772519388, 'fraction_numerical': 0.03166633525551799, 'mean_word_length': 4.121435845213849, 'pattern_counts': {'":': 0, '<': 47, '<?xml version=': 2, '>': 51, 'https://': 1, 'lorem ipsum': 0, 'www.': 8, 'xml': 22}, 'pii_count': 46, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4621823', 'n_tokens_mistral': 5881, 'n_tokens_neox': 5213, 'n_words': 2650}