Seitenhistorie

...

protel uses protel I/O to route incoming and outbound data messages. Messages can be delivered to protel I/O from an HTTPS endpoint. protel I/O provides different endpoints for synchronous and asynchronous SOAP 1.2 messages to accommodate WSDL requirements.In addition, protel I/O requires some information in the message header.

Security, Access,

+

and Authentication

Security is important to you and protel. All messages must be authenticated using protel IO’s secure authentication processes. To ensure the source of messages are valid, all messages flowing to and from protel are checked. Messages are verified by protel I/O

Who can send messages
What messages they can send
Where they can send to and receive from

. Access to the API is only permitted through SSL (secure sockets layer). For HTNG messaging, all messages will utilize the HTNG 2.1 SOAP header.

Authentication of Inbound messages

Direction Vendor to protel. All messages require a protel provided Bearer Token (whether RQ or RS!).

The Authentication token can must be submitted in HTTP headers and SOAP headers. If the token can be found in more than one of these places, the SOAP header has the higher priority than the HTTP header. The place with the highest priority that has the token set determines which is used and which is ignored.

Protel will provide you with your bearer token at the time we commence testing. When requesting a test environment protel will provide you with a token at that time.

protel Access Token

For API access, each service connecting to a hotel will have it’s own access token.

Codeblock

language	xml
title	Bearer Token

Authorization: Bearer <HOTEL_TOKEN>

Authentication is specific in each case and requires partner applications to provide this access token with each API request message. This access token is provided by protel. protel authenticates this access token before allowing any actions to be taken

.

Format of Headers

You must send HTTP headers. There are 2 mandatory HTTP header parameters

Format of HTTP Headers

In order to process your incoming requests, all of your messages must contain headers inside the HTTP headers

HTTP Header	Description	Occurrence
Content-Type	Fixed to "application/soap+xml"	Mandatory
SOAPAction	The type of messages you are sending e.g. "OTA_HotelResNotifRQ"	Mandatory
Authorization	The access token e.g. "Bearer C6MmpEFjRRSy288V1-DEMO-hGETMBImNJhFzv5"	Mandatory
CorrelationID	The CorrelationID of the message you are sending to identify the transaction	Optional

Codeblock

language	xml
title	Header Format

Content-Type: application/soap+xml
SOAPAction: OTA_HotelResNotifRQ
Authorization: Bearer C6MmpEFjRRSy288V1-DEMO-hGETMBImNJhFzv5

The Authorization (Bearer) token is generated for your service when installed and sent to you using a secure method. It can be either in the HTTP header or in the SOAP Header

Authorization is not mandatory in the HTTP header. However it is preferred. It should be like this in the HTTP header

Codeblock

language	xml
title	Bearer token

Authorization: Bearer C6MmpEFjRRSy288V1hGETMBImNJhFzv5

Or it can be in the SOAP header, like this

...

language	xml
title	Token In the SOAP header

...

Format of SOAP Environment

In order to process your incoming requests, all of your messages must contain headers inside the SOAP environment

Info

title	Note!

We do not support the Action parameter in the HTTP header but we rely upon the official message name OTA/HTNG*RQ/RS sent in the HTTP Header as the SOAPAction parmeter.

Codeblock

language	xml
title	SOAPAction

SOAPAction: <MethodName>

Info

title	Note!

You should send a Correlation ID in the HTTP header

Codeblock

language	xml
title	Correlation ID

CorrelationID: <ID_for_the_message_exchange>

We use the HTTP Headers as a location for these parameters, to keep it easy and have the important information at hand before even reading the xml document.

Info

title	Note!

There is no mandatory SOAPHeader for ASYNC communication - if you dont provide a CorrelationID - then protel I/O will generate it for you.

If header information is sent using the SOAP header, the elements have to use the XML namespace

...

language	xml
title	XML Namespace

...

Element	Namespace	Description	Occurrence
Envelope	http://www.w3.org/2003/05/soap-envelope	-	Mandatory
Envelope / Header	http://www.w3.org/2003/05/soap-envelope	Contains the SOAP headers of the message	Mandatory
Envelope / Header / Action	http://protel.io/soap

...

	The required action (Message name) e.g. "OTA_HotelResNotifRQ"	Optional
