Exchanging Data
protel uses protel I/O to route incoming and outbound data messages. Messages can be delivered to protel I/O from an HTTPS endpoint or via a Websocket. protel I/O provides different endpoints for synchronous and asynchronous SOAP 1.2 and JSON messages to accommodate WSDL requirements.
Systems send messages to protel I/O using HTTP endpoints.
In addition, protel I/O requires some information in the message header.
Security, Access, + 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 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.
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
Content-Type: application/soap+xml; charset=utf-8 + SOAPAction: OTA_HotelResNotifRQ
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
Authorization: Bearer C6MmpEFjRRSy288V1hGETMBImNJhFzv5
Or it can be in the SOAP header, like this
<p:Token xmlns:p="http://protel.io/soap">C6MmpEFjRRSy288V1hGETMBImNJhFzv5</p:Token>
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.
SOAPAction: <MethodName>
Note!
You should send a Correlation ID in the HTTP header
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.
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
"http://protel.io/soap"
There is only 1 mandatory SOAPHeader for SYNC communication. Protel prefers to not use sync message patterns, due to scalability concerns.
`p:Target`
Example: Mandatory HTTP headers parameters for Inbound messages
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
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
<soapenv:Header>
<p:Action xmlns:p="http://protel.io/soap">$1 OTA_HotelAvailNotifRS</p:Action>
<p:Token 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
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>
SOAPAction:<MethodName>
protel IO always sends out the CorrelationID, which identifies (uniqueID) the message pair (RQ/RS)
CorrelationID: <ID_for_the_message_pair>
Example of SOAPHeader sent from protel I/O
Additionally protel IO sends out a SOAPHeader with Outbound messages
<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
| System | Endpoint | Variant | URL | Comments |
|---|---|---|---|---|
| ESB | Asynchronous API | SOAP 1.2 | https://api-dev.protel.net/services/ProtelApiService.ProtelApiServiceHttpsSoap12Endpoint | |
| Websocket | ws://172.31.191.140:9090 | |||
| JSON | https://api-dev.protel.net/services/ProtelApiService.ProtelApiServiceHttpsJsonEndpoint | |||
| Synchronous API | SOAP 1.2 | https://api-dev.protel.net/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsSoap12Endpoint | ||
| JSON | https://api-dev.protel.net/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsJsonEndpoint |
Connecting to prod:test
Connecting to prod:prod
| System | Endpoint | Variant | URL | Comments |
|---|---|---|---|---|
| ESB | Asynchronous API | SOAP 1.2 | https://service.protel.io/services/ProtelApiService.ProtelApiServiceHttpsSoap12Endpoint | |
| Websocket | wss://wsesb.protel.io:443 | |||
| JSON | https://wsdl.protel.io/services/ProtelApiService.ProtelApiServiceHttpsJsonEndpoint | |||
| Synchronous API | SOAP 1.2 | https://service.protel.io/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsSoap12Endpoint | ||
| JSON | https://wsdl.protel.io/services/ProtelApiSyncService.ProtelApiSyncServiceHttpsJsonEndpoint |
Format of the Acknowledgment (ASYNC communication)
To communicate with an ASYNC pattern, the receiver of the message needs to send an ACK with the HTTP status code 200 and the following payload back to the sender before the receiver starts the processing of the message.
<?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
Our WSDL can be found here: https://wsdl-test.protel.io/services/ProtelApiService?wsdl