¶ OTA Integration Process
The best way to understand the Webservice work flow process is through a graphical example, therefore, we have created a diagram that oulines and simplifies the steps to follow through the booking process. We will refer to this diagram as we advance further on in our explanation.
As you may have observed, this booking process is divided in four differentiated steps. We will proceed to describe each of these steps in detail:
Before searching for availability on the system, you should know before hand a series of information that is required to obtain availability. In the availability process you may specify various filters such as areas, hotels, board types, etc. All this information is obtined from the Static Data transactions.
To carry our these mappings, our API allows for the following transactions:
- JP_CatalogueData: For the retrieval of general static data information
- JP_RoomTypeList: For the retrieval of room type information (only available for directly contracted hotels).
- JP_ZoneList: For the retrieval of all of the available destinations.
- JP_HotelList: For the retrieval of all of the available hotels within all of the available destinations.
- OTA_HotelDescriptiveInfo: For the retrieval of all of the available hotel information.
For further information, kindly refer to the OTA Static Data Transactions section.
The availability process is the first step to create a new booking. You may narrow your availability request through various parameters, all of which are explained on OTA_HotelAvail section. There are multiple ways on which you could request for availability and, the most common ones, are:
- Destination code. Retrieve all of the available results from a specific destination.
- Hotel code (either a single or multiple ones). Retrieve all of the available results from a specific list of hotels.
According to the indicated parameter the system will return information of all found availability. Each hotel will have a group combinations. A combination is a group of rooms that will depend on the numer of requested rooms in the overall request.
Once the availability has been obtained we will continue with the booking process through a unique code that will identify the combination we wish to book, for which we will have to identify such combination with the RatePlanCode attribute. It is important to understand that the whole booking process starts on from the RatePlanCode, which will be the code you should send in the following transactions.
At this point, after searching for availability, we have decided a combination and through the RatePlanCode we validate the information obtained in the availability response to ensure that it is correct, since with this step, with the passage of time, something may have altered the result of the OTA_HotelAvail; a room has run out of allotment, or simple the prices have changed, ...
For this reason, the function that allows us to validate the information is the OTA_HotelBookingRule one.
Before making a booking it is necessary to send a OTA_HotelBookingRule. It receives the RatePlanCode which will be validated and it will check once more if the availability of the room has changed, or if for whatever reason, the prices have been modified. If the initial availability has changed, the system, it will advice us about it and it will also update the RatePlanCode. In case it has changed, you need to take this new RatePlanCode and set it in the rest of transactions of the booking process.
This procedure will also return the cancellation policies. It is important to review them in order to know if the possible costs that the cancellation charges that the bookings will entail if cancelled.
Additionally, it is possible to obtain detailed information of the hotel through the RatePlanCode by using the transaction OTA_HotelDescriptiveInfo. In case you request for the extended hotel information during the booking process, it is mandatory you set the RatePlanCode in the OTA_HotelDescriptiveInfo request.
Once you have received the response of the OTA_HotelRes transaction of the preferred combinaion we will proceed to make a Booking Code (locator) that will identify the booking in a unique way. A reference code will consist of various elements or booking elements and in this case it will always have a unique booking element even if the booked combination has various rooms.
Moving on, once the booking has been created, successfully confirmed and you've been able to retrieve its locator, there are two additional actions that you may take in this regard:
- OTA_Read: This transaction will let you, through the use of a specific booking code (locator), to retrieve all of the information related to the requested booking. Kindly refer to the OTA_Read section for more information.
- OTA_Cancel: This transaction will let you, through the use of a specific booking code (locator), to cancel the requested booking (by simply indicating the mentioned locator). Kindly refer to the OTA_Cancel section for more information.
¶ OTA Endpoint
Following the Getting Started section found on the home page, we would like to add an example of the OTA test environment endpoint for your reference:
https://xml-uat.bookingengine.es/WebService/OTA_HotelAvail.asmx
And on which it is very important to note that each transaction will have its own independent endpoint, you will be able to find the name of the transaction that you will need to request for on the specifications of each transaction. Kindly refer to a few examples in this regard:
https://xml-uat.bookingengine.es/WebService/JP_ZoneList.asmx
https://xml-uat.bookingengine.es/WebService/OTA_HotelAvail.asmx
https://xml-uat.bookingengine.es/WebService/OTA_HotelBookingRule.asmx
https://xml-uat.bookingengine.es/WebService/OTA_HotelRes.asmx
Important note:
Being xml-uat.bookingengine.es the endpoint of the test environment and the part that you would have to replace if you wished to connect to a different environment. This is very important to keep in mind for when you connect to the live environment and/or if you plan on connecting with multiple Juniper clients.
¶ OTA Static Data Transactions
Important note:
The maximum allowed frequency for the retrieval of static data information (if you plan on retrieving such information) is at least once every 15 days. This a requirement meant to keep the static data information from our system updated.
¶ JP_CatalogueData
Request: JP_CatalogueDataRq
Response: JP_CatalogueDataRs
Development URL: JP_CatalogueData.asmx
SOAPAction for SOAP 1.1: "http://www.juniper.es/webservice/2007/GetCatalogueService"
This is not an OTA standard message. With this messsage, you can retrieve the available static data (room category, acommodation cateory, mealplan codes, etc).
The static data is used to categorize the information returned in the OTA_HotelAvail response.
Please take into account that the static data can be empty. This means that all accommodation information is retreived dynamically from external providers and can't be categorized.
If the catalogue data is available, some results from the availability response can be returned categorized, but others can be returned without a category code (because they come from a gynamic supplier). It is very important to take into consideration when implementing the connection with Juniper Webservice.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.juniper.es/webservice/2007/">
<soap:Body>
<GetCatalogueService xmlns="http://www.juniper.es/webservice/2007/">
<CatalogueDataRQ Language="en">
<Login Email="username@mydomain.com" Password="pass"/>
<Data>
<DataTypes Type="RoomCategory" />
<DataTypes Type="Mealplan" />
<DataTypes Type="AccommodationType" />
<DataTypes Type="AccommodationCategory" />
<DataTypes Type="OfferSupplementType" />
<DataTypes Type="AccommodationService" />
</Data>
</CatalogueDataRQ>
</GetCatalogueService>
</soap:Body>
</soap:Envelope>
You can ask for one or more data types. In this example all available are retrieved:
- RoomCategory: This data type retrieves the list of available room categories.
- MealPlan: This data type retrieves the list of available mealplans.
- AcommodationType: This data type retrieves the list of available accommodation types.
- AccommodationCategory: This data type retrieves the list of available accommodation categories.
- OfferSupplementType: This data type retrieves the list of available offers and supplements.
- AccommodationService: This data type retrieves the list of available services.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetCatalogueServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<CatalogueDataRS>
<Results>
<Result Type="RoomCategory">
<Elements>
<Element Id="1" Code="ASV">APARTMENT SEA VIEW</Element>
<Element Id="2" Code="DST">STANDARD DOUBLE ROOM</Element>
<Element Id="3" Code="DSV">DOUBLE ROOM SEA VIEW</Element>
<Element Id="4" Code="DLV">DOUBLE LATERAL VIEW</Element>
<Element Id="5" Code="FAM">FAMILIAR ROOM</Element>
<Element Id="6" Code="DSG">DOUBLE SINGLE USE</Element>
<Element Id="7" Code="DGV">DOUBLE GARDEN VIEW</Element>
<Element Id="8" Code="TRP">TRIPLE ROOM</Element>
<Element Id="9" Code="SUI">SUITE</Element>
<Element Id="10" Code="SUP">SUPERIOR DOUBLE ROOM</Element>
<Element Id="11" Code="A2R">TWO ROOMS APARTMENT</Element>
<Element Id="12" Code="VLL">VILLAGE</Element>
<Element Id="13" Code="SGL">SINGLE ROOM</Element>
<Element Id="14" Code="QUA">QUADRUPLE ROOM</Element>
<Element Id="15" Code="SGS">SINGLE ROOM SUPERIOR</Element>
<Element Id="16" Code="JRS">JUNIOR SUITE</Element>
<Element Id="17" Code="A1R">ONE ROOM APARTMENT</Element>
</Elements>
</Result>
<Result Type="Mealplan">
<Elements>
<Element Id="5" Code="AI" Category="TI">All Inclusive</Element>
<Element Id="2" Code="BD" Category="AD">Bed & Breakfast</Element>
<Element Id="4" Code="FB" Category="PC">Full Board</Element>
<Element Id="1" Code="HB" Category="MP">Half Board</Element>
<Element Id="3" Code="HBD" Category="MP">Half Board + Drinks</Element>
<Element Id="6" Code="RO" Category="SA">Room Only</Element>
</Elements>
</Result>
<Result Type="AccommodationType">
<Elements>
<Element Id="1" Code="HOT">Hotel</Element>
<Element Id="3" Code="VIL">Villa</Element>
<Element Id="2" Code="APT">Apartment</Element>
</Elements>
</Result>
<Result Type="AccommodationCategory">
<Elements>
<Element Id="1" Code="1">*</Element>
<Element Id="2" Code="2">**</Element>
<Element Id="3" Code="3">***</Element>
<Element Id="4" Code="4">****</Element>
<Element Id="5" Code="5">*****</Element>
<Element Id="6" Code="1K">1 KEY</Element>
<Element Id="7" Code="2K">2 KEYS</Element>
<Element Id="8" Code="3K">3 KEYS</Element>
<Element Id="9" Code="4K">4 KEYS</Element>
</Elements>
</Result>
<Result Type="OfferSupplementType">
<Elements>
<Element Id="1" Code="BAS">Basic supplement</Element>
<Element Id="2" Code="CID">Check-In Day</Element>
<Element Id="3" Code="LSD">Long Stay Discount</Element>
<Element Id="4" Code="EBO">Early Booking</Element>
<Element Id="5" Code="HFF">Handling Fee</Element>
<Element Id="6" Code="MSY">Minimum Stay</Element>
<Element Id="7" Code="FNG">Free nights</Element>
<Element Id="8" Code="BDC">Basic discount</Element>
<Element Id="9" Code="SSS">Short Stay Supplement</Element>
<Element Id="10" Code="NRR">Non-Refundable Rate</Element>
<Element Id="11" Code="SUS">Single Use Supplement</Element>
</Elements>
</Result>
</Results>
</CatalogueDataRS>
</GetCatalogueServiceResponse>
</soap:Body>
</soap:Envelope>
Each element will have an internal numeric ID and a public unique code (unique in its category; there won't be two room categories with the same code, but there could be one room category with the same code of an accommodation type, for example).
¶ JP_RoomTypeList
Request: JP_RoomTypeListRq
Response: JP_RoomTypeListRs
Development URL: JP_RoomTypeList.asmx
SOAPAction for SOAP 1.1: "http://www.juniper.es/webservice/2007/JP_RoomTypeListService"
This is not an OTA standard message.
With this message, you can retrieve the available staticdata of room types.
The static data is used to categorize the information of room returned in the OTA_HotelAvail response.
Some results from the availability response can be returned categorized, but others can be returned without a room type code (because the come from a dynamic supplier).
It is very important to take this into consideration when implementing the connection with Juniper Webservice.
This petition allows you to get all the room types codes.
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JP_RoomTypeListService>
<JP_RoomTypeListRQ PrimaryLangID="es">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID ID_Context="1" MessagePassword="pass" />
</Source>
</POS>
</JP_RoomTypeListRQ>
</JP_RoomTypeListService>
</soap:Body>
</soap:Envelope>
The response will contain only the room tyoe codes and the name of the room type.
This name is a description generic of the room type. If you want obtain the list of rooms of a hotel, you must use the OTA_HotelDescriptiveInfo request.
Click to see the example
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JP_RoomTypeListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_RoomTypeListRS>
<RoomType Code="2" Name="1 ad (1/1A+0/0N)" />
<RoomType Code="232" Name="SNGL ROOM PV (1/1A+0/0N)" />
<RoomType Code="206" Name="DBL ROOM (2/2A+0/0N)" />
<RoomType Code="257" Name="Double (2/2A+0/1N)" />
<RoomType Code="221" Name="1-3/2+2 (1/3A+0/2N)" />
<RoomType Code="237" Name="FAMILY ROOM PV (4/5A+0/1N)" />
</JP_RoomTypeListRS>
</JP_RoomTypeListServiceResponse>
</soap:Body>
</soap:Envelope>
¶ JP_ZoneList
Request: JP_ZoneListRq
Response: JP_ZoneListRs
Development URL: JP_ZoneList.asmx
SOAPAction for SOAP 1.1: "http://www.juniper.es/webservice/2007/JP_ZoneListService"
This is not an OTA standard message.
With this message, all available zone codes are returned. The returned zones have a tree structure, hence, each zone ontains the parent from the previous one.
In this request, only the authentication information is mandatory. The zone codes are used in the availability request (OTA_HotelAvail) and hotels per zone request (JP_HotelList). You must cache these zones in a data base, and update them weekly.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_ZoneListService xmlns="http://www.juniper.es/webservice/2007/">
<JP_ZoneListRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<TPA_Extensions>
<ShowHotels>1</ShowHotels>
</TPA_Extensions>
</JP_ZoneListRQ>
</JP_ZoneListService>
</soap:Body>
</soap:Envelope>
The ShowHotels option allows you to activate the Hotels attribute in the response.
The MaxLevel option allows you to only obtain zones with a level equal or lower to the supplied value will be returned. For example, if a valueof 1 is supplied, only zones which correspond to countries will be returned.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_ZoneListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_ZoneListRS>
<Zone Code="118" JPDCode="JPD034804" Name="Spain" Parent="" IATA="ES" Hotels="false" Searchable="false" />
<Zone Code="5127" JPDCode="JPD040191" Name="Balearic Islands" Parent="118" Hotels="true" Searchable="true" />
<Zone Code="851" JPDCode="JPD035556" Name="Ibiza (Island)" Parent="5127" IATA="IBZ" Hotels="true" Searchable="true" />
<Zone Code="1953" JPDCode="JPD036705" Name="Majorca" Parent="5127" Hotels="true" Searchable="true" />
<Zone Code="15011" JPDCode="JPD054557" Name="Palma De Mallorca" Parent="1953" IATA="PMI" Hotels="true" Searchable="true" />
<Zone Code="6169" JPDCode="JPD041327" Name="Eastern Area" Parent="1953" Hotels="true" Searchable="true" />
<Zone Code="2459" JPDCode="JPD037347" Name="Manacor" Parent="6169" IATA="MNAC" Hotels="true" Searchable="true" />
</JP_ZoneListRS>
</JP_ZoneListServiceResponse>
</soap:Body>
</soap:Envelope>
The JPDCode property serves as a zone identificator between all Juniper clients. JPDCodes can be represented in two ways:
- JPDXXXXXX: This code implies that this is a sharedzone and serves as an identifier on all Juniper clients.
- CUDXXXXXX: This code implies that this is a zone created by your supplier and will not be shared between Juniper clients.
NOTE:
This value can also be used on availbilities (OTA_HotelAvail) as a zone code.
The Hotels attribute in the response indicates if you can search in that zone for hotels (JP_HotelList).
The Searchable attribute in the response indicates if you can search in that zone for availability (OTA_HotelAvail).
NOTE:
Keep in mind that some countries may also have theSearchable attribute available, in these cases it is not advised to search availability (OTA_HotelAvail) on these zones and instead use lower level zones.
The Type attribute returns the type of the zone and may have the following values:
| ALO | Accommodation. |
| OTR | Other. |
| ARP | Airport. |
| BAR | Neighborhood. |
| COL | Colony. |
| CTY | City. |
| EST | Train station. |
| LOC | Locality. |
| PAS | Country. |
| PRT | Port. |
| PTI | Point of interest. |
| REG | Region. |
| SKI | Ski station. |
| TUR | Touristic zone. |
This extra information regarding types of zone is only available for certain Juniper clients. For more information, please contact Juniper Team.
¶ JP_HotelList
Request: JP_HotelListRq
Response: JP_HotelListRs
Development URL: JP_HotelList.asmx
SOAPAction for SOAP 1.1: "http://www.juniper.es/webservice/2007/JP_HotelListService"
Important note:
Given that the JP_HotelList request is very inefficient on Juniper suppliers that have a considerable portfolio of hotels available, being it even possible for the process to take hours, it is, instead, strongly recommended for you to retrieve this information through the use of the HotelPortfolio request from the JP API, as this request will let you retrieve the same exact information in a much more efficient way, usually in a matter of minutes. In some scenarios, the Juniper supplier may even disallow the use of the JP_HotelList request and, instead, require their customers to retrieve their portfolio by using the HotelPortfolio request.
If you are interested on developing this transaction, kindly refer to the following API specs on which you will be able to find all of the neccesary information in this regard:
It is also worth noting that although you will have access to use this transaction even while developing the OTA API (if case that you do not, contact with the Juniper team), you will not have access to any other transaction from within the JP API.
This is not an OTA standard message.
This petition allows you to get all the hotel codes in a specific zone. Using it combined with the OTA_HoteldDescriptiveInfo request, you can download the hotel data per zone.
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JP_HotelListService xmlns="http://www.juniper.es/webservice/2007/">
<JP_HotelListRQ PrimaryLangID="string">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<Zone>5</Zone>
<TPA_Extensions>
<OnlyDirectZone>1</OnlyDirectZone>
</TPA_Extensions>
</JP_HotelListRQ>
</JP_HotelListService>
</soap:Body>
</soap:Envelope>
The Zone node indicates the zone coe where you want to search hotels. It is mandatory; the value can be retrieved from JP_ZoneList.
The FromDate node, if specified, indicates the update date from which you will start to search hotels. It is optional; the value must be a date in format yyyy-mm-dd.
The response will only contain the accommodation codes of the zone you've searched for (and the HotelName if you include the option ShowBasicInfo) including also the hotels that belong to its child zones. For more information (hotel name, description, location, images, etc) you must use the OTA_HotelDescriptiveInfo request (remember you can ask for more than one accommodation at the same time using this petition).
Additionally, depending on the configurationof your Juniper supplier, it may also contain the HasSynonyms property which identifies if the JPCode has symonyms and, consequently, if it is a master JPCode.
If you have any additional doubt in this regard, then please do not hesitate to contact with Juniper Support Team.
Click to see the example
<soap:Envelope xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema" xmlns:soap = "http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<JP_HotelListServiceResponse xmlns = "http://www.juniper.es/webservice/2007/">
<JP_HotelListRS>
<Hotel Code="JP254206" HasSynonyms="false"/>
<Hotel Code="JP123783" HasSynonyms="false"/>
</JP_HotelListRS>
</JP_HotelListServiceResponse>
</soap:Body>
</soap:Envelope>
This petition also has the OnlyDirectZone optio that allows you to only obtain the hotels that are directly related to the zone you're searching for excluding all the hotels that belong to its child zones.
¶ OTA_HotelDescriptiveInfo
Request: OTA_HotelDescriptiveInfoRq
Reponse: OTA_HotelDescriptiveInfoRs
Development URL: Request: OTA_HotelDescriptiveInfo.asmx
SOAPAction for SOAP 1.1: http://www.opentravel.org/OTA/2003/05/OTA_HotelDescriptiveInfoService
This transaction allows for the retrieval of hotel detailed information through the use of hotel codes that you should have previously retrieved through the use of the JP_HotelList request. This transaction allows for up 50 hotels to be requested at once.
Alternatively, you may also send this transaction along the RatePlanCode from any of the booking flow responses (OTA_HotelAvail or OTA_HotelBookingRule).This should always be the case whenever this transaction is requested in the middle of the booking flow.
In this example, we are requesting one valid hotel (BzVqeJQ79HKBCSNRDwRzQA==) and one incorrect hotel code (JPxxxx) that will raise an error.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelDescriptiveInfoService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelDescriptiveInfoRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo HotelCode="BzVqeJQ79HKBCSNRDwRzQA==" />
<HotelDescriptiveInfo HotelCode="JPxxxx" />
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</OTA_HotelDescriptiveInfoService>
</soap:Body>
</soap:Envelope>
There are some options you can also use in the request:
- ShowGiataCode:
- You may use this Boolean option in order to retrieve the hotel GIATA code (if available, as this is optional information within the system). Additionaly, it is worth noting that this parameter requires for a specific permission to be enabled, contact with your supplier if you would like more information in this regard.
Response example:
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelDescriptiveInfoServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelDescriptiveInfoRS TransactionStatusCode="End">
<HotelDescriptiveContents AreaID="1953" HotelCode="BzVqeJQ79HKBCSNRDwRzQA==" JPCode="JP633562" HotelName="NoReservarJuniperPruebas" ChainName="Juniper">
<HotelDescriptiveContent>
<HotelInfo>
<CategoryCodes>
<HotelCategory Code="13" CodeDetail="Apartamento" />
</CategoryCodes>
<Descriptions>
<MultimediaDescriptions>
<MultimediaDescription>
<ImageItems>
<ImageItemsTypeImageItem>
<ImageFormat Format="Big" FileName="http://www.bookingengine.es/images/upload/hotels/Nombre/HotelAdolfo1.jpg" />
<ImageFormat Format="Thumb" FileName="http://www.bookingengine.es/images/upload_p/hotels/Nombre/HotelAdolfo1.jpg" />
</ImageItemsTypeImageItem>
<ImageItemsTypeImageItem>
<ImageFormat Format="Big" FileName="http://www.bookingengine.es/images/upload/hotels/Nombre/HotelAdolfo2.jpg" />
<ImageFormat Format="Thumb" FileName="http://www.bookingengine.es/images/upload_p/hotels/Nombre/HotelAdolfo2.jpg" />
</ImageItemsTypeImageItem>
<ImageItemsTypeImageItem>
<ImageFormat Format="Big" FileName="http://www.bookingengine.es/images/upload/hotels/Nombre/HotelAdolfo3.jpg" />
<ImageFormat Format="Thumb" FileName="http://www.bookingengine.es/images/upload_p/hotels/Nombre/HotelAdolfo3.jpg" />
</ImageItemsTypeImageItem>
<ImageItemsTypeImageItem>
<ImageFormat Format="Big" FileName="http://www.bookingengine.es/images/upload/hotels/Nombre/HotelAdolfo4.jpg" />
<ImageFormat Format="Thumb" FileName="http://www.bookingengine.es/images/upload_p/hotels/Nombre/HotelAdolfo4.jpg" />
</ImageItemsTypeImageItem>
</ImageItems>
</MultimediaDescription>
<MultimediaDescription>
<TextItems>
<TextItemsTypeTextItem Title="ShortDescription">
<Description>Descripcion corta</Description>
</TextItemsTypeTextItem>
<TextItemsTypeTextItem Title="LongDescription">
<Description>Descripción larga</Description>
</TextItemsTypeTextItem>
<TextItemsTypeTextItem Title="ZoneDescription">
<Description>Descripción - Mallorca es</Description>
</TextItemsTypeTextItem>
</TextItems>
</MultimediaDescription>
</MultimediaDescriptions>
</Descriptions>
<Position Latitude="39.601257" Longitude="2.656642" />
<Services>
<Service Code="3" CodeDetail="Restaurante" Sort="Catering" />
<Service Code="7" CodeDetail="Wi-Fi" Sort="Room" />
<Service Code="16" CodeDetail="Albornoz" Sort="Room" />
<Service Code="21" CodeDetail="Piano Bar" Sort="Catering" />
<Service Code="49" CodeDetail="Estacionamiento con Valet" Sort="Hotel" />
<Service Code="51" CodeDetail="Tenis" Sort="Sport" />
<Service Code="53" CodeDetail="Servicio de transporte a la playa" Sort="Hotel" />
<Service Code="65" CodeDetail="Plancha y Tabla" Sort="Room" />
<Service Code="76" CodeDetail="Amenities" Sort="Other" />
<Service Code="92" CodeDetail="Esto es información adicional" Sort="Other" />
<Service Code="93" CodeDetail="Z Información" Sort="Other" />
<Service Code="99" CodeDetail="Lavadora" Sort="Other" />
</Services>
</HotelInfo>
<FacilityInfo>
<GuestRooms>
<GuestRoom RoomTypeName="Single Room (1/1A+0/0n)" MaxOccupancy="1" MaxAdultOccupancy="1" ID="352" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="Doble (2/2A+1/1n)" MaxOccupancy="3" MaxAdultOccupancy="2" ID="375" MaxChildOccupancy="1" />
<GuestRoom RoomTypeName="2 ad + 0/3 ni (2/2A+0/3n)" MaxOccupancy="5" MaxAdultOccupancy="2" ID="347" MaxChildOccupancy="3" />
<GuestRoom RoomTypeName="Double limited sea view (2/3A+0/2n)" MaxOccupancy="5" MaxAdultOccupancy="3" ID="230" MaxChildOccupancy="2" />
<Amenities>
<Amenity RoomAmenityCode="RoomAreaM2" Quantity="90"/>
</Amenities>
</GuestRooms>
</FacilityInfo>
<ContactInfos>
<ContactInfo>
<Addresses>
<Address>
<AddressLine>c/Gremi Fusters 33, 07009, Palma de Mallorca, Mallorca, Espana</AddressLine>
<CityName>Mallorca</CityName>
<PostalCode>07009</PostalCode>
<CountryName>Espana</CountryName>
</Address>
</Addresses>
<Phones>
<Phone ID="+34 987456321" />
</Phones>
<Emails>
<Email>contact@email.com</Email>
</Emails>
</ContactInfo>
</ContactInfos>
<TPA_Extensions>
<Order xmlns="">1</Order>
<BestDeal xmlns="">0</BestDeal>
<Home xmlns="">0</Home>
<LastMinute xmlns="">0</LastMinute>
<AccommodationType id="2" xmlns="">Playa</AccommodationType>
<CheckInHour xmlns="">14:00</CheckInHour>
<CheckOutHour xmlns="">12:00</CheckOutHour>
</TPA_Extensions>
</HotelDescriptiveContent>
</HotelDescriptiveContents>
<Errors>
<ErrorType Type="enFORMATERROR" ShortText=" Code [JPxxxx] is not valid" Code="INVALID_CODE" />
</Errors>
</OTA_HotelDescriptiveInfoRS>
</OTA_HotelDescriptiveInfoServiceResponse>
</soap:Body>
</soap:Envelope>
In the response we obtain blocks of information like:
- < HotelDescriptiveContents >
This node contains the hotel informations. - < Errors >
If an error occurs, an Errors node will be returned.
In this example, the first hotel was successfully returned, but the second one caused an error. The response will return the nodes in the same order of the request. For example, if you ask for 5 hotels and the 4th gives an error, you will receive 3 HotelDescriptiveContents nodes, 1 Errors node, and 1 HotelDescriptiveContents node.
Click to see the example
<OTA_HotelDescriptiveInfoRS URL = "http://xml-uat.bookingengine.es/WebService/OTA_HotelDescriptiveInfo.asmx" IntCode = "L8yQvmw/QQS2NmD8qiwyNZPTmTRoe3leEDdxysVNAhc=" TimeStamp = "2021-09-03T11:32:44.6161682+02:00" TransactionStatusCode = "End">
<HotelDescriptiveContents AreaID = "76999" HotelCode = "JP02060V" JPCode = "JP02060V" HotelName = "Paredon Surf House">...</HotelDescriptiveContents>
<HotelDescriptiveContents AreaID = "2" HotelCode = "JP01883Z" JPCode = "JP01883Z" HotelName = "Hotel Indico Rock Mallorca">...</HotelDescriptiveContents>
<HotelDescriptiveContents AreaID = "35236" HotelCode = "JP782407" JPCode = "JP782407" HotelName = "Polo Towers by Diamond Resorts">...</HotelDescriptiveContents>
<Errors>
<ErrorType Type = "enFORMATERROR" ShortText = " Code [ERRORTEST] is not valid" Code = "INVALID_CODE"/>
</Errors>
</OTA_HotelDescriptiveInfoRS>
Inside the HotelDescriptiveContents node, you can find:
- < HotelInfo >
Here we can find information regarding the hotel, like images, descriptions, services and facilities, etc. - < FacilityInfo >
Here we can find room types available, ages and number of guests. - < ContactInfos >
Here we can find the contact into for the hotel, like telephone, address, etc.
Notes:
We cannot assure the accuracy of the coordinates.
We encourage the client to save in cache for some days or weeks the response of this transaction, as this information is usually more or less static. In this way traffic and bandwidth is reduced.
Service node contains the list of the hotel services/facilities, room services, etc.
- Use the “Sort” attribute to get the type of service:
- Room: Services and facilities of the room.
- Hotel: Services and facilities of the hotel.
- Catering: Restaurants and other catering facilities or services that the hotel provides.
- Sport: Services and facilities regarding sport activities.
- Other: Other unspecified services or facilities.
Hotel descriptions have the following categories (some may not be available).
- ShortDescription.
- LongDescripcion.
- RoomDescription.
- SportDescription.
- ZoneDescripcion (Deprecated).
- AdditionalDescripcion .
- < TPA_Extensions >
Here we can find extra information for the hotel, this node may contain the following information: - CheckInHour: Time after which guests may enter the hotel.
- CheckOutHour: Time until which guests may stay in the hotel.
- ContentProviders: Information regarding media content of the hotel.
- JPRooms: Information regarding the codes from the hotel unique rooms. Contact with Juniper if you’re interested on using this information as the availability of this information depends on a specific module that your suppliers could or could not have and the list of all of the available JPRooms is to be performed through a different API.
- JPCodeSynonyms. List of synonym JPCodes that have been grouped under the master JPCode. This means that all of the synonym JPCodes that are detailed on this node will stand for the master JPCode. It is important to note that, when you request for the OTA_HotelDescriptiveInfo of a synonym JPCode, the response will include the ObsoleteJPCode warning and you will be supplied with the hotel information related to the master JPCode.
Given the case, the @JPCode property from the HotelDescriptiveContents node will contain the master JPCode. If you have any additional doubt in this regard, then please do not hesitate to contact with Juniper support team.
In this example, we are requesting for a specific hotel after an availability search and through the RatePlanCode obtained from this previous transaction:
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelDescriptiveInfoService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelDescriptiveInfoRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="user@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo HotelCode="JRZeUyuAd1LQ1g0oF3ybeB6W0MlkNzZor3+SaLUfUjd7th6KgEXZBu3AW6OlAqsXSvHPEcI7GdsqfLgoaLMZy+OpOZ/yOkseGURlUzfvCiAyDutiJYNHfOp826zSljOPHtSR3Mpqg73P6WU00hyIoX5rJ0Tm3YxLsnHH+CLv9tIP29tEHSgiMe578kg3FwV0JDZAezZtMHl3wwJ84iJiILsM6bK5Fze1DHr5HNpodbamDznuegCdfvjh8CUN/HTF"/>
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</OTA_HotelDescriptiveInfoService>
</soap:Body>
</soap:Envelope>
The structure if of the response of this transaction will be similar in both cases, requesting by HotelCode or by RatePlanCode. Only the content may vary.
¶ Payment types
It will only be available if the client has the payment types parameter activated, this includes having the direct payment parameter activated.
If the accommodation has the payment types configured, this node will show the available. The payment types are validated when doing a Reservation Request, if they not match with the ones configured on the accommodation the booking won’t be created and an error will be shown “Invalid payment form for this Accommodation”. If the parameters aren’t enabled the previous behavior won’t happen, the nodes won’t show on the Hotel Information Request and the validation won’t be made on the Reservation Request. If available the Payment types information will be available under the HotelDescriptiveContent/PaymentTypes node.
Click to see the example
<PaymentTypes xmlns="">
<PaymentType id="1" type="Tarjeta" Days="10">MasterCard</PaymentType>
</PaymentTypes>
The payment types have the following attributes:
- Id: Internal payment type Code.
- Type: Type of payment type.
- Credit Card.
- Cash.
- Days: Margin of days to play.
The inner text of the paymentType tag corresponds to the payment type internal code like the Id attribute.
¶ OTA Booking Flow Transactions
¶ OTA_HotelAvail
Request: OTA_HotelAvailRq
Response: OTA_HotelAvailRs
Development URL: OTA_HotelAvail.asmx
SOAPAction for SOAP 1.1: "http://www.opentravel.org/OTA/2003/05/OTA_HotelAvailService"
This is the availability request which, given a specific set of filters, will supply you with all of the available results from within all of the available hotels from your Juniper supplier.
The following are the mandatory filters that you will need to st on all of your availability requests:
- Search dates (checkin date and checkout date). The maximum lenght of stay will be 200
- Occupancy (number of rooms and guests).
- Hotel code/s that you may wish to search availability for, you may either set a single hotel code or a list of multiple hotel codes (on which cases you can inform up to 500 hotel codes).
While you will never be able to obtain results of availability requests of more than 500 hotel codes (as we just mentioned), we recommend for you to allow for this hotel amount per request to be configurable on your integration (configuration that should not be able to exceed the 500 hotel code count, as to avoid allowing your customers to configure this erroneously), as some supplier connections may request you to limit the hotel code number ever further.
¶ Request
Important note:
Including the ShowCatalogueData will modify some of the existing available on the response and, in short, make the response lighter. Due to this, we understand that adding the same to an already existing integration may not be possible but it will be required to be used on the availability request of any new integrations.
There are some options that you may include on your availability requests, attached you will be able to find an example on how to use these options:
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCode = "JP046300"/>
<TPA_Extensions>
<ShowBasicInfo>0</ShowBasicInfo>
<ShowCatalogueData>1</ShowCatalogueData>
<PaxCountry>ES</PaxCountry>
<SearchTimeOut>8000</SearchTimeOut>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
And the specifications list of all of them:
- ShowBasicInfo:
- You should use this Boolean option to retrieve some basic hotel details in the response. If you do not include it, the response will be faster (less server process and less transfer time) but you will have to have previously retrieved the hotel information through the use of the OTA_HotelDescriptiveInfo transaction.
- ShowPromotions:
- You can use this boolean option to retrieve some extra information about promotions. This includes discounts, best deals, free nights, etc.
- If you activate it, the response will include informative texts about the promotions included, but the response will be slower.
- ShowOnlyAvailable:
- You can use this boolean option to filter on request results and get only accommodations with immediate confirmation.
- TypeSearch:
- You can use this option to search for a special product type (for example, Forfaits).
- Please refer to the FAQ: How can we search for a special product type? for further information.
- ShowInternalRoomInfo:
- With this option you can retrieve internal room information if it is available.
- ShowInternalProvInfo:
- With this option you can retrieve internal room codes if it is available.
- Mealplan:
- This option is available only for direct contracted hotels. Do not use it with external providers.
- With this option you can specify the meal plan board you wish.
- Please contact Juniper if you want to use this option for further details.
- DailyContractTypes:
- This option is available only for direct contracted hotels, do not use it with external providers.
- With this option you can specify the daily contract type you wish.
- Please contact Juniper if you want to use this option for further details.
- RoomTypes:
- This option is available only for direct contracted hotels, do not use it with external providers.
- With this option you can specify the room type you wish for a certain accommodation.
- Please contact Juniper if you want to use this option for further details.
- ExtRoomTypes:
- This option is available only for direct contracted hotels, do not use it with external providers.
- With this option you can specify an external room type code for a certain accommodation.
- Please contact Juniper if you want to use this option for further details.
- ShowSupplementsWithPickupPoints:
- For compatibility purposes. Availability results with pickup points (or any other mandatory supplement with options) will require you to specify the desired option in the confirmation request. If your integration doesn’t support mandatory options, then you won’t receive these results.
- By default the value is “false”. If you want to use it, set it to “true”.
- ShowCommission:
- This boolean option lets you know your commission (if applies). For more information, see “Net and gross prices”.
- ShowNettPrice:
- This boolean option lets you know the net price (if applies). For more information, see “Net and gross prices”.
- ShowCatalogueData:
- This option allows for the retrieval of static codes on the availability response (whose values can be retrieved with JP_CatalogueData) while changing the format of others in order to make the response lighter.
- This is disabled by default for compatibility purposes but if you are a new integrator you will be required to use the same on all of your availability requests.
- SearchByPaymentType:
- Use this option if you want to retrieve direct payment results at the availability response.
- Possible values are:
- ExcludePaymentInDestination: Direct payment results are excluded. This option is used by default, so direct payment is not activated by default.
- OnlyPaymentInDestination: Show only direct payment results.
- All: Show both direct payment and non-direct payment results.
- ShowDailyAvailabilityBreakdown:
- Use this option if you want to show the daily breakdown and the daily availability breakdown.
- ShowCancellationPolicy:
- With this option you can retrieve the cancellation policies from the combination in the availability response, if available (it is important to note that not all hotels will have the cancellation policies available on this step and that, even if enabled, you will have to control the possibility on not receiving them in this step).
- Please contact Juniper if you want to use this option for further details.
- IsGiataHotelCode:
- Use this boolean option if you want to set a Giata hotel code instead an internal one in the attribute @HotelCode. The response return the available rates for the hotel associated to this Giata code.
- PaxCountry:
- Use this option in order to set a specific PaxCountry on the availability request. This may affect the product you will receive from the availability. Before using this node please contact with your supplier about if they want you to include the nationality or not because they can configure it on their end which we recommend.
- The codes should be included as the ISO 3166-1 alfa-2 standard.
- NOTE: Please keep in mind that if you set this option on the OTA_HotelAvail, you will also have to set this option with the same exact value on the OTA_HotelBookingRule and OTA_HotelRes transactions.
- ShowAllCombinations:
- Use this option in order to retrieve all the combinations available between rooms.
- Keep in mind that this option may increase the response times.
- PackageContracts:
- Use this option if you want to search for package rates.
- Possible values are:
- Package: Package rates will be preferred but non package rates will also be retrieved.
- OnlyPackage: Only package rates will be returned.
- PropertyType:
- Use this option in order to filter the results by its property type. This option is only implemented on certain suppliers.
- Possible values are:
- Hotel: Only hotel results will be returned (in the case that the supplier doesn’t allow PropertyType filtering this option will include all the results of the mentioned supplier).
- Villa: Only home results will be returned.
- ShowOnlyBestPriceCombination:
- Use this option if you only want to retrieve the cheapest available combination.
- This option will considerable reduce the size of the response at the expense of only getting the cheapest available combination.
- This is useful for those cases that you wish to only show the cheapest available combination prior to sending an availability request for a specific hotel in order to retrieve all of the available combinations under the mentioned hotel.
- MaxCombinations:
- Use this option if you only want to retrieve the n cheapest available combinations.
- This option will considerable reduce the size of the response at the expense of only getting the cheapest available combinations.
- MinimumPrice:
- Use this option if you want to retreive the rate with the minimum price closest to the value indicated.
- The price indicated will be applied according the currency configured to the sales channel.
- SearchTimeOut:
- This value allows you to set the timeout that will be used on the availability request.
- Note that this node expects milliseconds (for example; 5000 for a 5 second timeout). This feature is recommended to be used only on single hotel availability requests on which you need to set a different timeout than the one that you use on the multi hotel / zone availability (as note that the default timeout is directly configured by your supplier, contact with your supplier if you wish for the mentioned to be adjusted).
- Note that the maximum timeout that the WebSevice interface allows is 8 seconds.
- ForceCurrency:
- This value allows you to set the currency code that will be used on the booking flow process.
- It is important to note that if a currency is specified on the availability request, you will then need to set the same TPA_Extension along the same value on the rest of the booking flow transactions.
- It is also important to note that the list of available currencies for your use (if any, as the feature could not be available) will entirely depend of the Juniper supplier that you will be connecting to.
- Last of all, please note that if no currency is set on the request the system will then use the default currency configured by your Juniper supplier.
You will also be able to find a similar parameter named UseCurrency. Note that you should not use this parameter, as it will only emulate changing the sales currency without actually changing the same.
- ExcludedSuppliers:
- This value allows you to exclude one or multiple suppliers, you can specify multiples suppliers separating the supplier codes with commas.
- Kindly note that this is a restrictive option that requires for a special permission.
- Please contact Juniper if you want to use this option for further details.
- RoomTypeCombinationCode:
- Room internal combination code. This property is mainly meant for PUSH-PULL integrations as it will allow for you to request availability of internal room codes that you previously retrieved through the PUSH files. Kindly contact with Juniper for futher information.
We look for 3 rooms, 2 rooms with 2 adults and 1 room with 2 adults and 1 child. (Age attribute can be null for adults. Guests older than 18 will be considered adults).
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelAvailService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelAvailRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<StayDateRange End="2010-09-28" Start="2010-09-26" />
<RoomStayCandidates>
<RoomStayCandidate Quantity="1">
<GuestCounts>
<GuestCount Count="2" />
<GuestCount Age="12" Count="1" />
</GuestCounts>
</RoomStayCandidate>
<RoomStayCandidate Quantity="2">
<GuestCounts>
<GuestCount Count="2" />
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCode = "JP046300"/>
<TPA_Extensions>
<ShowBasicInfo>1</ShowBasicInfo>
<ShowCatalogueData>1</ShowCatalogueData>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</OTA_HotelAvailService>
</soap:Body>
</soap:Envelope>
When wishing to search for multiple hotels, you will need to request each of the different hotels through different Criterion, such a in the following 2-hotel availability request example:
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCode="JP633562" />
<TPA_Extension>
<ShowPromotions>1</ShowPromotions>
</TPA_Extension>
</Criterion>
<Criterion>
<HotelRef HotelCode="JP633563" />
</Criterion>
</HotelSearchCriteria>
¶ Response
The response has several important items:
-
<RoomStay>
One is returned per hotel. -
<RoomRates>
Different combination of rates according to type of room and board type. -
<RoomRate>
Every combination comes int his tag, it is necessary to make the reservation in the following step.<RatePlanCode>is the code that will identify the combination we book.<RatePlanCategory>is the board description.
-
<Rates>
It contains the rates details. -
<Rate>
Each rate per room of the combination selected.<RateDescription>contains the name of the room. -
<Total>
This is total price of every combination. -
<TPA_Extensions>
It contains some extra information:- DailyBreakdown will display the daily rate (if available). It's used the separator "#" between days. Needs the option
<ShowDailyAvailabilityBreakdown>
Example for 3 days:<DailyBreakdown xmlns="">100.50#100.50#150.00 </DailyBreakdown> - DailyAvailBreakdown will display the daily available allotment (if available). It's used the separator "#" between days. Needs the option
< ShowDailyAvailabilityBreakdown>
Example for 3 days:<DailyAvailBreakdown xmlns="">1#1#1#1#1#1#1</DailyAvailBreakdown> - RecommendedPrice will display the recommended sales price of the reservation (if available, as this information is optional and may only be available for some products/results).
- DailyContractNames will display the daily name of the contract (if available). It’s used the separator “#” between days. Needs the option ShowInternalRoomInfo.
- DailyContractTypes will display the daily name of the contract (if available). It’s used the separator “#” between days. Needs the option ShowInternalRoomInfo.
- ContractTypes will display the types of the contract (if available). Needs the option ShowInternalRoomInfo.
- RoomType will display the type of room (if available). Needs the option ShowInternalRoomInfo.
- ExtRoomType will display the external code room type (if available). Needs the option ShowInternalRoomInfo. Please contact Juniper if you want to obtain this information for further details.
- AvailRooms will display the number of rooms available (if available). Needs the option ShowInternalRoomInfo to external providers.
- MealPlan will display information about the mealplan. Needs the option ShowInternalRoomInfo. If you use the option ShowCatalogueData too, will display the internal code of the meal (if available) with the attribute IntCode.
- RoomCategory will display the category of the room (if available). Needs the options ShowInternalRoomInfo and ShowCatalogueData.
- RoomOccupancy will display the room occupancy (if available). Needs the options ShowInternalRoomInfo and ShowCatalogueData.
The following node may have any of these optional attributes:- Occupancy.
- MaxOccupancy.
- MinOccupancy.
- Adults.
- Max.
- Adults.
- Min.
- Adults.
- Children.
- MaxChildren.
- MinChildren.
- MinAge
- RoomTypeGroup needs the options ShowGenericCodes and ShowInternalRoomInfo.
- MealPlanProv will display the internal code of meal (if available). Needs the option ShowInternalProvInfo.
- RoomTypeProv will display the internal code of the room (if available). Needs the option ShowInternalProvInfo.
- MandatoryBookingRule will inform if it's mandatory to call OTA_HotelBookingRule before OTA_HotelRes. If this value is true, you need a new RatePlanCode returned in the response of OTA_HotelBookingRule to be set in the request of OTA_HotelRes.
- CancellationPolicyRules will display the cancellation policies of this distribution, if available. Needs the option ShowCancellationPolicy. Please contact Juniper if you want to obtain this information for further details.
- HotelGiataCode will display the Giata code of the hotel (if available). Needs the option IsGiataHotelCode.
- PackageContract will display if the combination is package rate.
- DailyBreakdown will display the daily rate (if available). It's used the separator "#" between days. Needs the option
-
<BasicPropertyInfo>and<HotelInfo>:
It has the hotel ID and some basic info. To obtain detailed info about a hotel the message OTA_HotelDescriptiveInfo can be used. You can also activate the option ShowBasicInfo in the request.
Important note:
The static data of the hotel returned in the node HotelInfo os the information that we recommend to display (hotel name, address, category, etc.). In order to retrieve this information, you should include the TPA_Extension ShowBasicInfo in the availability request.
This same must be applied for the transaction OTA_HotelBookingRule.
With a spcial system setup, you will receive in the response a JPCode. With this new node that complements HotelCode, all rates for one unique hotelrates will be available.
It is important to note that, when the warning ObsoleteJPCode is shown, this property will identify the master JPCode related to the synonym JPCode that has been initially requested.
<BasicPropertyInfo HotelCode = "BzVqeJQ79HKBCSNRDwRzQA==" JPCode = "JP633562" HotelName = "JuniperPruebas"/>
<Feature>:
Each combination (RoomRate) may contain a list of supplements, promotions and discounts.
Important note:
The header of the OTA_HotelAvailRS tag ha an attribute SequenceNmbr whose value must be sent in the reservation request.
Example: for the previous request example, only one hotel is found, with 4 possible combinations:
- 3 Suite Rooms for 300 $, 50 $ per Suite Room and day.
- 2 Suites and 1 Twin Room for 260 $, 30 $ per Twin Room and day and 50 $ per Suite Room and day.
- 1 Suite and 2 Twin Rooms for 220 $, 30 $ per Twin Room and day and 50 $ per Suite Room and day.
- 3 Twin Rooms for 180 $, 30 $ per Twin Room and day.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelAvailServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelAvailRS SequenceNmbr="Code123">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes/>
<RoomRates>
<RoomRate RatePlanCode="COMBINATION1" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="100.00" />
<RateDescription>
<Text>Suite</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>50.00#50.00</DailyBreakdown>
<MandatoryBookingRule>1</MandatoryBookingRule>
<RoomCategory id="9">SUI</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO">
<Name>Free welcome cocktail</Name>
<Description>A free welcome cocktail is offered at the room, including a Cava glass and a selection of the best local snacks.</Description>
</Element>
</Elements>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
</RoomRate>
<RoomRate RatePlanCode="COMBINATION2" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="1" RateMode="Hab" RateSource="1">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Twin room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
<MandatoryBookingRule>0</MandatoryBookingRule>
<RoomCategory id="2">DST</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
<Rate NumberOfUnits="2" RateMode="Hab" RateSource="2,3">
<Total AmountAfterTax="100.00" />
<RateDescription>
<Text>Suite</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>50.00#50.00</DailyBreakdown>
<MandatoryBookingRule>0</MandatoryBookingRule>
<RoomCategory id="9">SUI</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="260.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
</RoomRate>
<RoomRate RatePlanCode="COMBINATION3" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="2" RateMode="Hab" RateSource="1,2">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Twin room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
<MandatoryBookingRule>1</MandatoryBookingRule>
<RoomCategory id="2">DST</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
<Rate NumberOfUnits="1" RateMode="Hab" RateSource="3">
<Total AmountAfterTax="100.00" />
<RateDescription>
<Text>Suite</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>50.00#50.00</DailyBreakdown>
<MandatoryBookingRule>1</MandatoryBookingRule>
<RoomCategory id="9">SUI</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="220.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
</RoomRate>
<RoomRate RatePlanCode="COMBINATION4" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Twin room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
<MandatoryBookingRule>0</MandatoryBookingRule>
<RoomCategory id="2">DST</RoomCategory>
<RoomOccupancy MaxOccupancy="2" />
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="180.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
</RoomRate>
</RoomRates>
<TimeSpan Start="2010-09-26" End="2010-09-28" />
<Total CurrencyCode="USD" />
<BasicPropertyInfo HotelCode="BzVqeJQ79HKBCSNRDwRzQA==" JPCode="JP633562" />
</RoomStay>
</RoomStays>
</OTA_HotelAvailRS>
</OTA_HotelAvailServiceResponse>
</soap:Body>
</soap:Envelope>
¶
Additionally, we will now detail most of the features available on this response:
¶ Extended information
If you do not want to call OTA_HotelDescriptiveInfo transaction for retrieving the information of each hotel, it is possible to get some basic information of the hotel in the availability response. If you are interested in this feature, you have to use the ShowBasicInfo option on the request.
Activating this option will result in adding a HotelInfo node in each RoomStay/TPA_Extensions:
Click to see the example
<TimeSpan Start="2010-09-26" End="2010-09-28" />
<Total CurrencyCode="USD" />
<BasicPropertyInfo HotelCode=" BzVqeJQ79HKBCSNRDwRzQA==" JPCode="JP633562" HotelName="JuniperPruebas" />
<TPA_Extensions>
<HotelInfo>
<Category Code="5" CodeDetail="*****" />
<Description>
<![CDATA[Soaring over the Mediterranean Sea on Majorca fabled coastline, this hotel is an oceanfront masterpiece, graced with panoramic vistas of the sea and Palma’s glittering skyline.]]>
</Description>
<Thumb>
<![CDATA[http://test.com/images/JP633562_thumb.jpg]]>
</Thumb>
<ContentProviders>
<ContentProvider Code="VFML">
<Thumbs>
<Thumb>
<![CDATA[http://test.com/images/JP633562_thumb.jpg]]>
</Thumb>
</Thumbs>
<MediaUrls>
<MediaUrl>
<![CDATA[http://test.com/images/INVENTEDVFML.jpg]]>
</MediaUrl>
</MediaUrls>
</ContentProvider>
</ContentProviders>
<Zone>
<![CDATA[Mallorca]]>
</Zone>
<CheckInHour>10:00</CheckInHour>
<CheckOutHour>14:00</CheckOutHour>
<AreaID>1953</AreaID>
<JPDCode>JPD036705</JPDCode>
<Address>
<![CDATA[Gremi Fusters, 33]]>
</Address>
<HotelChain>
<![CDATA[Perfect hotels]]>
</HotelChain>
<AccommodationType id="1">HOT</AccommodationType>
<Recommended>1</Recommended>
<Provider Id="1" Type="C" PaymentType="D" Days="1">Juniper.es</Provider>
<Latitude>39.5525</Latitude>
<Longitude>2.6392</Longitude>
<HotelGiataCode>75040</HotelGiataCode>
<PropertyType>hotel</PropertyType>
<Order>0</Order>
<BestDeal>0</BestDeal>
<Home>0</Home>
<LastMinute>0</LastMinute>
</HotelInfo>
</TPA_Extensions>
The AccommodationType, Mealplan and RoomCategory nodes will only applear if you select the ShowCatalogueData option in the availability request. All possible values can be retreived using the JP_CatalogueData service.
Please take into account that these nodes will only appear if the information is categorized. Some external providers do not categorize the accommodation type, the mealplan or the room category so only the name of the mealplan / room / accommodation will be available.
At this moment it is not possible to specify a mealplan / room / accommodation type at the request. Any filtering by these fields should be made by the integrator when retrieving all results. In the future the option to filter in the request will be available (no estimated date yet).
Some combinationsmay return a recommended price. This is the price that you should sell the product.
Important note:
Keep in mind that in these cases you should still book the combination using the Total/AmountAfterTax of the combination, the recommended price is purely meant for your sale.
When specified a recommended price, you will find one RecommendedPrice node in the TPS_Extensions node on each Rate node (recommended price for each specified room), and one RoomRate/TPA_Extensions/RecommendedPrice node with the recommended price of the whole combination.
<RoomRate RatePlanCode="COMBINATION5" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Sea view room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
<RecommendedPrice>70.00</RecommendedPrice>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="180.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<RecommendedPrice CurrencyCode="USD">210.00</RecommendedPrice>
</TPA_Extensions>
</RoomRate>
Each combination may include a list of element nodes (that applies only to that combination).
The Class attribute will indicate, for informative purposes, the type of supplement or discount applied.
If available, a Type attribute will also appear with the categorized type (this value is dynamic and the list with all possible values can be retrieved via XML; see JP_CatalogueData using OfferSupplementType for more details). The attribute Type will not appear if the supplement or discount is not categorized.
- Supplements:
- Class: SUPPLEMENT. Indicates general supplements (short stay, single use, handling fee, etc).
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="SUPPLEMENT" Type="SUS">
<Name>Single use supplement included</Name>
</Element>
</Elements>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
- Promotions:
- Class: PROMO. Indicates included promotions (free nights, free passengers, discounts, etc).
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO" Type="BDC">
<Name>First children free</Name>
</Element>
</Elements>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
Attached you will be able to find examples with all of the available properties under the PROMO class, keep in mind that these properties will only be available when the mentioned information is available.
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO" MinDate="2017-06-30" MaxDate="2017-07-03" Category="Percent" Quantity="35">
<Name>
<![CDATA[Gran oferta]]>
</Name>
<Description>
<![CDATA[Gran oferta! From 30/06/2017 to 03/07/2017, 35% discount! (included in price)]]>
</Description>
</Element>
</Elements>
<PriceBeforeDiscount CurrencyCode="USD">400</PriceBeforeDiscount>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO" MinDate="2017-07-17" MaxDate="2017-07-20" Category="PayStay" Free="1" Nights="3">
<Name>
<![CDATA[PayStayPromotion]]>
</Name>
<Description>
<![CDATA[From 17/07/2017 to 20/07/2017, pay 2 & stay 3 nights!]]>
</Description>
</Element>
</Elements>
<PriceBeforeDiscount CurrencyCode="USD">400</PriceBeforeDiscount>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
Note that there can also be promotions that will only contain a description.
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO">
<Description>
<![CDATA[Descuento por larga estancia Oferta Especial]]>
</Description>
</Element>
</Elements>
<PriceBeforeDiscount CurrencyCode="USD">400</PriceBeforeDiscount>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
- Discounts:
- Node PriceBeforeDiscount: Indicates the combination price without the promotion.
- Node PriceBeforeDiscountWithTax: Indicates the combination price with tax without the promotion.
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="PROMO" Type="BDC">
<Name>25% Discount included</Name>
</Element>
</Elements>
<PriceBeforeDiscount CurrencyCode="USD">400</PriceBeforeDiscount>
<PriceBeforeDiscountWithTax CurrencyCode="USD">440</PriceBeforeDiscountWithTax>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
- Direct payment supplements:
- Code: DIRECT_PAYMENT.
Important note:
This kind of supplements must be paid directly in the hotel so they are not included in the returned price.
These supplements will be also included in the BookingRule response under Comments from the provider for highlighting it.
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="DIRECT_PAYMENT">
<Name>Resort fee $2.75</Name>
<Description>Guest must pay an $2.75 per day resort fee directly to the hotel </Description>
</Element>
</Elements>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
These supplements, with the exception of direct payment supplements (promos, discounts, etc) will be included in the returned price, so you don’t have to add it to the final price.
When requesting a special product type, the Class will contain the special product type when the supplement applies to the requested product type – for example, if you search for Forfait, you may see the following:
<Element Class="FORFAIT">
You can see the FAQ: How can we search for a special product type? for further information about special product types.
Mandatory supplements with options (including pickup points or any other selectable option)
Some combinations will require you to select an option from a list retrieved in the availability results. For example, some combinations include a tour or a transfer, and you have to select the pick up point or the hour.
For compatibility purposes, this option is deactivated by default, so you won’t receive this kind of results if you don’t ask for them. If you want to receive them, use the ShowSupplementsWithPickupPoints parameter in the availability request and set it to “true”.
Pickup points (or any other selectable option) will appear in a list as a mandatory supplement.
This list of available options will appear under Description[@Name=’SELECT’]/ListItem.
<Total AmountAfterTax="140.94" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements>
<Element Class="SUPPLEMENT" Type="">
<Name>
<![CDATA[City Tour]]>
</Name>
<Options Type="PICKUP_POINT">
<Option Code="TourC#0" />
<Option Code="TourC#1" />
<Option Code="TourC#2" />
</Options>
</Element>
</Elements>
</TPA_Extensions>
The complete detail list will appear in the RoomStay/TPA_Extensions node (the list of options can be shared among all combinations).
Pickup points will appear under PickUpPoints. Other selectable options will appear under other nodes when implemented in the future.
The list will contain the supplement information, in a similar format of the supplements shown in the OTA_HotelBookingRule.
The following example shows both the basic accommodation info and the pickup list.
<TimeSpan Start="2010-09-26" End="2010-09-28" />
<Total CurrencyCode="USD" />
<BasicPropertyInfo HotelCode="JP633562" HotelName="Maximum Luxo Hotel Resort and Spa" />
<TPA_Extensions>
<HotelInfo>
<Category Code="5" CodeDetail="*****" />
<Description>
<![CDATA[Soaring over the Mediterranean Sea on Majorca fabled coastline, this hotel is an oceanfront masterpiece, graced with panoramic vistas of the sea and Palma’s glittering skyline. ]]>
</Description>
<Thumb>
<![CDATA[http://test.com/images/JP633562_thumb.jpg]]>
</Thumb>
<Zone>
<![CDATA[Mallorca]]>
</Zone>
<AreaID>1953</AreaID>
<JPDCode>JPD036705</JPDCode>
<Address>
<![CDATA[Gremi Fusters, 33]]>
</Address>
<HotelChain>
<![CDATA[Perfect hotels]]>
</HotelChain>
<Latitude>39.5525</Latitude>
<Longitude>2.6392</Longitude>
<HotelGiataCode>75040</HotelGiataCode>
</HotelInfo>
<PickUpPoints>
<Supplement id="TourC" type="M">
<Option>
<Code>TourC#0</Code>
<Name>City Tour, pickup Maximum Luxo Hotel</Name>
<Hour>09:00</Hour>
<Address>Hotel hall</Address>
</Option>
<Option>
<Code>TourC#1</Code>
<Name>City Tour, pickup Maximum Luxo Hotel </Name>
<Hour>11:30</Hour>
<Address>Hotel hall </Address>
</Option>
<Option>
<Code>TourC#2</Code>
<Name>City Tour, pickup Maximum Luxo Hotel </Name>
<Hour>15:00</Hour>
<Address>Hotel hall</Address>
</Option>
</Supplement>
</PickUpPoints>
</TPA_Extensions>
When requesting a booking confirmation, you will have to send the supplement id, type and the selected option code. For more information, please see Reservation Request section.
Mandatory supplement with alternative
When the system returns a supplement with the OPTIONAL_SUPPLEMENT class it means that this supplement is included in the price while at the same time it can be changed by another supplement.
You can use the ShowSuplementID option in order to show the supplement identifier.
<Total AmountAfterTax="300.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Elements xmlns="">
<Element Id="10361" Class="OPTIONAL_SUPPLEMENT" Type="GEN" Price="101,70" Currency="EUR">
<Name>
<![CDATA[Ticket 3 days]]>
</Name>
<Description>
<![CDATA[Ticket description]]>
</Description>
</Element>
<Element Id="10384" Class="SUPPLEMENT" Type="GEN" Price="9" Currency="EUR">
<Name>
<![CDATA[Mandatory]]>
</Name>
</Element>
</Elements>
<Mealplan Category="SA" id="6">6</Mealplan>
</TPA_Extensions>
On the OTA_HotelBookingRule response, this supplement will appear as an optional supplement but with a num=”1” attribute, so the supplement will be included in the TotalPrice node. If you wish to alternate this supplement with a different one, you can do so by simply sending a different supplement on the booking confirmation request.
Below there is an example of alternative supplements from a OTA_HotelBookingRule response:
<Supplements xmlns="">
<Supplement id="10361" type="O" Discount="0" name="Ticket 3 days" price="101.70" SelectByPax="0" empaquetado="0">
<Desc>
<![CDATA[Ticekt description]]>
</Desc>
</Supplement>
<Supplement id="10362" type="O" Discount="0" name="Ticket 4 days" price="110.70" SelectByPax="0" empaquetado="0">
<Desc>
<![CDATA[Ticekt description]]>
</Desc>
</Supplement>
<Supplement id="10384" type="M" Discount="0" name="Mandatory" price="9.00" SelectByPax="0" empaquetado="0" />
</Supplements>
From which, if you send an additional OTA_HotelBookingRule request along the selected supplement:
<TPA_Extensions>
<Supplements xmlns="">
<Supplement id="10362" type="O" num="1"/>
</Supplements>
</TPA_Extensions>
You will be able to calculate the total price while including the selected supplement (it is important to note that the selected supplement will appear along num=”1”).
It is important to note that when you will create the booking you will also have to set this supplement on your booking confirmation request.
Optional supplements on which you will be able to choose its first day
In some type of supplements it is possible to choose the first day on which it take place. For example, in the tickets it's possible that the system needs the deseired day to made the booking, beause the price would be different. In that case, in the booking rules the attribute firstDaySelected will appear as follows:
<Supplements xmlns="">
<Supplement id="10361" type="O" Discount="0" name="Ticket 3 days" price="101.70" SelectByPax="0" num="1" empaquetado="0" firstDaySelected="1">
<Desc>
<![CDATA[Ticekt description]]>
</Desc>
</Supplement>
<Supplement id="10362" type="O" Discount="0" name="Ticket 4 days" price="110.70" SelectByPax="0" empaquetado="0" firstDaySelected="1">
<Desc>
<![CDATA[Ticekt description]]>
</Desc>
</Supplement>
</Supplements>
It means that the supplement will start the first day of booking, but it's possible to change it. To change, you can send it in a new OTA_HotelBookingRule request with:
<TPA_Extensions>
<Supplements xmlns="">
<Supplement id="10361" type="O" num="1" firstDaySelected="3" />
</Supplements>
</TPA_Extensions>
In the result, the price will be calculated as the service starts at the 3º day of booking.
You must send the firstDaySelected information at OTA_HotelRes and OTA_HotelResModify.
NonRefundable promotions
There may be some non-refundable promotions associated to a particular room. In the event that one of the roomtypes in a booking has a non-refundable promotion applied to it, the booking will have a 100% penalty from the date in which that booking is confirmed.
This can be informed in one of the following ways:
- Attribute NonRefundable: if the promotion corresponds to this type, the attribute “nonrefundable” in TPA_Extensions/Element will be “true”.
- This attribute may not be available. In this case, a plain text will inform about the promotion properties.
Non-refundable promotions will produce non-refundable rooms. These rooms follow the same regular rules of non-refundable rooms explained in following sections.
Example including the attribute @NonRefundable as true:
<TPA_Extensions>
<Elements>
<Element Class="PROMO" Type="BDC" NonRefundable="True" Price="-36" Currency="USD">
<Name>Discount 5% off</Name>
</Element>
</Elements>
</TPA_Extensions>
Example described only with plain text:
<TPA_Extensions>
<Elements>
<Element Class="PROMO">
<Name>Non-refundable rate. Changes are not allowed</Name>
</Element>
</Elements>
</TPA_Extensions>
There may be some non-refundable combinations. In the event, the booking will have a 100% penalty from the date in wich that booking is conformed.
<RoomRate RatePlanCode="COMBINATION1" RatePlanCategory="Room Only" AvailabilityStatus="AvailableForSale ">
<Rates>
<Rate NumberOfUnits="1 " RateMode="Room " RateSource="1 ">
<Total AmountAfterTax="163.26 " DecimalPlaces="2 " />
<RateDescription>
<Text>Executive Studio (NRF)</Text>
</RateDescription>
<TPA_Extensions>
<Mealplan xmlns=" ">3</Mealplan>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="163.26 " CurrencyCode="USD " DecimalPlaces="2 " />
<TPA_Extensions>
<Mealplan Category="RO " id="3 ">3</Mealplan>
<NonRefundable>1</NonRefundable>
</TPA_Extensions>
</RoomRate>
The prices returned can be both net (the price returned is the price you have to pay to the provider, so you have to add by yourself a markup to the specified price in order to earn money) or gross (the price returned includes your commission).
This depends on the provider’s configuration. However you can ask explicitly for the nett price and/or your commission, using the ShowCommission and/or ShowNettPrice optional parameters in the availability request.
<TPA_Extensions>
<ShowBasicInfo>1</ShowBasicInfo>
<ShowPromotions>1</ShowPromotions>
<ShowCommission>1</ShowCommission>
<ShowNettPrice>1</ShowNettPrice>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
</AvailRequestSegment>
The extra information will be returned as a NettPrice node or a Commission node.
The nett price + the commission will be th price returned in the Total[@AmountAfterTax] attribute.
If you work with nett prices directly, the commission will be 0. This is an example:
<RoomRate RatePlanCode="COMBINATION5" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Sea view room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
</TPA_Extensions>
</Rate>
</Rates>
<Features>
<Feature RoomViewCode="COMMISSION">
<Description Name="VALUE">
<Text>0.00</Text>
</Description>
</Feature>
<Feature RoomViewCode="NETT_PRICE">
<Description Name="VALUE">
<Text>180.00</Text>
</Description>
</Feature>
</Features>
<Total AmountAfterTax="180.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Commission CurrencyCode="USD">0.00</Commission>
<NettPrice CurrencyCode="USD">180.00</NettPrice>
</TPA_Extensions>
</RoomRate>
If you work with gross prices, you will get the nett price and the commission included. For example:
<RoomRate RatePlanCode="COMBINATION5" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Sea view room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
</TPA_Extensions>
</Rate>
</Rates>
<Features>
<Feature RoomViewCode="COMMISSION">
<Description Name="VALUE">
<Text>0.00</Text>
</Description>
</Feature>
<Feature RoomViewCode="NETT_PRICE">
<Description Name="VALUE">
<Text>180.00</Text>
</Description>
</Feature>
</Features>
<Total AmountAfterTax="180.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Commission CurrencyCode="USD">18.00</Commission>
<NettPrice CurrencyCode="USD">162.00</NettPrice>
</TPA_Extensions>
</RoomRate>
If the provider gives you some products in nett and some in gross prices, you can use always the ShowCommission and ShowNettPrice in the availability request in order to distinguish between gross prices and nett prices.
In case you also get the Recommended price with gross price, then you have to sell the product at the specified price, because your commission is included in the price.
This is an example. You have to sell for 180 $, and you get a 10% (18 $).
<RoomRate RatePlanCode="COMBINATION5" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="3" RateMode="Hab" RateSource="1,2,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Sea view room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
<RecommendedPrice>60.00</RecommendedPrice>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="180.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<Commission CurrencyCode="USD">18.00</Commission>
<NettPrice CurrencyCode="USD">162.00</NettPrice>
<RecommendedPrice CurrencyCode="USD">180.00</RecommendedPrice>
</TPA_Extensions>
</RoomRate>
If more than one room is requested, the response will contain a RateSource attribute which indicates the order of the rooms.
For example, if you request one single room, one double room, and one single room, you may see:
<RoomRate RatePlanCode="COMBINATION5" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="2" RateMode="Hab" RateSource="1,3">
<Total AmountAfterTax="60.00" />
<RateDescription>
<Text>Single room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>30.00#30.00</DailyBreakdown>
</TPA_Extensions>
</Rate>
<Rate NumberOfUnits="1" RateMode="Hab" RateSource="2">
<Total AmountAfterTax="70.00" />
<RateDescription>
<Text>Double room</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>35.00#35.00</DailyBreakdown>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="190.00" CurrencyCode="USD" DecimalPlaces="2" />
</RoomRate>
This means that 3 rooms are returned, grouped in two room types (single and double).
The single applies to the first and third rooms requested (RateSource="1,3") and the double applies to the second room requested (RateSource="2").
Some external providers do not provide a final price at the availability zone request.
Instead, they provide a reference price (which means This hotel is available from 100 $).
If you want to see all available rooms and meal plans, you have to perform an availability request for that hotel.
These reference price results are marked with the node ReferencePrice. They include basic information and in most cases no room type or meal plan is provided.
<RoomStay>
<RoomRates>
<RoomRate RatePlanCode="COMBINATION1" RatePlanCategory="" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="1" RateMode="Hab" RateSource="1">
<Total AmountAfterTax="100.00" />
<RateDescription>
<Text>Double</Text>
</RateDescription>
</Rate>
</Rates>
<Total AmountAfterTax="100.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<ReferencePrice>1</ReferencePrice>
</TPA_Extensions>
</RoomRate>
</RoomRates>
<TimeSpan Start="2010-09-26" End="2010-09-28" />
<Total CurrencyCode="USD" />
<BasicPropertyInfo HotelCode="7bOrLYZEqj9yfyClLMcpEd2kUO1EE=" JPCode=" JP046542" />
</RoomStay>
In these cases there are two options:
- You can perform an availability request per hotel.
In this response, all available room types, meal plan and final prices will be provided (and the ReferencePrice node will not appear or will be 0 or false).
Now you can use the new RatePlanCode values returned in the new response. - Book directly the combination with the RatePlanCode obtained in the availability request per zone. The cheapest combination will be booked with the reference price.
Use this last option with caution, as normally the providers that work with reference price work with a cache and do not send the exact price at the reference price, so there can be variations in the final price (so for example if you try to book for 100 $ , you can get an error if the real price is 103 $ and you specify at the booking confirmation a maximum accepted price lower than that).
Some hotel results are tagged as Direct payment.
In these cases the payment is made by the hotel with the final user credit card.
If you want to confirm a direct payment booking, the credit card must be provided in the OTA_HotelRes request (as a guarantee).
Direct payment is deactivated by default. In order to get results with direct payment, you must specify it in the availability request (see the option list in the OTA_HotelAvail main section).
The following XML contains a direct payment combination result.
<RoomRate RatePlanCode="COMBINATION2" RatePlanCategory="Room only" AvailabilityStatus="AvailableForSale">
<Rates>
<Rate NumberOfUnits="1" RateMode="Hab" RateSource="1">
<Total AmountAfterTax="75.00" />
<RateDescription>
<Text>Junior Suite</Text>
</RateDescription>
<TPA_Extensions>
<DailyBreakdown>35.00#40.00</DailyBreakdown>
<RecommendedPrice>75.00</RecommendedPrice>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax="75.00" CurrencyCode="USD" DecimalPlaces="2" />
<TPA_Extensions>
<PaymentInDestination>1</PaymentInDestination>
</TPA_Extensions>
</RoomRate>
See the FAQ: When should we send the credit card? Which payment options are there? for more information about direct payment.
¶ OTA_HotelBookingRule
Request: OTA_HotelBookingRuleRq
Response: OTA_HotelBookingRuleRs
Development URL: OTA_HotelBookingRule.asmx
SOAPAction for SOAP 1.1: “http://www.opentravel.org/OTA/2003/05/OTA_HotelBookingRuleService”
OTA_HotelBookingRule is used to retrieve additional info that the client should know before making the reservation. It is always recommended to implement this operation and it is mandatory for some specific hotels which can suffer significant changes between the availability and the policy cancellation transactions. You can check if it is mandatory (true) or not (false) in the tag TPA_Extensions / MandatoryBookingRule from the response of OTA_HotelAvail.
The response includes the cancellation policy and hotel/provider comments. Also, a list of warnings may be returned if price or allotment has changed between the initial availability search and this transaction. This is the Price Verification functionality.
You can only ask booking rules for one combination on each petition. For that reason you should use this operation only when you want to know the booking rules of a specific combination.
For more info, please see the FAQ section: When should we use the Booking Rules request?
<soap:Envelope xmlns:soap = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelBookingRuleService xmlns = "http://www.opentravel.org/OTA/2003/05">
<OTA_HotelBookingRuleRQ PrimaryLangID = "en" SequenceNmbr = "U2BlFk5ih5KN0zl/4F603J/y6s2iAg/98oNTwqzKHBY=">
<POS>
<Source AgentDutyCode = "username@mydomain.com">
<RequestorID Type = "1" MessagePassword = "pass"/>
</Source>
</POS>
<RuleMessage HotelCode = "JP046300">
<StatusApplication RatePlanCode = "ya79dM4dS6R6EywV4XhfEhQaJi8y3fxcJtvpS7HwEMBbgHDaJx3DIJp..." Start = "2021-09-09" End = "2021-09-11"/>
<TPA_Extensions>
<PaxCountry>ES</PaxCountry>
</TPA_Extensions>
</RuleMessage>
</OTA_HotelBookingRuleRQ>
</OTA_HotelBookingRuleService>
</soap:Body>
</soap:Envelope>
Key points:
- Attribute SequenceNmbr must have the same value of SequenceNmbr attribute obtained in the OTA_HotelAvail response.
- RatePlanCode attribute set in the HotelBookingRule request must be exactly the same as returned in the availability response. Moreover, you must use the same data that you asked in the availability request (hotel, dates, etc). If not, an error will be thrown. If you want to change any data, you have to do another search and use the new RatePlanCode code (apart of the new SequenceNumber value obtained).
- The SequenceNumber, HotelCode and dates are the same data that you will use in the reservation request.
- The RatePlanCode returned in the response of the HotelBookingRule transaction may change from the one received in the availability response. You must confirm the booking OTA_HotelRes with the RatePlanCode retrieved from the the response of the OTA_HotelBookingRules transaction.
- The TotalPrice returned int he response of the HotelBookingRule transaction may change from the one received in the availability response. You must confirm the booking OTA_HotelRes with the TotalPrice retrieved from the the response of the OTA_HotelBookingRules transaction.
- You can use the optional boolean tag ShowSupplements in order to retrieve optional available supplements and a more detailed supplement breakdown. If not included, by default the value is 0.
- You can use the optional boolean tag ShowOnlyBasicInfo in order to not retrieve the Description and Thumb nodes in HotelInfo. If not included, by default the value is 0.
- If you included the PaxCountry in the availability request, it’s mandatory to set the same PaxCountry in the booking rules request.
¶ Response
The response has the following parts:
- Warnings: Due to the Price Verification functionality, the response may return a list of warnings if something related to the price, currency or availability has changed.
The possible warnings are:Type="1" ShortText="Price changed" Code="PRICE_CHANGED"Type="2" ShortText="Quote changed" Code="QUOTE_CHANGED"Type="3" ShortText="Not availability" Code="NOT_AVAILABILITY"Type="4" ShortText="Price review is not possible" Code="NOT_POSSIBLE"Type="5" ShortText="There is a category difference" Code="CATEGORY_DIFFERENCE"Type="6" ShortText="No reservable" Code="NOT_BOOK"
It is important to note that you should always check if there is a price change by comparing the availability price with the booking rules price regardless of the PRICE_CHANGED warning.
- Cut-off date: If available, this date indicates the moment when the booking would start incurring into cancellation costs. Please note that sometimes this date cannot be calculated automatically. (Attribute AbsoluteCutoff).
- Cancellation policy: If available, a cancellation policy is shown here.
- Comments from the hotel or provider: If available, some comments from the hotel or provider are shown here.
- Supplements: If asked at the request, the response will return a list with available supplements for that hotel and dates.
Each Supplement node has the following information:- Type (@type): It indicates the type of the supplement, may have the following values:
- M: Mandatory supplement.
- R: Restriction supplement.
- O: Basic optional supplement.
- Id (@Id): Internal supplement code. You have to use it in the OTA_HotelRes request if you want to add the supplement.
- Name (@name): Supplement name.
- Price (@price): If exists, it indicates of the supplement, in the availability currency.
- Direct payment (@DirectPayment): If exists, indicates if the supplement has to be paid directly at the hotel. Default: false.
- On Request (@OnRequest): If exists, indicates that the supplement is on request , so if you choose it, it may change the reservation status to on request.
- Type (@type): It indicates the type of the supplement, may have the following values:
- EarlyBooking: If asked at the request, the response will return a list with the payment conditions of any applicable earlybooking supplements.
- Id (@id): Id of the supplement that these payment condicitons apply to.
- Percentage (Percentage): the percentage value that will apply to the sales booking value and which result will be the amount to pay.
- CostValue (CostValue): the amount to pay as a fixed value.
- PaymentDate (PaymentDate): the date in which the payment is due.
Click to see the example
<Supplements>
<Supplement id="37245567" type="M" Discount="1" name=" IBD 1 10%" price="-1.56" SelectByPax="0" empaquetado="0" />
</Supplements>
<EarlyBooking id=” 37245567” xmlns="">
<Percentage>15</Percentage>
<PaymentDate>25/10/2008</PaymentDate>
</EarlyBooking>
It is very important to check this node, as it may include applicable payment conditions.
- Preferences: List of available preferences fot he combination. Only implemented on certain suppliers.
Each Preference node has th following information:- Code (@Code): Internl preference code. You may use it in the OTA_HotelRes request if you want to select the preference.
- Description: Descriprion of the preference.
- Required fields: Independent nodes. If available, each one of them indicates if this particular node is mandatory to be sent in OTA_HotelRes request. Possible returned fields are:
- RequirePaxName: indicates if it is mandatory to send the names of all the pax included in the booking.
- RequirePaxSurName: indicates if it is mandatory to send the surnames of all the pax included in the booking.
- RequirePaxDocumentNumber: indicates if it is mandatory to send the document number of all the pax included in the booking.
- RequirePaxDocumentType: indicates if it is mandatory to send the document type of all the pax included in the booking.
- RequireFullAddress: If available, indicates if it is mandatory to send the complete address of the booking customer (main pax).
- RequirePostalCode: If available, indicates if it is mandatory to send the postal code of the booking customer (main pax).
- RequireCityCode: If available, indicates if it is mandatory to send the name of the city of the booking customer (main pax).
- RequireCountryName: If available, indicates if it is mandatory to send the name of the country of the booking customer (main pax).
- RequireCountryCode: If available, indicates if it is mandatory to send the code (ISO2) of the country of the booking customer (main pax).
- RequireTelephoneHolder: If available, indicates if it is mandatory to send the telephone of the country of the booking customer (main pax).
- RequireEmailHolder: If available, indicates if it is mandatory to send the email of the booking customer (main pax).
- RequireDocumentNumberHolder: If available, indicates if it is mandatory to send the document number of the booking customer (main pax).
- HotelInfo: Here we can find basic informationof the hotel such as category, description, zone, areaID, address, longitude and latitude, etc.
The format is the same as the node HotelInfo in the available response.
Important note:
The static data of the hotel returned in the node HotelInfo is the information that we recommend to display (hotel name, address, catecogry, etc.). In order to retrieve this information, you should include the TPA_Extension ShowBasicInfo in the request.
This same must be applied for the transaction OTA_HotelAvail.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelBookingRuleServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelBookingRuleRS Version="0" SequenceNmbr="Code123">
<Success/>
<RuleMessage HotelCode="7bOrLYZEqj9yfyClLMcpE77a4QrbPq5txD7d2kUO1EE=" JPCode="JP046542" HotelName="Maximum Luxo Hotel Resort and Spa">
<StatusApplication RatePlanCode="COMBINATION3" End="2010-09-28" Start="2010-09-26" />
<BookingRules>
<BookingRule AbsoluteCutoff="2010-09-23T00:00:00">
<CancelPenalties>
<CancelPenalty>
<PenaltyDescription>
<Text>Cancelling 3 days before check-in has a cancellation cost of 1 night</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<Description>
<Text> Resort Fee: A $2.75 resort fee per room; per day is not included in the rate and will be paid by the guest directly to the hotel at checkout. </Text>
</Description>
<TPA_Extensions>
<Supplements>
<Supplement id="SUS" type="M" name="Single use supplement included" price="30" />
<Supplement id="RFEE" type="M" name="Resort fee (Hotel direct payment)" price="8.25" DirectPayment="1" />
<Supplement id="PARK" type="O" name="Parking (Hotel direct payment)" price="70.00" DirectPayment="1" />
<Supplement id="CITYBUS" type="O" name="City bus sightseeing (4 hours, 7 pax)" price="140.00" OnRequest="1" />
</Supplements>
<Preferences>
<Preference Code="200075169~200449792~NS">
<Description>Premium Room – Room only: No smoking room</Description>
</Preference>
</Preferences>
<TotalPrice CurrecncyCode="EUR">220</TotalPrice>
<RequirePaxName>1</RequirePaxName>
<RequirePaxSurName>1</RequirePaxSurName>
<RequirePaxDocumentNumber>1</RequirePaxDocumentNumber>
<RequirePaxDocumentType>1</RequirePaxDocumentType>
<RequireFullAddress>1</RequireFullAddress>
<RequirePostalCode>1</RequirePostalCode>
<RequireCityCode>1</RequireCityCode>
<RequireCountryName>1</RequireCountryName>
<RequireCountryCode>1</RequireCountryCode>
<RequireTelephoneHolder>1</RequireTelephoneHolder>
<RequireEmailHolder>1</RequireEmailHolder>
<HotelInfo>
<Category Code="5" CodeDetail="*****" />
<Description>
<![CDATA[Soaring over the Mediterranean Sea on Majorca fabled coastline, this hotel is an oceanfront masterpiece, graced with panoramic vistas of the sea and Palma’s glittering skyline.]]>
</Description>
<Thumb>
<![CDATA[http://test.com/images/JP633562_thumb.jpg]]>
</Thumb>
<Zone>
<![CDATA[Mallorca]]>
</Zone>
<AreaID>54813</AreaID>
<JPDCode>JPD0000015</JPDCode>
<Address>
<![CDATA[Gremi Fusters, 33]]>
</Address>
<Latitude>39.5525</Latitude>
<Longitude>2.6392</Longitude>
<HotelGiataCode>75040</HotelGiataCode>
</HotelInfo>
<VirtualCreditCardInfo>
<Currency>RUB</Currency>
<ValidFrom>Arrival date</ValidFrom>
<IncreaseDays>3</ IncreaseDays>
<Email>contact@email.com</ Email>
</VirtualCreditCardInfo>
</TPA_Extensions>
</BookingRule>
</BookingRules>
</RuleMessage>
</OTA_HotelBookingRuleRS>
</OTA_HotelBookingRuleServiceResponse>
</soap:Body>
</soap:Envelope>
¶
Additionally, we will now detail most of the features available on this response:
¶ Extended information
This WebService does not return cancellation policies in the OTA_HotelAvail response by default. It is necessary to call the OTA_HotelBookingRules transaction in order to retrive them.
Under certain circumstances, it is also possible to get these policies in the availability response.
For further information, please see the section concerning OTA_HotelAvail.
The cancellation policy text will be available under the
BookingRule/CancelPenalties/CancelPenalty/PenaltyDescription/Text node.
If available, a list of cancellation policy rules will be available under the
BookingRule/TPA_Extensions/CancellationPolicyRules node.
Important note
It is important to keep in mind that on some cases the list of cancellation policy rules may not be available. In these cases it is mandatory to read the node that contains the cancellation policy as plain text.
Here an example of cancellation policy rules:
<CancellationPolicyRules CurrencyCode = "USD">
<Rule DateFrom = "2016-09-09T00:00:00" Type = "S" FixedPrice = "0.00" PercentPrice = "100" Nights = "0" ApplicationTypeNights = ""/>
<Rule From = "0" To = "9" DateFrom = "2016-08-30T00:00:00" DateTo = "2016-09-09T00:00:00" Type = "V" FixedPrice = "0.00" PercentPrice = "0.00" FirstNightPrice = "166.67" Nights = "1" ApplicationTypeNights = "FirstNight"/>
<Rule From = "10" DateFrom = "2016-06-30T00:00:00" DateTo = "2016-08-30T00:00:00" Type = "V" FixedPrice = "0.00" PercentPrice = "0.00" Nights = "0" ApplicationTypeNights = ""/>
</CancellationPolicyRules>
The rules have the following attributes:
- Type: The type of rule that will be used:
- V: Before check in date.
- R: After thebooking confirmation date.
- S: No show.
- From / To: Optional attribute. Indicates the number of days beforethe check in date (or after the confirmation date depending its Type).
- DateFrom: Optional attribute. It indicates the date in which the cancellation policy rules calculation will start to apply, which will be from this date on.
- DateTo: Optional attribute. It indicates the end date in which the cancellation charges will apply without being included in the cancellation policy rule calculation.
- StayLengthFrom: Optional attribute. Indicates the stay length or number of nights from which the cancellation rule applies.
- StayLengthTo: Optional attribute. Indicates the stay length or number of nights to which the cancellation rule applies. If StayLengthFrom is informed but StayLengthTo is not, the rule applies to all bookings longer than StayLengthFrom value.
- FixedPrice: Price value of the rule (in CurrencyCode).
- PercentPrice: Price percentage of the rule.
- MostExpensiveNight: Price value of the rule when it’s ApplycationTypeNights is MostExpensiveNight.
- Nights: Number of nights of penalty.
- ApplicationTypeNights: If we have any night type cancellation charge configuration, it will indicate how the price per night will be calculated. The possible night type values are:
- Average: this is the average price of all nights.
- FirstNight: the price of the first night.
- MostExpensiveNight: the price of the most expensive night.
- Blank or empty field: If there is a nights penalty and this field is blank, you can assume that the application will be Average otherwise (if there is no nights penalty nor ApplicationTypeNights value you can assume that there will be no
night penalty).
- FirstNightPrice: Price for the first night, only available if ApplicationTypeNights has the FirstNight type.
Note
Keep in mind that when interpreting the rules on your side you should prioritize the use of the From / To properties and if they were not available, the DateFrom / DateTo properties.
Examples:
- Cancelling from 20th August 2016 to 22nd August 2016: you have a penalty of 10 $ (although not the most common case there may be some rules with no From / To properties)
<Rule DateFrom="2016-08-20T00:00:00" DateTo="2016-08-22T00:00:00" Type="V" FixedPrice="10" PercentPrice="0" Nights="0" ApplicationTypeNights=""/>
On all the following examples we will assume that the confirmation date is the 2016-06-30 and the checkin date is the 2016-09-08.
- No show with a 100% penalty
<Rule DateFrom="2016-09-09T00:00:00" Type="S" FixedPrice="0.00" PercentPrice="100" Nights="0" ApplicationTypeNights=""/>
- Cancelling 2 days after the confirmation date would incur into a 25% of penalty.
<Rule From="2" DateFrom="2016-07-02T00:00:00" Type="R" FixedPrice="0" PercentPrice="25" Nights="0" ApplicationTypeNights=""/>
- Cancelling 1 week before check-in date you have no penalty.
<Rule From="7" DateFrom="2016-06-30T00:00:00" DateTo="2016-09-02T00:00:00" Type="V" FixedPrice="0.00" PercentPrice="0.00" Nights="0" ApplicationTypeNights=""/>
Note
Keep in mind that if on a Type=”V” rule there is no To property, it will mean that the rule will go from the date specified on the From property to the first date of the booking, the confirmation date.
This also applies to Type=”R” rules where the rule would go from the date specified on the From property to the last date of the booking.
- Cancelling 2 weeks before check-in date (or before 2 weeks): you have no penalty.
- Cancelling between 1 and 2 weeks before check-in date: you have a 10% of penalty.
- Cancelling up to 1 week before check-in date: you have a 25% of penalty. No show incurs into a 50% of penalty.
<Rule From="14" DateFrom="2016-06-30T00:00:00" DateTo="2016-08-26T00:00:00" Type="V" FixedPrice="0.00" PercentPrice="0.00" Nights="0" ApplicationTypeNights=""/>
<Rule From="7" To="13" DateFrom="2016-08-26T00:00:00" DateTo="2016-09-02T00:00:00" Type="V" FixedPrice="0.00" PercentPrice="10" Nights="0" ApplicationTypeNights=""/>
<Rule From="0" To="6" DateFrom="2016-09-02T00:00:00" DateTo="2016-09-09T00:00:00" Type="V" FixedPrice="0.00" PercentPrice="25" Nights="0" ApplicationTypeNights=""/>
<Rule DateFrom="2016-09-09T00:00:00" Type="S" FixedPrice="0.00" PercentPrice="50" Nights="0" ApplicationTypeNights=""/>
- Between the date on which the booking is confirmed and until 1 week before the check-in date, if you cancel, you will have the price of the first night as a penalty.
<Rule From="7" DateFrom="2016-06-30T00:00:00" DateTo="2016-09-02T00:00:00" Type="V" FixedPrice="0.00" PercentPrice="0.00" FirstNightPrice="166.67" Nights="1" ApplicationTypeNights="FirstNight"/>
- Cancelling 1 week before check-in date (or before 1 week) you have the price of the most expensive night as penalty, with the exact value at MostExpensiveNight.
<Rule Type="V" From="7" DateFrom="2013-08-10" DateFromHour="00:00" FixedPrice="0" PercentPrice="0" Nights="1" MostExpensiveNight="733.33" ApplicationTypeNights="MostExpensiveNight"/>
In some cases it is not necessary to specify the name of all passengers – only the holder is required.
In other cases (by default), all passengers are required, apart from the holder.
If the node RequirePaxName is true or 1, or the node does not exist, then all passengers must be specified in the OTA_HotelRes request. The holder is mandatory in all cases, and should be among the passengers if they are included.
If the passenger names are not mandatory (RequirePaxName is false or 0), they can be omitted (but you can specify them if you want). However the holder is still mandatory.
Some external providers may have special name conditions, so in order to avoid problems try to:
- Include the holder in the passenger names (if they are specified).
- Avoid repeated names.
- Avoid numbers.
- Avoid empty names.
Besides this requirement, there may be some other fields returned that indicate required fields in the booking confirmation. The complete list of possible fields returned is the following:
- RequirePaxName
- RequirePaxSurName
- RequirePaxDocumentNumber
- RequirePaxDocumentType
- RequireFullAddress
- RequirePostalCode
- RequireCityCode
- RequireCountryName
- RequireCountryCode
- RequireTelephoneHolder
- RequireEmailHolder
See OTA_HotelRes for more details.
In the event that one of the roomtypes in a booking has a non-refundable rule applied to it, the booking will have a 100% penalty from the date in which that booking is confirmed.
You can know this with the following information:
- AbsoluteCutoff: this date indicates the moment when the booking would start incurring into cancellation costs. In which case, the date applicable will be the date the booking is created.
- Attribute nonrefundable: if the combination is this type, the attribute nonrefundable in TPA_Extensions/CancellationPolicyRules will be true.
- Rule: Cancelling 0 days after the confirmation (or after 0 days) would incur into a 100% of penalty.
<OTA_HotelBookingRuleRS>
…
<BookingRules>
<BookingRule AbsoluteCutoff="2010-09-23T00:00:00">
…
<TPA_Extensions>
<CancellationPolicyRules CurrencyCode="EUR" nonRefundable="True" xmlns="">
<Rule Type="R" From="0" FixedPrice="0.00" PercentPrice="100.00" Nights="0" ApplicationTypeNights="" />
</CancellationPolicyRules>
</TPA_Extensions>
…
</BookingRule>
</BookingRules>
…
</OTA_HotelBookingRuleRS>
Please note the following regarding supplements:
- Restriction supplements are returned for informative purposes and normally don't have any price indicated.
- Mandatory supplements are always selected and can't be deselected.
- If it is direct payment supplement, then the price is not included in the reservation final price and the import be paid directly by the client at the hotel.
- If it is not a direct payment supplement, then th price is already included in the reservation final price.
- Optional supplements: These are the only supplements you can choose at the OTA_HotelRes request.
- Basic optional supplements allow yes or no (1 if you want to select it, 0 if you don’t want it).
- The total supplement price is always selected number x price.
- If it is a direct payment supplement, then the price is not included in the reservation final price and the import should be paid directly by the client at the hotel if they want the service.
- If it is not a direct payment supplement, then the final price of the reservation will be greater than the price returned at the availability response. Remember to add the optional supplement price at the expected price of the reservation request when confirming the reservation.
- All direct payment supplement will also be indicated at the Comments from the hotel or provider section of the XML, so if you decide not to use supplements (you set ShowSupplements to false at the request), you won't miss any important information.
- Supplements with pickup points will appear both in the Availability Response and in the Booking Rule response with the same format.
<Supplement id="TourC" type="M">
<Option>
<Code>TourC#0</Code>
<Name>City Tour, pickup Maximum Luxo Hotel</Name>
<Hour>09:00</Hour>
<Address>Hotel hall</Address>
</Option>
<Option>
<Code>TourC#1</Code>
<Name>City Tour, pickup Maximum Luxo Hotel </Name>
<Hour>11:30</Hour>
<Address>Hotel hall </Address>
</Option>
<Option>
<Code>TourC#2</Code>
<Name>City Tour, pickup Maximum Luxo Hotel </Name>
<Hour>15:00</Hour>
<Address>Hotel hall</Address>
</Option>
</Supplement>
In these cases you must select one option and sent its cod in the booking confirmation request.
If the desired booking is a direct payment booking, a node DirectPayment will appear with value true or 1. If the data is available, a list of accepted credit card types will appear in the AllowedCreditCards node.
<soap:Envelope>
<soap:Body>
<OTA_HotelBookingRuleServiceResponse>
<OTA_HotelBookingRuleRS>
<RuleMessage>
<BookingRules>
<BookingRule>
<TPA_Extensions>
…
<TotalPrice>220</TotalPrice>
<RequirePaxName>1</RequirePaxName>
<DirectPayment>1</DirectPayment>
<AllowedCreditCards xmlns="">
<Card codigo="VS">
<![CDATA["Visa"]]>
</Card>
<Card codigo="MC">
<![CDATA["Mastercard"]]>
</Card>
</AllowedCreditCards>
</TPA_Extensions>
</BookingRule>
</BookingRules>
</RuleMessage>
</OTA_HotelBookingRuleRS>
</OTA_HotelBookingRuleServiceResponse>
</soap:Body>
</soap:Envelope>
See the FAQ: When should we send the credit card? Which payment options are there? for more information about direct payment.
¶ OTA_HotelRes
Request: OTA_HotelResRq
Reponse: OTA_HotelResRs
Development URL: Request: OTA_HotelRes.asmx
SOAPAction for SOAP 1.1: http://www.opentravel.org/OTA/2003/05/OTA_HotelResV2Service
Important note:
At this step, it is not allowed to show information of the hotel previously stored in your system.
As explained in previous sections, there are two options to retrieve the final information of the booking:
- First option is to use the information returned in the response of the OTA_HotelAvail and OTA_HotelBookingRule transactions (hotel name, address, hotel category, ...).
- Second option is to show the information retrieved by the OTA_HotelDescriptiveInfo, but it is mandatory to include the RatePlanCode in the request of this transaction.
The message contains two parts:
- Reservation Data: including dates, room type, ages, name of passengers, hotel code and remarks.
- Passenger Data: including name, phone, identification, email and address.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResV2Service xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResRQ PrimaryLangID="en" Version="0" SequenceNmbr="Code123">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<UniqueID ID_Context="Your locator" />
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanCode="COMBINATION3" />
</RatePlans>
<RoomTypes>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="First" Surname="Passenger" />
<Guest Age="12" Name="Boy" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="Third" Surname="Passenger" />
<Guest Name="Fourth" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="Fifth" Surname="Passenger" />
<Guest Name="Sixth" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<TimeSpan End="2010-09-28" Start="2010-09-26" />
<BasicPropertyInfo HotelCode="JP633562" />
<Total CurrencyCode="USD" AmountAfterTax="220" />
<TPA_Extensions>
<ExpectedPriceRange min="0" max="230" />
</TPA_Extensions>
<Comments>
<Comment>
<Text>non-smoking rooms requested;king bed. This field allows 4000 characters</Text>
</Comment>
</Comments>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile ProfileType="1">
<Customer>
<PersonName>
<GivenName>Juniper</GivenName>
<Surname>Test</Surname>
</PersonName>
<Telephone PhoneNumber="971001122" />
<Document DocID="123123123" />
<Email>holder@email.com</Email>
<Address>
<AddressLine>My address</AddressLine>
<PostalCode>32837</PostalCode>
<CityName>Orlando</CityName>
<StateProv StateCode="FL">FLORIDA</StateProv>
<CountryName Code="US">USA</CountryName>
</Address>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<TPA_Extensions>
<MsgUser>1</MsgUser>
<VoucherUser>0</VoucherUser>
<Agent>Richard</Agent>
<AcceptOnly>OK</AcceptOnly>
<Supplements>
<Supplement id="CITYBUS" type="O" num="1" />
<Supplement id="TourC" type="M" option="TourC#2" />
</Supplements>
<Preferences>
<Preference Code="200075169~200449792~NS" />
</Preferences>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
</OTA_HotelResV2Service>
</soap:Body>
</soap:Envelope>
¶ Extended information
- It is important to note that the OTA_HotelRes TPA_Extensions branch from the HotelReservation node:
<HotelReservations>
<HotelReservation>
<UniqueID/>
<RoomStays>…</RoomStays>
<ResGuests>…</ResGuests>
<TPA_Extensions>
<PaxCountry>ES</PaxCountry>
<MsgUser>1</MsgUser>
<AcceptOnly>OK</AcceptOnly>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
- Attribute SequenceNmbr must have the same value of SequenceNmbr attribute obtained in the OTA_HotelAvail response.
- Attribute TimeStamp is an optional field where you can send your own timestamp. It will be shown in the booking history log.
- UniqueID/@ID_Context is an optional field where you can send your booking identification. It can be a locator, an agent reference, a code that allows you to identify the reservation, etc. This field only allows 50 characters (its length may be shorter depending on the provider).
NOTE: On some cases, depending on your account configuration, this value can be mandatory. - TPA_Extensions/PackageID is an optional field where you can send a numeric package identifier.
- You have to specify the names of all passengers (node RoomTypes) apart from the holder (see next point). In some cases (if RequirePaxName is ‘false’ or ‘0’ in the OTA_HotelBookingRule response) they can be omitted. In case of doubt, include the passenger names in all cases.
- You may also have to specify the document type and document number of all passengers (node RoomTypes) apart from the holder (see next point). In some cases (if RequirePaxDocumentType and/or RequirePaxDocumentNumber are ‘true’ or ‘1’ in the OTA_HotelBookingRule response) it will be mandatory to specify the document type and/or document number on all of the passengers:
Click to see the example
<RoomTypes>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="First" Surname="Passenger">
<Document DocType="1" DocID="12345678A" />
</Guest>
<Guest Name="Boy" Surname="Passenger" Age="12">
<Document DocType="1" DocID="23456789B" />
</Guest>
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
- ResGuests/ResGuest/Profiles/ProfileInfo/Profile/Customer contains information about the holder of the reservation. Only GivenName and Surname are mandatory. The rest of parameters are optional.
- RoomType elements must be in order.
For example, if you specified in the availability request the first room to be a double with one child, and the second and third one a double, do not put a double in the first place. Moreover, place the double with one child in the first place (first RoomType node) and do not mix RoomType elements among them. - Remember that guests older than 18 will be considered adults.
- RatePlanCode attribute must be exactly the same as returned in the OTA_HotelBookingRule response.
Moreover, you must use the same data that you asked in the availability request. If not, an error will be thrown.
For example, if you search for 2 rooms, your reservation will have to be for 2 rooms. If you add one room and try to book 3 rooms using the RatePlanCode from the 2 room availability, it will give you an error. The same applies to dates, passengers and other info.
In this case, you have to do another search for 3 rooms and use the new RatePlanCode code (apart of the new SequenceNmbr value obtained) - Total node is mandatory and it has the value of the expected price with its currency.
ExpectedPriceRange node is optional, and you can indicate the accepted price range. It can be useful if you decide to make the reservation time after making the availability search and prices may have changed. If you don’t specify ExpectedPriceRange node and at least one of its attributes, it will take the AmountAfterTax attribute in Total. If the price of the reservation is greater or lower than the expected price, reservation won’t be made.
Take this 3 cases as example:- If you expect 220.50 $ (important to note that these prices have to use a decimal mark) but accept a margin of 10 $, you can specify a range of 0 $ - 230.50 $ so reservation will be done if price is lower than 230.50 $. If it costs 231 $, it won’t be done.
- If you specify a minimum range of 0 but do not specify a maximum range, reservation will be done if price is equal or lower than 220.50 $, the initial expected price. If it is greater, it won’t be done.
- If you don’t specify a range, reservation will be made if price is exactly 220.50 $. If it costs 219 $ or 221 $ it won’t be done.
NOTE: The ExpectedPriceRange will use the price returned on the price verification step (where it will work as explained) but if by any chance the hotel changes the price between the price verification and the booking confirmation attempt the system will also accept any new price with a maximum price difference of 0,5%.
- Customer node is meant to send personal details of the holder (or main passenger) of the booking. It is only mandatory to send the name and the surname, but it is highly recommended to add some additional details, such as a contact email, a telephone number, the address, etc.
- If any RequireXXX field has been returned as 1 (true) in OTA_HotelBookingRule, then it is mandatory to send this information regarding the passengers or the booking holder. It includes names and surnames, address, postal code, city, nationality and telephone number.
Regarding cpuntry and besides its name, it is also important to send the correct country code (@Code), which defines the customer nationality. The correct codes can be obtained from the transaction JP_ZoneList, node Zone[@IATA]. - The MsgUser boolean node is optional and allows you to control the automatic confirmation message sent to your email account. By default it is deactivated, so no confirmation message will be send.
- The VoucherUser boolean node is optional, and allows you to send a confirmation email with the voucher to the email account of the reservation holder, if specified (ProfileInfo/Profile/Customer/Email). By default it is deactivated, so no confirmation message will be send.
- The Agent node is optional. Indicates the agent name that made the reservation.
- The AcceptOnly node is optional. If specified, it can have the values OK or RQ. If it is specified, the reservation will only be confirmed if its status is the same as the requested.
For example, if you use, if you use AcceptOnly=OK and the reservation is on request (because some booked the last room before you), the reservation will fail with a RESERVATION_FAILS_STATUSNOTCORRECT error (and won’t be made). In this way you can prevent undesired on request bookings.
If not specified, no status checking will be performed. - You can add additional Supplements (retrieved in the OTA_HotelBookingRule). You can only add optional supplements as mandatory supplements are already included, and
restrictions are only for informative purposes. The only exceptions to this rule are supplements with selectable options (like pickup points). In this case you must choose one option from the list retrieved in the availability response.
You just have to indicate the id, the type and that you selected the same (num=”1”). For supplements with options, you have to indicate the selected option instead.
Please take into account that if the supplement is not a direct payment supplement, you have to add its price at the expected price value or you will get a price error. - You can add Preferences (retrieved from the OTA_HotelBookingRule). In order to do so you just have to indicate the retrieved @Code.
- You can retrieve the commission and nett price of the reservation, with the following parameters in the confirmation request (at the same level of the other parameters): ShowCommission, ShowNettPrice.
- If you want to retrieve the supplements applied to the booking, use the parameter ShowSupplements in the request.
- If you want to send the Giata code of the booked hotel instead of the internal one, use the parameter IsGiataHotelCode in the request.
- If you included the PaxCountry in the availability request, it's mandatory to set the same PaxCountry in the booking request.
<HotelReservations>
<HotelReservation>
<UniqueID/>
<RoomStays>…</RoomStays>
<ResGuests>…</ResGuests>
<TPA_Extensions>
<PaxCountry>ES</PaxCountry>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
- If you included the PackageContracts in the availability request, it’s mandatory to set the same PackageContracts option in the booking request.
<HotelReservations>
<HotelReservation>
<UniqueID/>
<RoomStays>…</RoomStays>
<ResGuests>…</ResGuests>
<TPA_Extensions>
<PackageContracts>Package</PackageContracts>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
The response indicates cancellation policy, total amount, rate description and most important, we get the booking code(s):
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResV2ServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResRS>
<Success/>
<HotelReservations>
<HotelReservation ResStatus="Pag">
<UniqueID ID="JR5Y2Z" ID_Context="Your locator" />
<RoomStays>
<RoomStay IndexNumber="123">
<RoomTypes>
<RoomType>
<RoomDescription>
<Text>Twin room</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Name="First" Surname="Passenger" Age="40" />
<Guest Name="Boy" Surname="Passenger" Age="12" />
</Guests>
</TPA_Extensions>
</RoomType>
<RoomType>
<RoomDescription>
<Text>Twin room</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Name="Third" Surname="Passenger" Age="40" />
<Guest Name="Fourth" Surname="Passenger" Age="40" />
</Guests>
</TPA_Extensions>
</RoomType>
<RoomType>
<RoomDescription>
<Text>Suite</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Name="Fifth" Surname="Passenger" Age="40" />
<Guest Name="Sixth" Surname="Passenger" Age="40" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanName="Room only" />
</RatePlans>
<TimeSpan Start="2010-09-26" End="2010-09-28" />
<CancelPenalties>
<CancelPenalty>
<PenaltyDescription>
<Text>Cancelling 3 days before check-in has a cancellation cost of 1 night</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<Total AmountAfterTax="220.00" CurrencyCode="USD" DecimalPlaces="2" />
<BasicPropertyInfo HotelCode="7bOrLYZEqj9yfyClLMcpE77a4QrbPq5txD7d2kUO1EE=" JPCode=" JP046542" HotelName="Maximum Luxo Hotel Resort and Spa ">
<VendorMessages>
<VendorMessage Title="ImportantInfo">
<SubSection>
<Paragraph>
<Text>Resort Fee: A $2.75 resort fee per room; per day is not included in the rate and will be paid by the guest directly to the hotel at checkout.</Text>
</Paragraph>
</SubSection>
</VendorMessage>
</VendorMessages>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Juniper</GivenName>
<Surname>Test</Surname>
</PersonName>
<Telephone PhoneNumber="971001122" />
<Document DocID="123123123" />
<Email>holder@email.com</Email>
<Address>
<AddressLine>My address</AddressLine>
<PostalCode>32837</PostalCode>
<CityName>Orlando</CityName>
<StateProv StateCode="FL">FLORIDA</StateProv>
<CountryName Code="US">USA</CountryName>
</Address>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Total AmountAfterTax="220.00" CurrencyCode="USD" DecimalPlaces="2" />
<HotelReservationIDs>
<HotelReservationID ResID_Value="JR5Y2Z" ResID_Date="2010-09-23T11:21:10.81" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<Delegation>
<Name>Mallorca</Name>
<Phone>+34 971123456</Phone>
<Fax>>+34 971654321</Fax>
<Address>31 diciembre, 27 - Palma de Mallorca</Address>
<Email>delegation@email.com</Email>
<TimeTable>10:00 - 20:00</TimeTable>
<Remarks/>
</Delegation>
<ExternalReference>195636</ExternalReference>
<ElementStatus>OK</ElementStatus>
<ExpirationDate>2010-09-25T12:00:00</ExpirationDate>
<Payable>Juniper Travel</Payable>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</OTA_HotelResV2ServiceResponse>
</soap:Body>
</soap:Envelope>
Notes:
- ResID_Value attribute (in HotelReservationID node) is the booking code you have to use in order to cancel, read or modify the booking.
- TPA_Extensions/Delegation node indicates information concerning the delegation in which the reservation has been made. It contains attributes as name, phone and fax numbers, email and physical address, etc.
- TPA_Extensions/ExternalReference, TPA_Extensions/Payable and TPA_Extensions/PayableTaxReference attributes are optional.
They contain information that may be displayed in the voucher. See the AQ for more information.- TPA_Extensions/HotelGiataCode will display the Giata code of the hotel (if available). Needs the option IsGiataHotelCode.
- ResStatus attribute indicates the state of the booking. See the Read reservation section to find more details about this attribute.
- If the reservation is a pre-payment reservation, an ExpirationDate node will be returned. This node contains the date when the reservation will be cancelled if not paid. For more info, please see the FAQ section: When should we send the credit card? Which payment options there are?”
- If the reservation has a recommended price, it will be returned in the HotelReservation/TPA_Extensions/RecommendedPrice.
Click to see the example
<TPA_Extensions>
<ExternalReference>195636</ExternalReference>
<ElementStatus>OK</ElementStatus>
<ExpirationDate>2010-09-25T12:00:00</ExpirationDate>
<Payable>Juniper Travel</Payable>
<RecommendedPrice>250.00</RecommendedPrice>
...
</TPA_Extensions>
- If you ask for the commission and nett price, you will get it a this level:
If the booking as already nett prices, the commission will be 0 and nett price will have the same value as the Total[@AmountAfterTax] attribute.
Click to see the example
<TPA_Extensions>
<ExternalReference>195636</ExternalReference>
<ElementStatus>OK</ElementStatus>
<ExpirationDate>2010-09-25T12:00:00</ExpirationDate>
<Payable>Juniper Travel</Payable>
<Commission>25.00</Commission>
<NettPrice>225.00</NettPrice>
</TPA_Extensions>
- For further information about the HotelReservatio/TPA_Extensions nodes, please see the OTA_Read section.
¶ Credit card payment
In some scenarios (your account being configured to require credit card payments, or simply confirming a direct-payment reservation), you will need to send credit card information along with its confirmation. When this is the case, it will be required for you to send this information or the booking confirmation request will fail (ERR_INVALIDCREDITCARD).
Below you will be able to find an example of the nodes that are required and on its placement:
Click to see the example
<Customer>
<PersonName>
<GivenName>Juniper</GivenName>
<Surname>Test</Surname>
</PersonName>
<Telephone PhoneNumber="971001122" />
<Email>holder@email.com</Email>
<Address>
<AddressLine>My address</AddressLine>
<CityName>Palma Mallorca</CityName>
</Address>
<PaymentForm>
<PaymentCard CardCode="VI" CardNumber="41111111111111" SeriesCode="123" ExpireDate="01/09">
<CardHolderName>Salad</CardHolderName>
<CardHolderSurname>Fingers</CardHolderSurname>
<CardHolderEmail>somewhereoverthe@rainbow.com</CardHolderEmail>
<Address>
<AddressLine>999th Happy Tree Friends Street</AddressLine>
<CityName>Alexandria</CityName>
<PostalCode>38921</PostalCode>
<StateProv StateCode="VA"/>
<CountryName Code="US"/>
</Address>
</PaymentCard>
</PaymentForm>
</Customer>
Some of the attributes that you will be able to find within the PaymentCard node here are:
- CardCode: Credit card type code. It is important to understand that this is a sample of credit card type codes, and that the actual list of supported card type codes will always depend on your supplier reason for which, if you are interested on performing these kind of payments, it will be necessary for you to clarify the list of supported card type codes directly with your supplier. Possible values:
- AX: Americn Express.
- CB: Carte Blanche.
- DC: Diners Club.
- DS: Dicover Card.
- ER: enRoute.
- MC: Master Card.
- VI: Visa.
- ExpireDate: Expiration date of the credit card. Follows the mm/yy format.
For further information in this regard, kindly refer to the following FAQ section: When should we send the credit card? Which payment options are there?
¶ OTA_Read
Request: OTA_ReadRq
Response: OTA_ReadRs
Development URL: OTA_Read.asmx
SOAPAction for SOAP 1.1: "http://www.opentravel.org/OTA/2003/05/OTA_ReadService"
In this message you need to send the booking number and the authentication in order to retrieve all information from one or more bookings. The response is similar to the OTA_HotelRes.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_ReadService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_ReadRQ PrimaryLangID="en" Version="0">
<POS>
<Source AgentDutyCode="email@domain.com">
<RequestorID Type="1" MessagePassword="test" />
</Source>
</POS>
<ReadRequests>
<ReadRequest>
<UniqueID ID="OCG7AS" />
</ReadRequest>
</ReadRequests>
</OTA_ReadRQ>
</OTA_ReadService>
</soap:Body>
</soap:Envelope>
Apart of filter by locator, you can also use the other filters in the Verification node:
- HolderName: Allows you to search by the holder name of the resrevation.
- AgencyReference: Allows you to retrieve reservations by your referene (ID_Context in the OTA_HotelRes.
- ResStatus: Alows you to filter by status of the reservation (see below for a list of available status). You can specify more than one, separated by commas.
- ReservationFrom/ReservationTo: Filters by reservation creation date.
- TravelFrom/TravelTo: Filters by reservation travel date.
- ModificationFrom/ModificationTo: Filters by modification date.
- CancellationFrom/CancellationTo: Filters by cancellation date.
- ShowCommission: By default false, this boolean parameter let you retrieved the commission.
- ShowNettPrice: By default false, this boolean parameter let you retrieved the nett price.
For example, if you want to search for cancelled reservations made on July 2009 for travelling on September onwards:
Click to see the example
<ReadRequests>
<ReadRequest>
<Verification>
<TPA_Extensions>
<TravelFrom>2009-09-01</TravelFrom>
<ResStatus>Can,CaC</ResStatus>
<ReservationFrom>2009-07-01</ReservationFrom>
<ReservationTo>2009-07-31</ReservationTo>
</TPA_Extensions>
</Verification>
</ReadRequest>
</ReadRequests>
If you want to search for all reservation with agency reference Ref123 made for the passenger John Doe:
Click to see the example
<ReadRequests>
<ReadRequest>
<Verification>
<TPA_Extensions>
<HolderName>John Doe</HolderName>
<AgencyReference>Ref123</AgencyReference>
</TPA_Extensions>
</Verification>
</ReadRequest>
</ReadRequests>
You can also send the ShowSupplemnts option with value 1 or true in order to retrieve the list of applied supplements:
Click to see the example
<ReadRequests>
<ReadRequest>
<Verification>
<TPA_Extensions>
<ShowSupplements>1</ShowSupplements>
…
</TPA_Extensions>
</Verification>
</ReadRequest>
</ReadRequests>
The response will contain all reervations that fit the requested filters.
It has three important blocks of information:
< HotelReservation >
Here we will obtain the details of the room booked, ges, dates and info from the hotel.
The ResStatus attribute indicates the status of the booking. Possible values are:
- Pag/Ok: Reservation confirmed and paid.
- Con: Reservation confirmed.
- Tar: Reservation confirmed (if pending credit card charge).
- Can/CaC: Reservation cancelled.
- PRe/PDi: Reservation on request.
- Ini: Initialized but not confirmed.
It is very important to check the ResStatus attribute in order to verify the booking is confirmed.
For more information, please refer to the FAQ: I send a booking confirmation but I receive it with status Can (cancelled) or PRe (on request). Why?
Please, note that you can get more information about the hotel combining this message with OTA_HotelDescriptiveInfo.
-
< Guests >
Retrieves personal data from the owner of the booking. -
< ResGlobalInfo >
Retrieves total amount, currency and booking number.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_ReadServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_ResRetrieveRS Version="0">
<Success/>
<ReservationsList>
<HotelReservation ResStatus="Can">
<UniqueID ID=" OCG7AS" ID_Context="23594" />
<RoomStays>
<RoomStay IndexNumber="2579">
<RoomTypes>
<RoomType>
<RoomDescription>
<Text>Fourbedded room (2A+0a+2n)</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Age="40" Name="First" Surname="Passenger" />
<Guest Age="40" Name="Second" Surname="Passenger" />
<Guest Age="08" Name="Third" Surname="Passenger" />
<Guest Age="06" Name="Fourth" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanName="Bed and breakfast" />
</RatePlans>
<TimeSpan Start="2008-10-11" End="2008-10-12" />
<Total AmountAfterTax="0" CurrencyCode="EUR" DecimalPlaces="2" />
<BasicPropertyInfo HotelCode="7bOrLYZEqj9yfyClLMcpE77a4QrbPq5txD7d2kUO1EE=" JPCode=" JP046542" HotelName="Hotel Maximum Luxo" />
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Homer</GivenName>
<Surname>Simpson</Surname>
</PersonName>
<Email>testemail@domain.com</Email>
<Address>
<CountryName/>
</Address>
<Document/>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Total AmountAfterTax="500" CurrencyCode="USD" />
<HotelReservationIDs>
<HotelReservationID ResID_Value="OCG7AS" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<ElementStatus>CA</ElementStatus>
<CancellationCost CurrencyCode="EUR">0.00</CancellationCost>
</TPA_Extensions>
</HotelReservation>
</ReservationsList>
</OTA_ResRetrieveRS>
</OTA_ReadServiceResponse>
</soap:Body>
</soap:Envelope>
The ResGlobalInfo contains information about the whole booking (locator, total price, etc).
The HotelReservation/TPA_Extensions node contains information about one element of the reservation. For more information about elements, please refer to the following section Reservations with more than one element.
The following nodes can be retrieved:
- ElementStatus: Possible values are:
- OK: Confirmed.
- RQ: On request.
- AV: Available (but pending, a similar status to “On Request”).
- CA: Cancelled.
- SO: Sold out (cancelled because there is no allotment).
- RP: Element replaced by another one.
- CancellationCost: If the element is cancelled, and there is information about the cancellation penalty, this node will return information about this cost.
Sometimes this information is not available and the node is missing. - SubstituteElement: If the element is replaced by another one (for example a hotel redirection), this node will give you information about the new element. For more information about redirections, please refer to the following section Reservations with more than one element.
- Payable: If present, this node will give you information about who pays the reservation to the hotel. This information has to be shown on voucher.
- PayableTaxReference: If present, this node will give you information about the payable tax reference.
- EarlyBooking: If present, this node will give you information about who pays the reservation to the hotel. This information has to be shown in the voucher.
- ExternalReference: If present, this node will give you the reference of the supplier. This information has to be shown in the voucher.
- EarlyBooking: It will come up as a result if you send the “Show Supplements” option with value 1 or true and if the booking has an Early Booking offer with payment conditions.
This node will give you the information about the Early Booking payment conditions:- Percentage: The percentage value that will apply to the sales booking value and which result will be the amount to pay.
- CostValue: The amount to pay as a fixed value.
- PaymentDate: The dte in which the payment is due.
For example with percentage:
Click to see the example
<TPA_Extensions>
...
<EarlyBooking xmlns="">
<Percentage>15</Percentage>
<PaymentDate>25/10/2008</PaymentDate>
</EarlyBooking>
</TPA_Extensions>
For example with fixed price:
Click to see the example
<TPA_Extensions>
...
<EarlyBooking xmlns="">
<CostValue>105.25EUR</CostValue>
<PaymentDate>25/10/2008</PaymentDate>
</EarlyBooking>
</TPA_Extensions>
It is very important to check this node, because if it is empty, it means that there isn't any early booking offer configured with payment conditions.
¶ Reservations with more than one element
Each reservation is composed by one or more elements.
For example, you could have a hotel and a transfer or a flight (contact Juniper for more information about these products), or a hotel may have been redirected to another one.
in this casem each element will appear as a different reservation with the same locator.
In the following examle the reservation 8LRT43 has two hotel reservations, 15129 and 16589.
The first one is cancelled because had to be redirected to the second one, 16589.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_ReadServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_ResRetrieveRS Version="0">
<Success/>
<ReservationsList>
<HotelReservation ResStatus="Pag">
<UniqueID ID="8LRT43" ID_Context="77496109" />
<RoomStays>
<RoomStay IndexNumber="15129">
<RoomTypes>
<RoomType>
<RoomDescription>
<Text>Double Bed</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Age="40" Name="First" Surname="Passenger" />
<Guest Age="40" Name="Second" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanName="Bed and breakfast" />
</RatePlans>
<TimeSpan Start="2008-10-11" End="2008-10-12" />
<Total AmountAfterTax="0" CurrencyCode="EUR" DecimalPlaces="2" />
<BasicPropertyInfo HotelCode="7bOrLYZEqj9yfyClLMcpEd2kUO1EE=" JPCode="JP046542" HotelName="Hotel Maximum Luxo" />
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Homer</GivenName>
<Surname>Simpson</Surname>
</PersonName>
<Email>testemail@domain.com</Email>
<Address>
<CountryName/>
</Address>
<Document/>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Total AmountAfterTax="1500" CurrencyCode="USD" />
<HotelReservationIDs>
<HotelReservationID ResID_Value="8LRT43" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<ElementStatus>RP</ElementStatus>
<SubstituteElement>16589</SubstituteElement>
<CancellationCost CurrencyCode="EUR" xmlns="">0.00</CancellationCost>
</TPA_Extensions>
</HotelReservation>
<HotelReservation ResStatus="Pag">
<UniqueID ID="8LRT43" ID_Context="77496109" />
<RoomStays>
<RoomStay IndexNumber="16589">
<RoomTypes>
<RoomType>
<RoomDescription>
<Text>Double Bed</Text>
</RoomDescription>
<TPA_Extensions>
<Guests>
<Guest Age="40" Name="First" Surname="Passenger" />
<Guest Age="40" Name="Second" Surname="Passenger" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanName="Bed and breakfast" />
</RatePlans>
<TimeSpan Start="2008-10-11" End="2008-10-12" />
<Total AmountAfterTax="1500" CurrencyCode="EUR" DecimalPlaces="2" />
<BasicPropertyInfo HotelCode="7bOrLYZEqj9yfyClLMcpE77a4QrbPq5txD7d2kUO1EE=" JPCode=" JP046542" HotelName="Hilton Paris" />
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Homer</GivenName>
<Surname>Simpson</Surname>
</PersonName>
<Email>testemail@domain.com</Email>
<Address>
<CountryName/>
</Address>
<Document/>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Total AmountAfterTax="1500" CurrencyCode="USD" />
<HotelReservationIDs>
<HotelReservationID ResID_Value="OCG7AS" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<ElementStatus>OK</ElementStatus>
</TPA_Extensions>
</HotelReservation>
</ReservationsList>
</OTA_ResRetrieveRS>
</OTA_ReadServiceResponse>
</soap:Body>
</soap:Envelope>
¶ OTA_Cancel
Request: OTA_CancelRq
Response: OTA_CancelRs
Development URL: OTA_Cancel.asmx
SOAPAction for SOAP 1.1: "http://www.opentravel.org/OTA/2003/05/OTA_CancelService"
In this message you need to send the booking number and authentication in order to cancel a booking.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_CancelService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_CancelRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID Type="1" MessagePassword="pass"/>
</Source>
</POS>
<UniqueID ID="UKHDFS" />
</OTA_CancelRQ>
</OTA_CancelService>
</soap:Body>
</soap:Envelope>
The WebService will respond with a success code if everything works well. Otherwise and if the booking cannor be cancelled (maybe because it was already canceled) it will respond with an error code.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_CancelServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_CancelRS>
<Success/>
<UniqueID/>
<Warnings>
<Warning Type="9" ShortText="Cancellation cost retrieved. Reservation was cancelled.">0.00 USD
</Warning>
</Warnings>
</OTA_CancelRS>
</OTA_CancelServiceResponse>
</soap:Body>
</soap:Envelope>
If you only want to get the cancellation costs of the reservation, withput cancelling the reservation, you may send:
Click to see the example
<soap:Envelope xmlns:soap = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_CancelRQ>
<POS>
<Source AgentDutyCode = "username@mydomain.com">
<RequestorID Type = "1" MessagePassword = "pass"/>
</Source>
</POS>
<UniqueID Type = "14" ID = "UKHDFS"/>
<TPA_Extensions>
<GetOnlyCancellationCost>1</GetOnlyCancellationCost>
<MsgUser>1</MsgUser>
</TPA_Extensions>
</OTA_CancelRQ>
</soap:Body>
</soap:Envelope>
If you only want to cancel an specific booking line without cancelling the entire booking, you may add the booking line with the booking code separated with "-":
Click to see the example
<soap:Envelope xmlns:soap = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_CancelRQ>
<POS>
<Source AgentDutyCode = "username@mydomain.com">
<RequestorID Type = "1" MessagePassword = "pass"/>
</Source>
</POS>
<UniqueID Type = "14" ID = "UKHDFS-24343"/>
</OTA_CancelRQ>
</soap:Body>
</soap:Envelope>
Lastly, if you want to cancel the entire booking if there is only one booking line active:
Click to see the example
<soap:Envelope xmlns:soap = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd = "http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_CancelRQ>
<POS>
<Source AgentDutyCode = "username@mydomain.com">
<RequestorID Type = "1" MessagePassword = "pass"/>
</Source>
</POS>
<UniqueID Type = "14" ID = "UKHDFS-24343"/>
<TPA_Extensions>
<CancelWholeResIfLastElement xmlns = "">1</CancelWholeResIfLastElement>
</TPA_Extensions>
</OTA_CancelRQ>
</soap:Body>
</soap:Envelope>
Notes:
- In case that you have to use credit card and there is no virtul POS, credir card will be stored and the reservation will be pending of manual charge. This is indicated with the status Tar (see next point Read a reservation). In this status, you have to wait for the credit card charge and meanwhile cancellation won’t be possible.
- By default, no cancellation messages will be sent to your email account. If you want to receive them, you can use the MsgUser option.
- A Warning node will be returned with information about the cancellation costs.
- If available, it will appear: Cancellation cost retrieved. Reservation was cancelled.
The value of the node will be the cancellation cost plus the currency.- If not available, it will appear: Cancellation cost could not be calculated. Reservation was cancelled and it is pending of cancellation cost.
- If you want to retrieve the cancellation costs with the GetOnlyCancellationCost option, a Warning node will be returned with information about the cancellation costs.
- If available, it will appear: Cancellation cost retrieved. Reservation was not cancelled.
The value of the node will be the cancellation cost plus the currency.- If not available, it will appear: Cancellation cost could not be calculated. Reservation was not cancelled.
¶ OTA_HotelResModify
Request: OTA_HotelResModifyRq
Response: OTA_HotelResModifyRs
Development URL: OTA_HotelResModify.asmx
SOAPAction for SOAP 1.1: "http://www.opentravel.org/OTA/2003/05/OTA_HotelResModifyService"
Booking modification allows you to directly modify the following parameters, without having to cancel a booking (or a booking element) and then having to make a brand new booking again:
- Occupancy: It allows modifying the occupancy of the reservation. If this option is taken, it always implies quoting again (it is as if there were a cancellation and a new booking).
This option also implies choosing the type of board and room again and specifying the name of guests again too. - Type of board, contract or room. It allows modifying the type of room, board or contract.
This option always implies a new quotation. - Dates. It allows changing arrival and departure dates.
This option always implies a new quotation. - Name of guests: It allows changing the name of guests or the lead passenger.
- Supplements: It allows to modify supplements.
Any modification where the hotel has change will always imply cancelling and booking again.
These modifications are limited by the provider. If a provider does not allow a particular data to be changed, that parameter will not be available for modification.
By default, the bookings within cancellation costs associated will not be available for modification, as possible expenses should be taken into account, and that should be done manually.
This transaction offers the following functionalities:
¶ New Availability Search
*OTA_HotelAvail can be used to list the available options. A normal availability request should be sent, returning all the data (hotel, dates, occupancy) and the booking code of the booking to be modified.
This is the difference with a normal availability; the booking to be modified should be specified so as to take into account the existing capacity, to avoid quoting again if it is possible.
In order to do so, it must be shown the id of the booking line to be modified in the node Criterion, attribute @InfoSource.
An example of the use of this attribute is shown next:
Click to see the example
<HotelSearchCriteria>
<Criterion InfoSource="41765">
<HotelRef HotelCode="HBE|123" />
<TPA_Extensions>
<ShowBasicInfo>1</ShowBasicInfo>
<ShowPromotions>1</ShowPromotions>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
This call to the OTA_HotelAvail transaction may be omitted of all the parameter to be modified re known: guest names, dates, etc. in this case, we can step into the New Booking phase directle. It is described next.
¶ New Booking
It is possible to send directly an OTA_HotelResModify request if all the parameters are known: nre dates (or the same if they do not change), the code or combination of the chosen availability, the booking code to be modified, etc.
There is a node that shows whether it is a real modification or whether only the final price of the modiication is being required. The possible values that this node EndTransaction accepts are the following:
- E (from End), if it is the case of a real modification.
- I (from Ignore)if only the price of the modification is desired. The booking won't bt modified in this case.
Is all the parameters to be modified are known: guests, names, dates, etc. In thi case, we can step into the New Booking phase directly.
XML sample of an OTA_ResModify request to add one night just for knowing the rate
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResModifyService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResModifyRQ PrimaryLangID="es" Version="0">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID MessagePassword="pass" />
</Source>
</POS>
<HotelResModifies>
<HotelResModify>
<UniqueID ID="F1GFSV" />
<RoomStays>
<RoomStay IndexNumber="52333">
<TimeSpan Start="2013-10-20" End="2013-10-25" />
</RoomStay>
</RoomStays>
<TPA_Extensions>
<EndTransaction>I</EndTransaction>
</TPA_Extensions>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRQ>
</OTA_HotelResModifyService>
</soap:Body>
</soap:Envelope>
The attribute ID in the node UniqueId refers to the booking locator received in the first booking confirmation.
IndexNumber attribute must contain the id of the booking line to be modified. it is obtained from the node Criterion, attribute @InfoSource of th OTA_HotelRes response.
Finally, this request must specify the new search criteria in the same way they are set in the initial availability request. In this example, it has been added one more night respect from the initial stay.
XML sample of an OTA_ResModify request to change the type of room and passengers name. To confirm modification.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResModifyService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResModifyRQ PrimaryLangID="es" Version="0">
<POS>
<Source AgentDutyCode="username@mydomain.com">
<RequestorID MessagePassword="pass" />
</Source>
</POS>
<HotelResModifies>
<HotelResModify>
<UniqueID ID="JLCTKD" />
<RoomStays>
<RoomStay IndexNumber="52337">
<RoomTypes>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="ChangedName_1" Surname="ChangedSurname_1" />
<Guest Name="ChangedName_2" Surname="ChangedSurname_2" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="QxLfxD4K5VHoP/tMLC5fsjpXBk1cVYoFQ0WUPF6UhHMVCmtps4fbuBaVU8kRoz9SjcFtQs74EMh51xJ3DfTcugYWoO2I3637QIJU61nLqx0c9arBDpa/sTphlxmPgIMtE3AK+SN/dU09VNdL2PO1ZQ==" />
</RatePlans>
<RoomRates/>
<BasicPropertyInfo HotelCode="HBE|341" />
</RoomStay>
</RoomStays>
<TPA_Extensions>
<EndTransaction>E</EndTransaction>
</TPA_Extensions>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRQ>
</OTA_HotelResModifyService>
</soap:Body>
</soap:Envelope>
This result updates the name of the passengers and returns the new rates including the change of the type room.
it is important to specify the new RatePlanCode. It should contain the changes wwe want to apply to the booking (change of room, type, board type, etc) and that are not specified in other parts of the code, as the passeger names. It can be obtained sending a nre availability requet ibcluding the attribute @InfoSource.
With the @EndTransaction node in the TPA_Extensions we indicate the action to be taken. As it was explained before, these are the possible values.
- E (from End), if it is the case of a real modification.
- I (from Ignore)if only the price of the modification is desired. The booking won't bt modified in this case.
OTA_ResModify response just informing about the new rates.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResModifyServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResModifyRS URL="http://xml-uat.bookingengine.es/webservice/OTA_HotelResModify.asmx" IntCode="VoPPt/IWys0tXPCY9FL2zA==" TimeStamp="2013-09-20T15:20:24.5860883+02:00" Version="0">
<Success/>
<Warnings>
<WarningType Type="3" ShortText="Modification changes ignored. Showing modification cost." />
</Warnings>
<HotelResModifies>
<HotelResModify ResStatus="Pag">
<RoomStays>
<RoomStay IndexNumber="52333">
<Total AmountAfterTax="805" CurrencyCode="USD" DecimalPlaces="2" />
</RoomStay>
</RoomStays>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="F1GFSV" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<ElementStatus xmlns="">OK</ElementStatus>
</TPA_Extensions>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRS>
</OTA_HotelResModifyServiceResponse>
</soap:Body>
</soap:Envelope>
If the request has been sent just knowing the new rates after the modification, it will return a Warning node indicating thet the booking has not beed modified.
Also, the ID of the booking line to be modified will be returned in the attribute @IndexNumbers of the RoomStay node.
The rest of the nodes will have the same aspect than in the OTA_HotelRes response.
OTA_ResModify response after modifying the type of room and passengers name. Booking has been updated with the new data.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResModifyServiceResponse xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResModifyRS URL="http://xml-uat.bookingengine.es/webservice/OTA_HotelResModify.asmx" IntCode="7P/jcGobH2O8izzLcOODVA==" TimeStamp="2013-09-20T15:50:48.057691+02:00" Version="0">
<Success/>
<HotelResModifies>
<HotelResModify ResStatus="Pag">
<RoomStays>
<RoomStay IndexNumber="52337">
<Total AmountAfterTax="175.32" CurrencyCode="USD" DecimalPlaces="2" />
</RoomStay>
</RoomStays>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="JLCTKD" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<ElementStatus xmlns="">OK</ElementStatus>
</TPA_Extensions>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRS>
</OTA_HotelResModifyServiceResponse>
</soap:Body>
</soap:Envelope>
The response of the OTA_HotelResModify returns the main info of the Booking just modifies. This is:
- ResStatus attribute indicates the state of the booking. See the Read reservation section to find more details about this attribute.
- IndexNumber refers to the ID of the booking line that has just been modified.
- AmountAfterTax is new rate of he modified booking.
- ResID_Value is the booking code you have to use in order to cancel, read or modify the booking.
In order to retrieve the complete updted information of the booking, you should call again the transaction OTA_Read.
¶ OTA Complete Process
With OTA_HotelAvail you can make request availability:
Click to see the example
<OTA_HotelAvailService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelAvailRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@test.com">
<RequestorID MessagePassword="password" />
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<StayDateRange Start="2012-03-09" End="2012-03-12" />
<RoomStayCandidates>
<RoomStayCandidate Quantity="1">
<GuestCounts>
<GuestCount Age="40" Count="2" />
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCode="HBE|107" />
<TPA_Extensions>
<ShowBasicInfo xmlns="">1</ShowBasicInfo>
<ShowPromotions xmlns="">1</ShowPromotions>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</OTA_HotelAvailService>
As a response you will receive a RatePlanCode. This is an encrypted cod to obtain booking rules with OTA_HotelBookingRule and to complete the booking with the OTA_HotelRes
Click to see the example
<RoomRate RatePlanCode = "44vE0QwKgeMUBhxVxmgjvm6CmpMPeOgkSCSgkXtLJM9XMUVa9p/g41ImH26HwQIKJ5APMT/QbZvCUtj78Di4nA==" RatePlanCategory = "Bed & Breakfast" AvailabilityStatus = "AvailableForSale">
<Rates>
<Rate NumberOfUnits = "1" RateMode = "Room" RateSource = "1">
<Total AmountAfterTax = "159.48" DecimalPlaces = "2"/>
<RateDescription>
<Text>Double Room</Text>
</RateDescription>
<TPA_Extensions>...</TPA_Extensions>
</Rate>
</Rates>
...
</RoomRate>
It is always recommended to implement OTA_HotelBookingRule and it is mandatory for some specific hotels which can suffer significant changes between the availability and the policy cancellation transactions. You can check if it is mandatory in the tag TPA_Extensions / MandatoryBookingRule from the response of OTA_HotelAvail.
We advise to call it in order to obtain the cancllation policy and hotel / provider comments. You should use the RatePlanCode returned in OTA_HotelAvail to compose the request of OTA_HotelBookingRule, and then take the new RatePlanCode returned n OTA_HotelBookingRule to compose the request of OTA_HotelRes as follows:
Click to see the example
<OTA_HotelBookingRuleService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelBookingRuleRQ PrimaryLangID="en" SequenceNmbr="xznZmG59RVOgz/PMsMqEnEfE=">
<POS>
<Source AgentDutyCode="username@test.com">
<RequestorID MessagePassword="password" />
</Source>
</POS>
<RuleMessage HotelCode="HBE|107">
<StatusApplication RatePlanCode="44vE0QwKgeMUBhxVxmgjvm6CmpMPeOgkSCSgkXtLJM9XMUVa9p/g41ImH26HwQIKJ5APMT/QbZvCUtj78Di4nA==" Start="2011-03-09" End="2012-03-12" />
</RuleMessage>
</OTA_HotelBookingRuleRQ>
</OTA_HotelBookingRuleService>
And the following, is the request to confirm the booking (OTA_HotelRes), using the RatePlanCode:
Click to see the example
<OTA_HotelResV2Service xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResRQ PrimaryLangID="en" SequenceNmbr="xznZmG59RVOgz/PMsMqEnEfE=">
<POS>
<Source AgentDutyCode="username@test.com">
<RequestorID MessagePassword="password" />
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<UniqueID ID_Context="agency_code" />
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType>
<TPA_Extensions>
<Guests xmlns="">
<Guest Name="John" Surname="Murray" />
<Guest Name="Sarah" Surname="Callahan" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="44vE0QwKgeMUBhxVxmgjvm6CmpMPeOgkSCSgkXtLJM9XMUVa9p/g41ImH26HwQIKJ5APMT/QbZvCUtj78Di4nA==" />
</RatePlans>
<TimeSpan Start="2011-03-09" End="2012-03-12" />
<Total AmountAfterTax="159.48" CurrencyCode="EUR" />
<BasicPropertyInfo HotelCode="HBE|107" />
<TPA_Extensions>
<ExpectedPriceRange min="0" max="500.00" xmlns="" />
</TPA_Extensions>
<Comments>
<Comment>
<Text>Comments</Text>
</Comment>
</Comments>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile ProfileType="1">
<Customer>
<PersonName>
<GivenName>John</GivenName>
<Surname>Murray</Surname>
</PersonName>
<Email>jmurray@test.com</Email>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
</OTA_HotelResV2Service>
As a response you will receive a locator of your booking:
Click to see the example
<UniqueID ID="DO4IE1" />
With this locator, you can use the request OTA_Cancel to obtain the cost cancellation or to cancel the booking.
Click to see the example
<OTA_CancelService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_CancelRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="username@test.com">
<RequestorID MessagePassword="password" />
</Source>
</POS>
<UniqueID ID="DO4IE1" />
<TPA_Extensions>
<GetOnlyCancellationCost>1</GetOnlyCancellationCost>
</TPA_Extensions>
</OTA_CancelRQ>
</OTA_CancelService>
¶ OTA Best Practices
¶ Compression
For big responses, the system will spend some extra time sending this information through the Internet. The system is designed to reduce the amount of time in the transmission step through the compression tool, by reducing the transmission time and response size by about 95%. We strongly recommend using compression in your request.
For using it, the request should have the header Accept-Encoding:gzip, deflate. If the server detects it then the response is compressed, and the client will receive our response with the header Content-Encoding: gzip. The client that receives the response has to decompress it on the fly before processing. This is a part of the HTTP standard protocol.
¶ Session-less Webservice
Juniper Webservice was designed to be session-less, that means that no login needs to be done, so you can call the operations in any desired order, without dragging any session or other data through the process (the only exception is the SequenceNumber at the confirmation request).
However, please note that the booking creation process has a basic flow:
- Do an availability search with the desired parameters.
- Send a booking rule request in order to retrieve the combination cancellation policies.
- Create a booking confirmation request.
Remember that prices and allotment can change at any time, so if you let much time between the availability and the booking request, you can lose the allotment or the price retrieved in the availability.
¶ Availability search by zone or accommodation
Our system is designed to search all the accommodations available in one specific destination for the dates and the occupancy requested. This model allows you to get in a single request all the available accommodations from a specific zone.
If you need just to check availability for one single accommodation, you can add this information in the availability request, so the system will return you just this service if available.
This single accommodation request is useful when you want to recheck availability or when you wish to focus on one particular product.
As seen in the section OTA_HotelAvail, you have the following options at the availability search:
- HotelCityCode: The destination code got from the zone list.
- HotelCode: The code of the specific accommodation you want to look for.
Warning
You should NEVER use the individual accommodation search to launch multithreaded requests for many individual products.
¶ Static data
Some data provided by the Webservice isn’t updated very often, while other data is updated often enough. You should store locally the static data, and use the Webservice to retrieve the non-static data online.
For example:
- Availability allotment and prices can change at any moment. You shouldn’t save this information much time in your system.
- Hotel information (description, images, etc) and zone list can be considered static. They aren’t updated often and you can save locally this information for days or weeks, thus you have fastest responses and you do not need to launch additional requests to get this information.
¶ Passenger names
At the OTA_HotelRes request, you should avoid entering duplicated passenger information (names/surnames) and/or names with numbers or any other incorrect data. Remember that passenger names are mandatory. If your system does not have for any of this information, you may agree along with your supplier into using dummy information. Leaving any of these fields as blank would cause error responses.
¶ Encoding
All SOAP messages must use UTF8 or UTF16 according to the {WS-I Basic Profile 1.0 statement - R1012}
Please make sure that the request you send has the following header (the content-type can also be application/soap+xml if you are using SOAP 1.2):
Content-Type: text/xml; charset=utf-8
¶ OTA Frequently Asked Questions
¶ How many rooms canI look for at the availability search?
Normally you can search up to three rooms, but this number can change depending on the supplier.
Please contact Juniper's support for more information.
¶ How can I get HotelCodes or using them at the Hotel Information request?
When you do a zone availability search, a list of results is returned.
These results have a HotelCode which identifies each accommodation.
This HotelCode doesn't change on each availability response, so each HotelCode indentifies a specific accommodation.
This HotelCode is used at the Hotel Information request at the Booking confirmation request.
¶ Which are the possible values of the AvailabilityStatus attribute?
The AvailabilityStatus attribute determines the availability of each combination of a specific hotel in the availability reponse. Possible values are:
- Availability for sale: The combination is available for online booking.
- OnRequest: The combination is available only on-request.
- NotAvailable: The combination is not available for sale - maybe it has no allotment for one day or has a stop sales.
¶ Which format should I use for sending dates?
You should use the format yyyy-MM-dd (ISO8601).
For example, 1st February 2020 would be 2020-02-01, and 14th September 2019 would be 2019-09-14.
¶ Which format should I use for sending decimal values?
You should send decimal values using no thousand sepatator, using dots as decimal separator, and using two decimals.
For example, 1,500.4 would be 1500.40.
¶ Is there any WSDL available?
Yes, each Webservice has its own WSDL. You only have to add the suffix ?WSDL to the path od each asmx file.
For example, if you have https://xml-uat.bookingengine.es/WebService/OTA_Cancel.asmx, you can go to https://xml-uat.bookingengine.es/WebService/OTA_Cancel.asmx?WSDL.
Remember you can access each asmx from a Web browser and see more information about each operation.
¶ Which information should we include in the voucher?
When doing an OTA_Read petition or reading the response of a booking confirmation, some important information will be returned. This information should be displayed in the client’s voucher in order to avoid problems for your clients:
- HotelReservation/UniqueID/ID: The locator of the reservation must be displayed.
- HotelReservation/RoomStays/RoomStay/TimeSpan: Checkin and checkout dates must be displayed.
- HotelReservation/RoomStays/RoomStay/BasicPropertyInfo: Hotel information (name, address, phone, zone, etc) should be displayed if available. Please note that you can get more information about the hotel combining this message with OTA_HotelDescriptiveInfo.
- HotelReservation/RoomStays/RoomStay/BasicPropertyInfo/VendorMessages/VendorMessage [@Title=’ImportantInfo’]: Comments from the hotel or the provider. It may include information about fees or payable services that the client must know.
- HotelReservation/RoomStays/RoomStay/CancelPenalties/CancelPenalty: Cancellation policy should be included in the voucher, if available.
- HotelReservation/RoomStays/RoomStay/RoomTypes: Room(s) name(s), board plan, and passenger names/ages must be included in the voucher.
- HotelReservation/ResGuests/ResGuest: Information of the booking holder should appear in the voucher.
- HotelReservation/TPA_Extensions/ExternalReference: If available, this reference code must be displayed. It is the external provider’s reference code.
- HotelReservation/TPA_Extensions/Payable: If available, this text indicates who pays the reservation. It should appear with a Payable by… text (or similar).
¶ When should we use the Booking Rules request?
The Booking Rules Request should be launched just before a reservation.
Although the booking confirmation request parameters re retrieved from the availability response, so you can confirm a booking without using this petition, it is highly recommeded to use it.
This petition allows the client to know the conditions of the reservation, such the cancellation policy or other comments or restrictions that the hotel or the provider reports before confirming the reservation. In this way unnecessary problems are avoided.
Apart of that, you retrieve optional supplements in this petition, which are not returned in the availability response due to the extra size.
Please take into acount also that this request is not fast in most cases. For that reason do not ask for booking rules on each combination returned in the availability response, neither sequentially nor using parallel (multithread) requests.
You should launch this operation only one step before the user confirms the reservation.
It is always recommeded to implement this operation and it is mandatory for some specific hotels which can suffer significant changes between the availability and the policy cancellation transactions. If the value returned in the tag TPA_Extensions/MadatoryBookingRule from the response OTA_HotelAvail is true, that meand it is required to call OTA_HotelBookingRule* before confirming the booking. I this case you have to use the new RatePlanCode returned in the response of OTA_HotelBookingRule in the request of OTA_HotelRes.
¶ When should we send the credit card? Which payment options are there?
There are three payment options. Depending on your account confguration, all reservations (with the exception of direct payment bookings) will have the same payment option:
- Credit card: You have to send the credit card when doing the booking confirmation. The reservation total price will be charged to that credit card and the reservation will be conirmed once the payment has been completed.
Please see the OTA_HotelRes for further information about how to send the credit card in the confirmation request. - Credit: Reservations will be cofirmed immediatly. They won't have any expiration date and you don't have to sen the credit card or immediate payment.
- Pre-payment: Reservations will be confirmed immediatly, but also have expiration date - see the OTA_HotelRes for more information about the expiration date location in the XML.
If you don't pay the reservation to the WebService provider before that date, the reservation will be automatically cancelled.
All reservations will have the same payment oprion you have configured in you account. For example, if your account is a pre-payment account, your reservations wil be pre-payment.
The only exception is credit card: if you send the credit card in the OTA_HotelRes request, the reservation will be a credit card reservation, regardless your account configuration.
For example, if your account is credit, if you don't send the credit card in OTA_HotelRes request, the reservation will be a credit reservation. But if you send the credit card, that reservation will be converted to credit card reservation.
The exceptions to this general rule are direct payment bookings.
These bookings are paid directly at the hotel, so the final user credit card must be provided in all cases as a guarantee in the OTA_HotelRes request.
Contact your WebService provider fot getting more information about the payment option you will have.
¶ How can we search for a special product type?
You can use the TypeSearch option in the OTA_HotelAvail request in order to request a special product type.
If you don't specify anything, it will be a normal hotel request. If you specify a special product type, only hotels with that product type will be returned.
the price will include the whole package, and the product may appear as an included supplement (with the same code as the product requested).
For example you may search for Forfait in this way:
Click to see the example
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCode="JP633562" />
<TPA_Extensions>
<TypeSearch>FORFAIT</TypeSearch>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
You would receive a lit of hotels with included forfaits under the Features node.
Click to see the example
<Features>
<Feature RoomViewCode="FORFAIT">
<Description Name="VALUE">
<Text>Forfait GrandValira 3 days</Text>
</Description>
<Description Name="DESC">
<Text>This package includes hotel + lift tickets in GrandValira for 3 days </Text>
</Description>
</Feature>
</Features>
In this way you can access additional product via XML with a tiny modification – only specifying the special product type in the OTA_HotelAvail request. The rest of the integration is exactly the same and no other change is needed in the client’s side.
Please contact Juniper to get a list of available special product types.
¶ I send a booking confirmation but I receive it with status Can (cancelled) or PRe (on request). Why?
It is very importantto check the ResStaus attribute in the OTA_HotelRes response in order to verify the booking has acorrect stats. In this way you can avoid thinking that a booking is confirmed but really is not, which would give you unnecessary problems.
Due to the fact that the WebService is session-less, you don't block allotment until the booking is confirmed. So there is a (very small) prossibility that someone else confirmed the las tt room before you, of between the availability and the confirmation the holder had added a stop sales.
Apart of this, there can be network or connection problems with providers nd other punctual issues that could prevent the booking from being confirmed correctly.
¶ How can we relate the information of the rooms between requests?
If you make a request OTA_HotelAvail with the option ShowInternalRoomInfo, you cna obtain a node RoomType with the code of the room type in: RoomStays/RoomStay/RoomRates/RoomRate/Rates/Rate/TPA_Extension.
You can obtain the description of the room in: RoomStays/RoomStay/RoomRates/RoomRate/Rates/Rate/RateDescription/Text.
Click to see the example
<Rates>
<Rate NumberOfUnits="1" RateMode="Room" RateSource="1">
<Total AmountAfterTax="918.75" DecimalPlaces="2" />
<RateDescription>
<Text>OceanView Balcony</Text>
</RateDescription>
<TPA_Extensions>
<AvailRooms xmlns="">10</AvailRooms>
<RoomType xmlns="">158</RoomType>
<Mealplan IntCode="AD" xmlns="">2</Mealplan>
<RoomCategory id="13" xmlns="">SUP</RoomCategory>
</TPA_Extensions>
</Rate>
</Rates>
If you make the OTA_HotelDescriptiveInfo by the code hotel, you can obtain a node GuestRooms with the different code rooms to this hotel.
Click to see the example
<FacilityInfo>
<GuestRooms>
<GuestRoom RoomTypeName="Standard Room (1/2A+0/0n)" MaxOccupancy="2" MaxAdultOccupancy="2" ID="12" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="OceanView (1/2A+0/0n)" MaxOccupancy="2" MaxAdultOccupancy="2" ID="156" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="Superior (1/2A+0/0n)" MaxOccupancy="2" MaxAdultOccupancy="2" ID="157" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="OceanView Balcony (1/2A+0/0n)" MaxOccupancy="2" MaxAdultOccupancy="2" ID="158" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="One Bedroom Suite (1/2A+0/0n)" MaxOccupancy="2" MaxAdultOccupancy="2" ID="161" MaxChildOccupancy="0" />
<GuestRoom RoomTypeName="Tresor Jr Suite (1/4A+0/3n)" MaxOccupancy="7" MaxAdultOccupancy="4" ID="15" MaxChildOccupancy="3" />
<GuestRoom RoomTypeName="Chateau Jr Suite (1/4A+0/3n)" MaxOccupancy="7" MaxAdultOccupancy="4" ID="162" MaxChildOccupancy="3" />
<GuestRoom RoomTypeName="Versailles One Bedroom Oceanfront (1/4A+0/3n)" MaxOccupancy="7" MaxAdultOccupancy="4" ID="163" MaxChildOccupancy="3" />
</GuestRooms>
</FacilityInfo>
Betwen this information, you can obtain an ID of GuestRoom which is the same as the type in the response of OTA_HotelAvail.
The attribute RoomTypeName is the concatenation of the name of the room in the hotel and the occupation. OceanViewBalcony (1/2A+0/0n).
Note:
One hotel has some rooms, for each room there is a room type.
One room type can be used by som different hotels. The ID will be the same between different hotels but the RoomTypeName will be different.
With the response JP_RoomTypeList, you can obtain all the types of rooms, the attribute name is the concatenation of the name of type and the occupation.
Click to see the example
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_RoomTypeListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_RoomTypeListRS>
<RoomType Code="12" Name="1/2 ad (1/2A+0/0N)" />
<RoomType Code="156" Name="1/2 ad (1/2A+0/0N)" />
<RoomType Code="157" Name="1/2 ad (1/2A+0/0N)" />
<RoomType Code="158" Name="1/2 ad (1/2A+0/0N)" />
<RoomType Code="161" Name="1/2 ad (1/2A+0/0N)" />
<RoomType Code="15" Name="Ocup. T5 4A hab (1/4A+0/3N)" />
<RoomType Code="162" Name="Ocup. T5 4A hab (1/4A+0/3N)" />
<RoomType Code="163" Name="Ocup. T5 4A hab (1/4A+0/3N)" /> …
</JP_RoomTypeListRS>
</JP_RoomTypeListServiceResponse>
</soap:Body>
</soap:Envelope>
¶ How can we send a request with PHP technology?
For example, a request OTA_HotelDescriptiveInfo with PHP technology:
Click to see the example
<?php
class OTA_HotelDescriptiveInfoService
{
function OTA_HotelDescriptiveInfoRQ()
{
$this->client = new SoapClient('https://xml-uat.bookingengine.es/webservice/OTA_HotelDescriptiveInfo.asmx?wsdl', array(
'exceptions' => 0,
'trace' => 1,
'connection_timeout' => 1800
));
$this->client->OTA_HotelDescriptiveInfoService->xmlns = 'http://www.juniper.es/webservice/2007/';
$OTA_HotelDescriptiveInfoService = $this->client->OTA_HotelDescriptiveInfoService;
$OTA_HotelDescriptiveInfoService->OTA_HotelDescriptiveInfoRQ->PrimaryLangID = "en";
$OTA_HotelDescriptiveInfoService->OTA_HotelDescriptiveInfoRQ->POS->Source->AgentDutyCode = "user@domain.com";
$OTA_HotelDescriptiveInfoService->OTA_HotelDescriptiveInfoRQ->POS->Source->RequestorID->Type = "1";
$OTA_HotelDescriptiveInfoService->OTA_HotelDescriptiveInfoRQ->POS->Source->RequestorID->MessagePassword = "password";
$OTA_HotelDescriptiveInfoService->OTA_HotelDescriptiveInfoRQ->HotelDescriptiveInfos->HotelDescriptiveInfo->HotelCode = "HotelCode";
$dataRQ = $OTA_HotelDescriptiveInfoService;
try {
$rp = $this->client->__soapCall('OTA_HotelDescriptiveInfoService', array(
'OTA_HotelDescriptiveInfoRQ' => $dataRQ
));
} catch (SoapFault $exception) {
$rp = $exception;
}
}
}
$obj = new OTA_HotelDescriptiveInfoService();
$obj->OTA_HotelDescriptiveInfoRQ();
An example, a request OTA_HotelAvail with PHP technoloy using TPA_Extensions nodes:
Click to see the example
<?php
class OTA_HotelAvailService
{
function OTA_HotelAvailRQ()
{
$this->client = new SoapClient('http://xml-uat.bookingengine.es/webservice/OTA_HotelAvail.asmx?wsdl', array(
'exceptions' => 0,
'trace' => 1,
'connection_timeout' => 1800,
'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP,
'encoding' => 'ISO-8859-1'
));
$this->client->OTA_HotelAvailService->xmlns = 'http://www.juniper.es/webservice/2007/';
$OTA_HotelAvailService = $this->client->OTA_HotelAvailService;
$OTA_HotelAvailService->OTA_HotelAvailRQ->PrimaryLangID = 'en';
$OTA_HotelAvailService->OTA_HotelAvailRQ->POS->Source->AgentDutyCode = $userid;
$OTA_HotelAvailService->OTA_HotelAvailRQ->POS->Source->RequestorID->Type = "1";
$OTA_HotelAvailService->OTA_HotelAvailRQ->POS->Source->RequestorID->MessagePassword = $password;
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->StayDateRange->Start = "2012-02-27";
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->StayDateRange->End = "2012-02-28";
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->RoomStayCandidates->RoomStayCandidate->Quantity = 1;
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->RoomStayCandidates->RoomStayCandidate->GuestCounts->GuestCount->Age = 40;
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->RoomStayCandidates->RoomStayCandidate->GuestCounts->GuestCount->Count = 2;
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->HotelSearchCriteria->Criterion->HotelRef->HotelCityCode = "PMI";
$tpa_extensions = '<ns1:TPA_Extensions> <ShowBasicInfo>1</ShowBasicInfo> <ShowCatalogueData>1</ShowCatalogueData><Debug>1</Debug></ns1:TPA_Extensions>';
$obj = new SoapVar($tpa_extensions, XSD_ANYXML);
$OTA_HotelAvailService->OTA_HotelAvailRQ->AvailRequestSegments->AvailRequestSegment->HotelSearchCriteria->Criterion->TPA_Extensions = $obj;
$dataRQ = $OTA_HotelAvailService;
try {
$rp = $this->client->__soapCall('OTA_HotelAvailService', array(
'OTA_HotelAvailRQ' => $dataRQ
));
}
catch (SoapFault $exception) {
$rp = $exception;
}
}
}
$obj = new OTA_HotelAvailService();
$obj->OTA_HotelAvailRQ();
?>
¶ What is the process to obtain the entire product?
The process to obtain the entie product is the following:
- First you can send the request JP_CatalogueData to obtain the static data of the catalogue. For example, mealplans, accommodation types, ...
- Then send the JP_ZoneList request in order to obtain a list of zones. This request has the following option.
- ShowHotels: This option shows the attribute Hotel that indicates if you can search in that zone for availability.
Example of response:
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_ZoneListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_ZoneListRS>
<Zone Code="17748" Name="España" Parent="" IATA="ES" Hotels="true" Searchable="true" />
<Zone Code="41869" Name="Mallorca Centro" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="36161" Name="Palma De Mallorca" Parent="17852" IATA="PMI" Hotels="true" Searchable="true" />
<Zone Code="40785" Name="Sierra De Tramuntana" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="41871" Name="Zona Este" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="41874" Name="Zona Norte" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="41872" Name="Zona Sur" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="37424" Name="Alcudia Región" Parent="41874" IATA="" Hotels="true" Searchable="true" />
<Zone Code="37407" Name="Calas De Mallorca" Parent="41871" IATA="" Hotels="true" Searchable="true" />
<Zone Code="40604" Name="Calvia" Parent="41872" IATA="" Hotels="true" Searchable="true" />
<Zone Code="40751" Name="Esporles" Parent="40785" IATA="" Hotels="true" Searchable="true" />
</JP_ZoneListRS>
</JP_ZoneListServiceResponse>
</soap:Body>
</soap:Envelope>
- For each zone of the list JP_ZoneList that have the attribute Hotels equal to true, you can send a JP_HotelList request. With the response of thi request you can obtain a list of hotel codes that there are in this zone and relate to which zone code does this hotel belong by the zone code you have searched it from.
Example of response:
Click to see the example
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_HotelListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_HotelListRS>
<Hotel Code="XIK5imVUdDm8UEtUeOdM+w==" />
<Hotel Code="lf6UNVAyKx/pRLDz+4TtNw==" />
<Hotel Code="KI7gWpn62OsDY2NxBzZe2Q==" />
<Hotel Code="C043fm9v31367U9Pti6bWQ==" />
<Hotel Code="ZV5MTdRUC/ML5nfqr5yUAw==" />
<Hotel Code="nEBk4Qh3YqAlZ4ENRgdmfw==" />
</JP_HotelListRS>
</JP_HotelListServiceResponse>
</soap:Body>
</soap:Envelope>
- For each code of the list JP_HotelList, you can send a request OTA_HotelDescriptiveInfo to obtainthe static data of this hotel. In this request you can send a maximum of 50 hotel codes.
¶ How can we relate the zones?
With the request JP_ZoneList you can obtain a list of zones. In this list you can observe that you have the folowing attributes for each node Zone.
- Code: It is the code of the zone that you have to use for search in OTA_HotelAvail, OTA_HotelDescriptiveInfo and JP_ZoneList.
- Name: It is the name of the zone in the language that you send in th request with the attribute PrimaryLangID.
- Parent: It is the top zone of this zone.
Example of response:
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<JP_ZoneListServiceResponse xmlns="http://www.juniper.es/webservice/2007/">
<JP_ZoneListRS>
<Zone Code="17748" Name="España" Parent="" IATA="ES" Hotels="true" Searchable="true" />
<Zone Code="35386" Name="Barcelona Y Región" Parent="17748" IATA="" Hotels="true" Searchable="true" />
<Zone Code="40760" Name="Islas Baleares" Parent="17748" IATA="" Hotels="true" Searchable="true" />
<Zone Code="17828" Name="Leon" Parent="17748" IATA="LEN" Hotels="true" Searchable="true" />
<Zone Code="41049" Name="Madrid Y Región" Parent="17748" IATA="" Hotels="true" Searchable="true" />
<Zone Code="40841" Name="Barcelona" Parent="35386" IATA="BCN" Hotels="true" Searchable="true" />
<Zone Code="17852" Name="Mallorca" Parent="40760" IATA="" Hotels="true" Searchable="true" />
<Zone Code="36063" Name="Menorca" Parent="40760" IATA="MAH" Hotels="true" Searchable="true" />
<Zone Code="36161" Name="Palma De Mallorca" Parent="17852" IATA="PMI" Hotels="true" Searchable="true" />
<Zone Code="40785" Name="Sierra De Tramuntana" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="37424" Name="Alcudia" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="37407" Name="Calas De Mallorca" Parent="17852" IATA="" Hotels="true" Searchable="true" />
<Zone Code="40604" Name="Calvia" Parent="17852" IATA="" Hotels="true" Searchable="true" />
</JP_ZoneListRS>
</JP_ZoneListServiceResponse>
</soap:Body>
</soap:Envelope>
Following the structure:
- The nodes Zone without value in attribute Parent are the main zones. In this example:
17748(España). - The nodes with value in attribute Parent equal to
17748are the lower zones of17748(España). In this example:40760(Islas Baleares). - The zones with value in attribute Parent equal to
40760are the lower zones of40760(Islas Baleares). In this example:17852(Mallorca).
And so on.
For this example, the structure of zones is:
- España (
17748).- Barcelona y region (
35386).- Barcelona (
40841).
- Barcelona (
- Leon (
17828). - Madrid y region (
41049). - Islas Baleares (
40760).- Menorca (
36063). - Mallorca (
17852).- Palma de Mallorca (
36161). - Sierra de Tramuntana (
40785). - Alcudia (
37424). - Calas de Mallorca (
37407). - Calvia (
40604).
- Palma de Mallorca (
- Menorca (
- Barcelona y region (
¶ I am getting too many OTA_HOTELRES_MandatoryBookingRule on my booking confirmation attempts. Why is this the case?
The OTA_HOTELRES_MandatoryBookingRule is an error response that is returned on the OTA_HotelRes step whenever the conditions from the MandatoryBookingRule node/feature are not being complied with.
Now, it will be possible to identify when this will be the case by looking into the MandatoryBookingRule node that is available within the OTA_HotelAvail response, as in the following example:
<RoomRate RatePlanCode = "COMBINATION1" RatePlanCategory = "Room only" AvailabilityStatus = "AvailableForSale">
<Rates>
<Rate NumberOfUnits = "3" RateMode = "Hab" RateSource = "1,2,3">
<Total AmountAfterTax = "100.00"/>
<RateDescription>...</RateDescription>
<TPA_Extensions>
<DailyBreakdown>50.00#50.00</DailyBreakdown>
<MandatoryBookingRule>1</MandatoryBookingRule>
<RoomCategory id = "9">SUI</RoomCategory>
<RoomOccupancy MaxOccupancy = "2"/>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax = "300.00" CurrencyCode = "USD" DecimalPlaces = "2"/>
<TPA_Extensions>...</TPA_Extensions>
</RoomRate>
As, when available and true (1), it will require for you to comply with the following conditions:
- Send a OTA_HotelBookingRule request in order to retrieve the update RatePlanCode from its response (which you would be using on your OTA_HotelRes request).
- Once you retrieve this updated RatePlanCode, ensure that the combination will be confirmed within 10 minutes -> Otherwise, it will expire and require you to obain a new RatePlanCode by sending an additional OTA_HotelBookingRule request.
In order to properly confirm the selected combination. Otherwise, if this is not complied, it is when the system will supply you with a OTA_HOTELRES_MandatoryBookingRule error response:
<Errors>
<ErrorType Type = "enNODATASENT" ShortText = " Combination code is not correct. It's mandatory to call OTA_BookingRule" Code = "OTA_HOTELRES_MandatoryBookingRule"/>
</Errors>
¶ How may I be able to identify fees and taxes that are to be paid at the destination?
Following the most recent update of the California Law:
California Resort Fee Bill (AB 537) and Consumer Legal Remedies Act (SB 478)
You may be wondering on how to properly identify fees and taxes that are to be paid at the destination, and here we would like to provide a brief extract/example on how may this be done within the Juniper API:
You will be able to identify this by looking into any direct payment supplements that may be available within your results, such as in the following example (example that assumes that your request will be using the ShowCatalogueData TPA_Extension):
<RoomRate RatePlanCode = "2+RZLQZBVM+8lY3E5xV..." RatePlanCategory = "Room Only" AvailabilityStatus = "AvailableForSale">
<Rates>
<Rate NumberOfUnits = "1" RateMode = "Room" RateSource = "1">
<Total AmountAfterTax = "1518.51" DecimalPlaces = "2"/>
<RateDescription>
<Text>Family Room, 1 King Bed and 2 Double Beds</Text>
</RateDescription>
<TPA_Extensions>
<RoomType xmlns = "">324573927</RoomType>
<Mealplan xmlns = "">3</Mealplan>
</TPA_Extensions>
</Rate>
</Rates>
<Total AmountAfterTax = "1518.51" CurrencyCode = "EUR" DecimalPlaces = "2"/>
<TPA_Extensions>
<MandatoryBookingRule xmlns = "">1</MandatoryBookingRule>
<Mealplan Category = "SA" id = "3" xmlns = "">3</Mealplan>
<NonRefundable xmlns = "">1</NonRefundable>
<PackageContract xmlns = "">0</PackageContract>
<Elements xmlns = "">
<Element Class = "DIRECT_PAYMENT" Price = "4.73" PriceWithTax = "" Currency = "EUR">
<Name>Mandatory Tax</Name>
<Description>Payment at destination</Description>
</Element>
<Element Class = "DIRECT_PAYMENT" Price = "32.12" PriceWithTax = "" Currency = "EUR">
<Name>Mandatory Fee</Name>
<Description>Payment at destination</Description>
</Element>
</Elements>
</TPA_Extensions>
</RoomRate>
On which, on the Elements node (found within the TPA_Extensions node of the applicable result (RoomRate)), you will be able to identify Element's labeled as Class = "DIRECT_PAYMENT" (implying that they will need to be paid at the desintation, and that they are not currently included in the total price), from which you would also be able to identify their respective @Price and @Currency (as to propertly represent how much would these direct payment supplemnts cost), along with their respective Name and (if available) Description, from which you will also be able to identify and to describe the supplements in question.
¶ OTA Warnings
In this section you will be able to find most of the warning codes that may be supplied to you while using the OTA Hotel API.
| Warning code | Warning text | Additional information |
|---|---|---|
| warnRequestDate | Your requested Dates specify a TimeZone, the results might not be for the expected dates. | |
| ObsoleteJPCode | You are using an obsolete JPCode. Please update your reference from {0} to the unified | |
| PRICE_CHANGED | Price changed | |
| QUOTE_CHANGED | Quote changed: | {0} will include either AV (available) or RQ (on request). |
| NOT_AVAILABILITY | Not availability | |
| NOT_POSSIBLE | Price review is not possible | |
| CATEGORY_DIFFERENCE | There is a category difference | |
| NOT_BOOK | No reservable | |
| REQ_PRACTICE | API required practices are not being complied in this request, please review parameter [{0}] | {0} being the name of the affected best practice. |
| warnCurrencyIgnored | The specified currency has been ignored as this is a Multicurrency environment. |
¶ OTA Certification Process
In this section you will find a description of the certification tests and the additional information we will ask you before connecting live.
It basically consists on some basic bookings, including the different options allowed and covering the available product. Moreover, we ask you for some info regarding the approximate volume of traffic you will send to our system (if available) a short description of your system flow and information about the timeouts you have implemented.
You can find next the certification tests that must be completed and sent to Juniper before connecting live. If we find any problem, we will inform you, so you can fix it. If everything is correct, we will provide you live access for the provided IP's.
¶ Booking flow certification
Before moving to live, you will have to perform some tests in order to validate the integration and to ensure that the implementation process is working correctly.
We would need to do the following bookings in the development environment. This tests may help to you to verify that most functionalities are covered. Please, add the recovered information from the bookings and some screenshots if needed. You can choose any hotel and area.
- One room for two adults.
- Two rooms, one for two adults and one child of 5 years and the second for one adult and two children of one and eight years.
- Three rooms , first for one adult, the second for one adult and one child of 15 years, and the third for three adults.
We need the XMLs of the requests and responses (OTA_HotelAvail, OTA_HotelBookingRule and OTA_HotelRes). In this way we will compare your data with ours and check that everything is correct.
We need you to copy the information you have in your system of these bookings:
- State of the booking.
- Price.
- Name and information of the passenger and the holder.
- Name of the hotel, dates, room and board of the booking.
We'd also like to have a short description of your system flow and how many requests you have planned to do in live. We want the approximate number of requests per day and per second for times of more work, both availability and reservations as others (total requests). We need an estimation, the number doesn't have to be exact.
Please also give us some information regarding the length of the timeout you have set for our response or if you don't have implemented any.
¶ What we check in the booking flow certification
First of all, the structure of the availability request must be correctly formed, and no one of the mandatory fields must be missed. Amongst other, we will check the following nodes:
• Pax and their ages. You should be especially careful with child ages, as they must be the same as you send in the booking transaction. Age for adults is optional.
• Also a hotel code and other filters (room type, board type, etc) might be included.
Click to see the example
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<OTA_HotelAvailService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelAvailRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="user@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<StayDateRange Start="2014-08-12" End="2014-08-14" />
<RoomStayCandidates>
<RoomStayCandidate Quantity="1">
<GuestCounts>
<GuestCount Count="2" />
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<HotelSearchCriteria>
<Criterion>
<HotelRef HotelCityCode="1953" />
<TPA_Extensions>
<ShowBasicInfo>1</ShowBasicInfo>
<ShowCatalogueData>1</ShowCatalogueData>
</TPA_Extensions>
</Criterion>
</HotelSearchCriteria>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</OTA_HotelAvailService>
</soap:Body>
</soap:Envelope>
It is also a mandatory point to use the compression tool, so the amount of transmitted data and time is highly reduced. If you don’t use it, the response will contain a warning and the integration could not be certificated.
<Warnings>
<WarningType Type = "89" ShortText = "Please add the 'Accept-Encoding: gzip, deflate' header in your petition. This can reduce the transmission time and response size by about 75-95%. See more here: http: //www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"/>
</Warnings>
If the request is valid, you will receive a response containing all the possible combinations for the desired distribution. Each combination may be composed by one or more rooms and will be returned under a RatePanCode. Each one of them will be returned under a RatePlanCode.
This code should be used in the next transaction of the booking flow: OTA_HotelBookingRule. Please be aware that the use of this code is other important point in the certification process.
It is not possible to split the rooms returned under the same RatePlanCode. If you want to book just one room from a combination of some, a new OTA_HotelAvail transaction for this only room must be sent and complete the booking process from the new RatePlanCode returned.
Next step is the OTA_HotelBookingRule transaction. This is a mandatory step for the booking process as, besides from returning important information for the booking (e.g. cancellation policies), it validates the allotment and rate. Some suppliers use dynamic assignation, so it is not up to this point when allotment and prices are confirmed in live.
This transaction needs only a few parameters: booking dates, hotel code and the described RatePlanCode from the availability response.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelBookingRuleService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelBookingRuleRQ PrimaryLangID="en" SequenceNmbr="RnJf18IIzatwedkQzm9IOWaB17sefYjHlEzBkbMbAeg=">
<POS>
<Source AgentDutyCode="user@mydomain.com">
<RequestorID MessagePassword="pass" />
</Source>
</POS>
<RuleMessage HotelCode="JP633562">
<StatusApplication Start="2014-08-12" End="2014-08-14" RatePlanCode="3WCCdKrNDmJB1QQRyLq2X+RVk0veR58/Hv8Wr7RNcjaiMCfF6vOAFNHzhm4h0A4P066d7gZr/i5En4gn1DphiTn0BAtonYZOyg1+o3BNUrCIUjpdVXYSRQpYRVqmAHPkkv7J+aw4K7Z8WLlYTUcDVA==" />
<TPA_Extensions>
<ShowSupplements>1</ShowSupplements>
</TPA_Extensions>
</RuleMessage>
</OTA_HotelBookingRuleRQ>
</OTA_HotelBookingRuleService>
</soap:Body>
</soap:Envelope>
The response will contain:
- RatePlanCode: It may be different from the one returned in the availability response. Thi is the one that must be used from now all along the booking process.
Click to see the example
<StatusApplication RatePlanCode="3WCCdKrNDmJB1QQRyLq2X+RVk0veR58/Hv8Wr7RNcjaiMCfF6vOAFNHzhm4h0A4P066d7gZr/i5En4gn1DphiTn0BAtonYZOyg1+o3BNUrCIUjpdVXYSRQpYRVqmAHPkkv7J+aw4K7Z8WLlYTUcDVA==" Start="2014-08-12" End="2014-08-14" />
- RequiredFields: It is important you consider this node, as it contains the mandatory fields that you should include for this booking in the confirmation step.
Click to see the example
<RequirePaxName>1</RequirePaxName>
<RequireFullAddress>1</RequireFullAddress>
- CancellationPolicies: It is important to remember that not always a list of cancellation policy rules can be returned. In this cases it is mandatory to read the node that contains the cancellation policy as plain text.
Click to see the example
<CancelPenalties>
<CancelPenalty>
<PenaltyDescription>
<Text>
CANCELLATION FEES
- 6 or more days before the arrival: NO CHARGES
- 4/5 days before the arrival: 10% of the total amount of the booking
- 2/3 days before the arrival: 20% of the total amount of the booking
- 0/1 days before the arrival: 1 night
- No show: 100% of the total amount of the booking
</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<CancellationPolicyRules CurrencyCode="USD">
<Rule From="0" To="1" DateFrom="2014-08-10T12:00:00" DateTo="2014-08-12T12:00:00" Type="V" FixedPrice="0.00" PercentPrice="0.00" Nights="1" ApplicationTypeNights="Average"/>
<Rule From="2" To="3" DateFrom="2014-08-08T12:00:00" DateTo="2014-08-10T12:00:00" Type="V" FixedPrice="0.00" PercentPrice="20.00" Nights="0" ApplicationTypeNights=""/>
<Rule From="4" To="5" DateFrom="2014-08-06T12:00:00" DateTo="2014-08-08T12:00:00" Type="V" FixedPrice="0.00" PercentPrice="10.00" Nights="0" ApplicationTypeNights=""/>
<Rule From="6" DateFrom="2014-03-27T07:13:43" DateTo="2014-08-06T12:00:00" Type="V" FixedPrice="0.00" PercentPrice="0.00" Nights="0" ApplicationTypeNights=""/>
<Rule DateFrom="2014-08-12T12:00:00" Type="S" FixedPrice="0.00" PercentPrice="100.00" Nights="0" ApplicationTypeNights=""/>
</CancellationPolicyRules>
- Special notes: A list of remarks from the hotel may be returned in the response.
Click to see the example
<Description>
<Text>* 01/02/2014 - 31/12/2014: Pool closed in winter</Text>
</Description>
- Optional products and supplements: For further information and a detailed description, please review the section OTA_HotelBookingRule.
As it is not mandatory to select these products to complete a booking, we would not ask you to validate them. However, if you don’t include them in the certification tests, we consider you will not use them and therefore you are not allowed to include them in the bookings
Click to see the example
<Supplements>
<Supplement id="8754" type="O" Discount="0" name="Optional supplement" price="200.00" SelectByPax="1" empaquetado="0">
<Desc>Description</Desc>
</Supplement>
<Supplement id="8757" type="O" Discount="0" name="Short stay" price="120.00" SelectByPax="0" empaquetado="0" />
<Supplement id="8764" type="M" Discount="1" name="New sales offer" price="-56.00" SelectByPax="0" empaquetado="0" />
<Supplement id="8770" type="O" Discount="0" name="short stay supplement" price="40.00" SelectByPax="0" empaquetado="0" />
</Supplements>
- If the Price verification is not possible for any reason, a warning at the beginning of the response will be returned.
Click to see the example
<Warnings>
<Warning Code = "warnCheckNotPossible" Text = "Price review is not possible"/>
</Warnings>
Last step in the booking flow is the OTA_HotelRes. This transaction validates all the information retrieved from the rest of transactions and confirms the booking. Some important data that we will check are:
- The RatePlanCode must be retrieved from the transaction OTA_HotelBookingRule.
- The distribution of passengers and its order in the XML structure must be the same as in the availability. Also the number of passengers and their ages (especially for children) must match.
- Also, it is mandatory to send information about the booking Customer (booking holder).
- The booking confirmation must also include basic information as the hotel code, stay dates and the price.
- Additional information and remarks: It is possible to add some comments from the customer in this transaction, which will be included in the booking. Also an external reference locator can be set in the booking by using the node
- Your own booking confirmation locator (UniqueID@ID_Context).
- Same language must be set in all the transactions of the booking flow.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelResV2Service xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelResRQ PrimaryLangID="en" Version="0" SequenceNmbr="RnJf18IIzatwedkQzm9IOWaB17sefYjHlEzBkbMbAeg=">
<POS>
<Source AgentDutyCode="user@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<UniqueID ID_Context="AGENCY_EXTERNAL_LOCATOR" />
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType>
<TPA_Extensions>
<Guests>
<Guest Name="A1" Surname="B1" />
<Guest Name="A2" Surname="B2" />
</Guests>
</TPA_Extensions>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="3WCCdKrNDmJB1QQRyLq2X+RVk0veR58/Hv8Wr7RNcjaiMCfF6vOAFNHzhm4h0A4P066d7gZr/i5En4gn1DphiTn0BAtonYZOyg1+o3BNUrCIUjpdVXYSRQpYRVqmAHPkkv7J+aw4K7Z8WLlYTUcDVA==" />
</RatePlans>
<TimeSpan Start="2014-08-12" End="2014-08-14" />
<Total AmountAfterTax="504" CurrencyCode="USD" />
<BasicPropertyInfo HotelCode="JP633562" />
<Comments>
<Comment>
<Text>Comments</Text>
</Comment>
</Comments>
<Reference/>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile ProfileType="1">
<Customer>
<PersonName>
<GivenName>CustomerName</GivenName>
<Surname>CustomerSurname</Surname>
<NamePrefix>Mr</NamePrefix>
</PersonName>
<Email>user@mydomain.com</Email>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
</OTA_HotelResV2Service>
</soap:Body>
</soap:Envelope>
Finally, we ask you to check the value of the node Status of the booking response. You may not consider a booking confirmed without reading its status, as it might be returned as canceled (CaC or Can status), or On request (Pre or PDI status).
¶ Static data certification
Once the booking flow certification has been verified and confirmed by our team and if you plan on retrieving and/or storing static data information from our system (if not, simply say us so), we will also need you to complete an additional booking flow on which we will supply you with an specific hotel code and verify a series of parameters. Kindly contact with Juniper for this information.
Important note:
With this booking flow, we will mainly verify that the following requirement is fulfilled:
Starting at the valuation step and onwards (which includes the OTA_HotelBookingRule response, the OTA_HotelRes response and the voucher), we require for our XML clients to use the hotel important information (by hotel important information we refer to the hotel name, hotel address and hotel category) from our respective XML responses directly instead of using previously downloaded information. This is done as to avoid potential mapping issues in this regard without needing to reach for any kind of agreement between the XML client and the supplier.
This requirement will ease the connection process along any Juniper supplier that you may wish to connect on the future as it would allow for you to directly connect to them without the need of performing and kind of verification and/or agreement in this regard. Otherwise, if not complied with, connecting to Juniper suppliers (current or future ones) will still be possible, but will require on having reached an agreement first (between both parties, integrator and supplier and on a supplier by supplier basis), as Juniper will not be held responsible on any missmatched bookings.
Additionally, we will also request you to confirm how often will you plan on updating the static data information. The mentioned should be done at least once every 15 days.
In order to perform this certification, we will need you to supply us with the following:
- XML requests and responses of the transaction OTA_HotelDescriptiveInfo for the provided hotel.
- XML requests and responses of the rest of the process (OTA_HotelAvail, OTA_HotelBookingRule and OTA_HotelRes) choosing the same hotel.
- Screenshots of the website in which we can see the hotel information you display at each step of the booking process: availability results, extended info (if you have this option), cancellation policies, booking confirmation and voucher.
¶ What we check in the static data certification
From the screenshots that you supply us with, we will verify that the hotel important information that you display to your clients has been retrieved dynamically from the XML responses from the booking process.
The following information, retrieved from the OTA_HotelAvail transaction, is allowed to be displayed.
<BasicPropertyInfo HotelCode="JP633562" HotelName="Test Hotel - Dynamic" />
<TPA_Extensions>
<HotelInfo>
<Category Code="5" CodeDetail="5 Stars" />
<Description>Short description</Description>
<Thumb>http://www.bookingengine.es/images/upload_p/hotels/Nombre/HotelAdolfo1.jpg</Thumb>
<Zone>Majorca</Zone>
<AreaID>1953</AreaID>
<JPDCode>JPD036705</JPDCode>
<AccommodationType id="2">BCH</AccommodationType>
<Label Code="2" SortPriority="0"> RECOMMENDED </Label>
<Latitude>39.60125744381</Latitude>
<Longitude>2.65664219856262</Longitude>
<Provider>Demo</Provider>
<IsOffer>0</IsOffer>
</HotelInfo>
</TPA_Extensions>
The same goes for the OTA_HotelBookingRule and OTA_HotelRes transactions.
If you wish to obtain the detailed information of a hotel through the OTA_HotelDescriptiveInfo transaction, you may do so by using the selected combination RatePlanCode in the HotelCode property.
Click to see the example
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<OTA_HotelDescriptiveInfoService xmlns="http://www.opentravel.org/OTA/2003/05">
<OTA_HotelDescriptiveInfoRQ PrimaryLangID="en">
<POS>
<Source AgentDutyCode="user@mydomain.com">
<RequestorID Type="1" MessagePassword="pass" />
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo HotelCode="JRZeUyuAd1LQ1g0oF3ybeB6W0MlkNzZor3+SaLUfUjd7th6KgEXZBu3AW6OlAqsXSvHPEcI7GdsqfLgoaLMZy+OpOZ/yOkseGURlUzfvCiAyDutiJYNHfOp826zSljOPHtSR3Mpqg73P6WU00hyIoX5rJ0Tm3YxLsnHH+CLv9tIP29tEHSgiMe578kg3FwV0JDZAezZtMHl3wwJ84iJiILsM6bK5Fze1DHr5HNpodbamDznuegCdfvjh8CUN/HTF" />
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</OTA_HotelDescriptiveInfoService>
</soap:Body>
</soap:Envelope>
That way we will chech that you compose the voucher following the same rules described in this section.