Envelope / Header / CorrelationID	http://protel.io/soap	The CorrelationID of the message you are sending to identify the transaction (protel namespace)	Mandatory
Envelope / Header / Source	http://protel.io/soap	The Source of the message (Only outbound from protel to vendor)	Optional
Envelope / Header / CorrelationID	http://htng.org/PWSWG/2007/02/AsyncHeaders	The CorrelationID of the message you are sending to identify the transaction (HTNG namespace)	Mandatory
Envelope / Header / Target

http://protel.io/soap

...

	The desired target service name of the message - ONLY for SYNC messages	Optional
Envelope / Body	http://www.w3.org/2003/05/soap-envelope	The HTNG/OTA/IO message	Mandatory

There is only 1 mandatory SOAPHeader for SYNC communication. Protel prefers to not use sync message patterns, due to scalability concerns.

Codeblock

language	xml
title	Target

`p:Target`

...

Codeblock

language	xml
title	Mandatory HTTP Header parameters

HTTP Header: Accept: application/soap+xml, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
HTTP Header: Content-Type: application/soap+xml
HTTP Header: SOAPAction: OTA_HotelAvailNotifRS
HTTP Header: Authorization: Bearer C6MmpEFjRRSy288V1hGETMBImNJhFzv5

Optional SOAP headers

SOAP Env

<?xml version='1.0' encoding='utf-8'?>
<env:Envelope xmlns:env

Codeblock

language	xml
title	Optional Soap Headers

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
    <soapenv	<env:Header>
        		<p:Action xmlns:p="http://protel.io/soap">$1 OTA>OTA_HotelAvailNotifRS<HotelResNotifRQ</p:Action>
        		<p:TokenCorrelationID xmlns:p="http://protel.io/soap">$2 C6MmpEFjRRSy288V1hGETMBImNJhFzv5<p:Token>
    </soapenv:Header>
        ...
</soapenv:Envelope>

Official message name sent as webservice (SOAPAction)
Token generated for this service installation in for particular hotel/customer by protel

Info

title	Note:

Username and Password are not used for incoming messages to protel. The protel supplied Bearer Token is used for authentication. The Callback URL of receiving system’s endpoint is known from the service installation

Authentication for Outbound messages

Vendor Systems can receive messages using HTTP endpoints that are configured in protel’s Module manifests or they can receive them via Websockets
Messages must be sent via HTTPS

For messages outgoing to the vendor we send the official message name in the HTTP Header as e.g. SOAPAction:<OTA_HotelResNotifRQ>

Codeblock

language	xml
title	SOAPAction

SOAPAction:<MethodName>

protel IO always sends out the CorrelationID, which identifies (uniqueID) the message pair (RQ/RS)

Codeblock

language	xml
title	Correlation ID

CorrelationID: <ID_for_the_message_pair>

>RES#047616#UPDATE#000025#1594029290242#546D</p:CorrelationID>
		<p:Source xmlns:p="http://protel.io/soap" Module="backline" ModuleVersion="2020-07-02T10:28:55 (PROD)" Product="protelAir" ProductVersion="2027.1.56845-RELEASE" Service="io.protel.air"/>
		<htnga:CorrelationID xmlns:htnga="http://htng.org/PWSWG/2007/02/AsyncHeaders">RES#047616#UPDATE#000025#1594029290242#546D</htnga:CorrelationID>
		<p:Target xmlns:p="http://protel.io/soap">io.protel.air</p:Target>
	</env:Header>
	<env:Body>
		--OTA/IO/HTNG Message--
	</env:Body>
</env:Envelope>

Example of SOAPHeader sent from protel I/O

Additionally protel IO sends out a SOAPHeader with Outbound messages

Codeblock

language	xml
title	Example Soap Header

<soapenv:Header>
    <wsa:MessageID>$1</wsa:MessageID>
    <htng:CorrelationID>$2</htng:CorrelationID>
    <wsa:Action>$3</wsa:Action>
    <wsa:To>$4</wsa:To>
    <wsa:ReplyTo>
        <wsa:Address>http://www.w3.org/2005/08/addressing/role/anonymous</wsa:Address>
    </wsa:ReplyTo>
    <wsse:Security mustUnderstand="1">
        <wsse:UsernameToken>
            <wsse:Username>$5</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">$6</wsse:Password>
        </wsse:UsernameToken>
    </wsse:Security>
    <htng:ReplyTo>
        <wsa:Address>$7</wsa:Address>
    </htng:ReplyTo>
