Seaware OTA Basics
General Message Format
All conversations with Seaware through Seaware OTA (SwOTA) API are done in form of XML messages: requests and responses. Each message must be a well-formed XML document.
Generally each SwOTA API request should look like:
<OTA_NameRQ>
<POS>
<Source>
… Message header elements
</Source>
</POS>
… Request options and parameters
</OTA_NameRQ>
General SwOTA API response looks like this:
Success:
<OTA_NameRS>
<Success/>
… Response data
</OTA_NameRS>
Failure:
<OTA_NameRS>
<Errors>
<Error>… Error message <Error>
</Errors>
</OTA_NameRS>
XML document header (like <?xml version="1.0" encoding="UTF-8" standalone="no"?>) is not mandatory though can be specified. XML comments are allowed. Special characters (like <>) should be escaped according to XML specification.
SwOTA API messages are defined in the schema files prefixed by OTA_Cruise (for example OTA_CruiseBookRQ.xsd). Other schemas usually define some common types and referenced from OTA_Cruise* schemas. Set of root elements defined by OTA_Cruise* schemas can be divided into two categories: requests and responses. The following naming convention is used: <Name>RQ for requests and <Name>RS for responses.
Transport Protocols: SOAP vs REST
The message formats shown above are the core OTA messages. SwOTA supports two transport protocols for sending these messages:
SOAP (Web Services)
With SOAP, the OTA message is wrapped in a SOAP envelope:
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header/>
<Body>
<OTA_NameRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0">
<POS>...</POS>
<!-- message content -->
</OTA_NameRQ>
</Body>
</Envelope>
SOAP Endpoint: https://bookings.travelhx.com:8082/ota/ws
Headers:
Content-Type: text/xml; charset=utf-8SOAPAction:(empty but required)
REST (Plain XML)
With REST, you send the OTA message directly without envelope wrapping:
<OTA_NameRQ xmlns="http://www.opentravel.org/OTA/2003/05" Version="1.0">
<POS>...</POS>
<!-- message content -->
</OTA_NameRQ>
REST Endpoint: https://bookings.travelhx.com:8082/ota/rest/<MessageName>
Example: https://bookings.travelhx.com:8082/ota/rest/OTA_PingRQ
Headers:
Content-Type: application/xml; charset=utf-8
Protocol Comparison
| Aspect | SOAP | REST |
|---|---|---|
| Endpoint | Single endpoint for all operations | Unique endpoint per operation |
| Request Wrapper | SOAP Envelope/Body required | Direct OTA message |
| Response Wrapper | SOAP Envelope/Body included | Direct OTA response |
| Headers | Requires SOAPAction | Only Content-Type needed |
| Certificates | SSL client cert required | SSL client cert required |
For detailed testing guides, see:
Data Types
SwOTA API supports all built-in XML types as well as defines many custom data types. All of them are specified in OTA_CommonTypes.xsd file and other not OTA_Cruise* schemas.
Enumerations and Code Lists
XML message exchanges commonly require the ability to restrict a field to a limited set of values. Business requirements may control this, but it is also typically preferred to limit the allowable values for an element or attribute to as few as possible to facilitate validation of values. To support this need, the OpenTravel specification uses XML enumerations and code lists, which are described below.
Enumerations are used when the list of values is static or when it is unlikely that values will be added. For example:
- Days of the week. The seven days of the week are static, and not expected to change.
- Gender. The two human genders (male and female) are fixed.
Code Lists. SwOTA API messages contains special code values. Most of them refer to code lists maintained by OpenTravel code table spreadsheet. See OTA Code Lists page for more details.
State Maintenance
Being based on the OpenTravel specification and originally targeted towards GDS client application types, the Versonix OTA supports transactions that occur within a stateless environment. Within the messages, this is reflected by a tendency to include data in the response that was defined in the request. With this design, message senders and recipients are not forced to "remember" data between message sends.
In addition to stateless environment, Versonix OTA supports stateful (live booking state) flow and sessionful (live user session) flow. Details on those can be found in the Session and State Support section.
Multilingual Support
SwOta usually pass language indicator in the message or it is can be determined by context (ex: by language defined for agency). So some fields in response message can be translated in accordance with language defined in message in case when Seaware has appropriate setup.
Error Handling and Success Indicator
Error messages are provided by SwOta in form of <Errors> element in response. Warning and information messages are provided in <Warnings> element. An empty <Success/> element in the response message indicates that the request has been successfully processed.
<vx:Errors>
<vx:Error Code="168" ShortText="Agent not recognised" Tag="POS/Source" Type="4">PseudoCityCode: KK17</vx:Error>
</vx:Errors>
If the SwOta application receives a request message that is not a valid XML the web service will return an HTTP response with status 400 Bad Request.
If the SwOta application receives a request messages that is not a valid Versonix OTA message (compliant to the XSD specification) then web service will return response like this:
<vx:Errors>
<vx:Error Code="320" Tag="CruiseDocument/@DeliveryMethodCode" Type="3">Invalid value</vx:Error>
</vx:Errors>
OTA/GDS Fare Code vs Seaware Promotion Code
OTA API (as most GDS APIs) has a slightly different design compared to Seaware in regards to promotions or price programs.
Promotion Code. Seaware uses promotion codes that can be applied to a booking. Multiple codes can be applied to the same booking. Eligibility rules govern if the code is applicable. Promotion can be applied to the booking at any step - before or after looking for and assigning a specific sail, category etc. As a general rule, if a promotion code has been requested for the booking but could not be applied, Seaware will not halt the booking process or produce a blocking error.
Fare Code. GDS systems and OTA API use fare code under which the booking can be made. Only single fare code can be applied to a booking. Often fare code must be selected before choosing a category or cabin. If a code has been requested but could not be applied that would usually result in a blocking error.
OTA fare code values are backed by Seaware promotion codes, but because of the described above conceptual differences between Seaware promotion and OTA Fare Code there is a certain list of limitations or differences in how they can be applied, compared to Seaware itself (SwMain or SwTouch or other API or UI). In order to bridge this difference a special (channel-specific) setting (SwOtaFareCodeModeEnabled) has been introduced that switches the SwOTA service between two modes:
- Fare Code Mode: SwOTA works as GDS system would usually expect it, with a single (or single per guest) Fare Code (Promotion) applicable. This means user cannot apply more than one, and if Seaware auto-applies other promotions they will not be reflected in the OTA messages.
- Promotions Mode (aka "Fare Code Mode OFF"): Several codes can be applied to each guest on the booking, and all promotions will be visible when retrieving a booking.
Additionally, in Seaware OTA there is a "hard-coded" (configurable) fare code "BESTPRICE" that is not mapped to any Seaware promotion, but simply means a request to Seaware to use its best price mechanism. Not sending any FareCode at all into OTA request would also mean the booking is being made using the Seaware best price mechanism.
The list of available fare codes (Seaware promotion codes) can be retrieved by OTA_CruiseFareAvailRQ.
Note
FareCode value in OTA can be provided on per-booking (per-cabin) or per-guest level (using SelectedSailing/SelectedCategory or GuestDetail/SelectedFareCode elements in the OTA_CruiseBookRQ). That makes sense only in Fare Code Mode. In Promotion Mode the promotions are to be applied per guest.