</soapenv:Header>

$1 - ID generated for this particular message

$2 - ID generated for this particular message exchange (at least for RQ, ACK and RS)

$3 - Official message name sent as webservice Action

$4 - URL of receiving system’s endpoint

$5 - Username if authentication is done using this schema

$6 - Password if authentication is done using this schema

$7 - URL of receiving system’s endpoint

Testing Connectivity with a Dummy API

To test the SOAP Function, systems can call
https://api-dev.protel.net/services/SoapDummyService.SoapDummyServiceHttpsSoap11Endpoint,
which returns a static OTA_HTNG Body.

Websocket Support

To connect the websocket, the client has to authenticate itself using the correct hotel token.
Once authenticated the client will receive incoming RQ messages for the hotel the token was issued for.
The websocket client also receives incoming RS messages on the same websocket connection, it has used to sent a RQ message before.

protel I/O Connection Endpoints

Connecting to dev:test

...

https://api-dev.protel.net/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsJsonEndpoint

...

Connecting to prod:test

...

not in use

Connecting to prod:prod

...

https://service.protel.io/services/ProtelApiService.ProtelApiServiceHttpsSoap12Endpoint

...

https://service.protel.io/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsSoap12Endpoint

...

Format of the Acknowledgment (ASYNC communication)

...

Codeblock

language	xml
title	Example ACK

<?xml version='1.0' encoding='UTF-8'?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
	<env:Header>
		<htnga:CorrelationID xmlns:htnga="http://htng.org/PWSWG/2007/02/AsyncHeaders">RES#045627#CREATE#000002#1575294717780#6244XXX</htnga:CorrelationID>
		<htnga:RelatesToCorrelationID xmlns:htnga="http://htng.org/PWSWG/2007/02/AsyncHeaders">RES#045627#CREATE#000002#1575294717780#6244XXX</htnga:RelatesToCorrelationID>
	</env:Header>
	<env:Body>
		<ns:HTNG_AcknowledgeReceipt xmlns:ns="http://htng.org/2014B"/>
	</env:Body>
</env:Envelope>

WSDL

...

Image Added

protel I/O Connection Endpoints

Connecting to TEST

System	Endpoint	Variant	URL	Comments
ESB	Asynchronous API	SOAP 1.2	https://service-test.protel.io/services/ProtelApiService.ProtelApiServiceHttpsSoap12Endpoint	Default Endpoint
	Synchronous API	SOAP 1.2	https://service-test.protel.io/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsSoap12Endpoint
	Asynchronous API (CD-Proxy)	SOAP 1.2	https://qa-pci.protel.net/cd-proxy-io/pci/1/io/reservations	Endpoint for all inbound OTA_HotelResNotifRQ messages
	WSDL	SOAP 1.2	https://wsdl-test.protel.io/services/ProtelApiService?wsdl

Connecting to PROD

System	Endpoint	Variant	URL	Comments
ESB	Asynchronous API	SOAP 1.2	https://service.protel.io/services/ProtelApiService.ProtelApiServiceHttpsSoap12Endpoint	Default Endpoint
	Synchronous API	SOAP 1.2	https://service.protel.io/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsSoap12Endpoint
	Asynchronous API (CD-Proxy)	SOAP 1.2	https://pci.protel.net/cd-proxy-io/pci/1/io/reservations	Endpoint for all inbound OTA_HotelResNotifRQ messages
	WSDL	SOAP 1.2	https://wsdl.protel.io/services/ProtelApiService?wsdl

NAT Gateway IP Addresses

Environment	NAT Gateway - Out
ESB TEST	34.249.236.99
ESB PROD	34.248.234.12

Seitenhierarchie

Versionen im Vergleich

Alte Version 9

Neue Version 10

Schlüssel

Security, Access,

and Authentication

Authentication of Inbound messages

protel Access Token

Format of Headers

Format of HTTP Headers

Format of SOAP Environment

Optional SOAP headers

Authentication for Outbound messages

Example of SOAPHeader sent from protel I/O

Testing Connectivity with a Dummy API

Websocket Support

protel I/O Connection Endpoints

Connecting to dev:test

Connecting to prod:test

Connecting to prod:prod

Format of the Acknowledgment (ASYNC communication)

WSDL

protel I/O Connection Endpoints