Use the Tour SOAP API to Search, Check Policies and Book Tours with over 100 different suppliers all over the world.
The Tour SOAP API has the following methods to use in this order:
SearchAvailability: Used to define what tours you want, whith Checkin date, Checkout date,number of passengers at the age of each passenger; Each Tour that will be returned has a list of activities where each activity will have its individual properties within that Tour.
GetPaymentPolicies: Used to check the Cancellation Policies for the chosen Tour.
DoBooking: Used to confirm a reservation, it sends the information of the passenger (s), payment information, the Tour and the chosen activity.
CancelBooking: Used to cancel a reservation.
Below you will find more information on the most important rules, possibilities, points of attention and properties to use for each method.
Each Operator will have its own instance of the Cangooroo Booking Engine and, with that, each will have its own endpoint. Unless specified otherwise, your Operator's endpoint will curently be:
https://ws-[OPERATOR].cangooroo.net/ws/2013/tour_c.asmx
Please note the words in BOLD on the example above since those will vary depending on the Operator you're integrating against.
This is where everything begins. The Search Request is where you will pass your Credentials, the destination city ID, and a list of passengers (where each passenger will be separated by age) and a similar list for children, must also be informed the language, checkin date and checkout date that will be spent on the Tour.
To see all properties contained in the Search Availability Request and Response, please refer to this reference page.
Our SearchAvailability Request is pretty simple and below you will find the most common usage of this method as well as some examples for the most Frequently Asked Questions we have.
The credentials tag is fairly simple and only has the UserName and the Password as shown below:
<ws:credential>
<ws1:UserName>?</ws1:UserName>
<ws1:Password>?</ws1:Password>
</ws:credential>
tag is where you're supposed to put in the UserName given you by the Operator. While the Password is where you're supposed to insert the Password given you by the Operator.
the criteria section will be used for the specifications of your search, in it you will inform the Id of the city where the Tour will be made, the age of the children, the age of the adults, languages of the Tour and the dates of CheckIn and checkOut of you want to spend on the Tour.
In this tag is informed the id of the city where the user wants to carry out the tour.
<can:CityId>1009709</can:CityId>
Here you will be informed the age of the children that will be in the Tour, where for each child will be used a new tag, as can be seen in the example below (if this property is null, the tag can be excluded)
<can:ChildAges >
<can:int>5</can:ChildAges >
<can:int>3</can:ChildAges >
</can:ChildAges >
after informing the amount of children, it will be necessary to inform how many adults will participate in the Tour, this tag works similarly to the previous one, however, this tag can not be null.
<can:AdultAges>
<can:int>35</can:int>
</can:AdultAges>
Here the language of the service will be informed. If the user wants to search for a specific language tour, he / she must enter the language below (if the user does not want to search for a specific language, he can enter "all" Tour with the parameters that the user informed previously).
<can:ServiceLanguage>pt_BR</can:ServiceLanguage>
here the user will inform the checkIn and ckeckOut dates of the Tour service.
<can:InitialServiceDate>2019-04-26</can:InitialServiceDate>
<can:FinalServiceDate>2019-04-27</can:FinalServiceDate>
Our SearchAvailability Response will hold all the results given your Criteria, separated by Tours( <TourItem> ) and Activities in each Tour( <ActivitySearch> ). Below you will find the most important sections and properties and to see all the properties and what each of them mean, please see our reference page.
The <Token> tag is extremely important, as explained on our Services page. You will need this token to confirm the reservation of choosen tour and this information should be transported with each subsequent request.
A Token will always be unique and the combination of Token + Credentials + expiration ensures that we will never have matching results stored on our servers.
The TotalToursResults field provides information on the total number of results found, lastly the number of results in this single response.
When your search provides larger sets of results, those that affect the performance of your application and on those occasions, you will have to work with filters and paging our results.
The SearchAvailability Response will always be a composition of multiple Tours with multiple Activities each, thus creating a list within a list. That is important to keep in mind since you will probably have to iterate through each of them to go over all the results we returned.
Inside those lists, the <ResponseId> tag and the <Id> tag must be mentioned since they behave very differently. While the <ResponseId> is an integer value and will hardly change, the <Id> is a integer value and will change constantly since it is the encrpyted result of multiple information. Therefore, never assume the Room Id format or size nor map it because it is a dynamic value.
The GetPaymentPolicies is the method you should call after receiving the Search Response and after you've selected the tour and activity you wish to book. This is a mandatory step for our booking process, which means that you will must make this call before attempting to confirm your booking.
It is important to be aware that many Suppliers work with cached information to decrease response time when responding to availability requests. Therefore, some values may change from the Search Availability Response for Payment Policy Response, such as price, rate information, and other properties. That is why it is important to compare, verify and update your information and properly notify the user in case of changes.
To see all properties contained in the Get Cancellation Policies Request, please refer to our reference page.
The GetCancellationPolicies Request is pretty direct and simple and below you will find the most Frequently Asked Questions we have about it.
The credentials tag is the same as required on the SearchAvailability with a UserName and a Password as shown below:
<ws:credential>
<ws1:UserName>?</ws1:UserName>
<ws1:Password>?</ws1:Password>
</ws:credential>
The UserName tag is where you're supposed to put in the UserName given you by the Operator. While the Password is where you're supposed to insert the Password given you by the Operator.
As stated before, the Token you received on the SearchAvailability Response is extremely important because it is this information that binds the booking process together. To learn more about the Token, you can check our Services page.
You must pass the Token on the <Token> tag as shown below, since the combination of your Token + Credentials + expiration time will guarantee that you will have access to the tours returned to you on the SearchAvailability Response.
<Token xmlns="Cangooroo.WS_2013.Tour">636e367c-6b5d-44dc-b38e-101fa1db45be</Token>
the TourId is the id of the chosen tour, each tour has a list of different activities where the price and days may vary.
<ws:tourId>45230</ws:tourId>
is the id of the selected activity, after choosing the desired tour must be informed the id of the desired activity.
<ws:disponibilityId>1</ws:disponibilityId>
is the date of the tour, the user will inform the date of the desired tour activity in yyyy/mm/dd HH:MM format.
<ws:serviceDate>2019-04-26T14:19:00</ws:serviceDate>
In response, in addition to showing the tour information, the cancellation deadline and the chosen activity, will also return the questions of the supplier, the questions and their quantity may vary for each supplier, in some cases may be void.
In addition to the information updated by the supplier, the user will also see the cancellation policies of the chosen Tour, in these tags it is possible to observe the deadline for service cancellation (<StartDate>) after being hired without having to pay the fine of the fine along with the payment currency can be seen in the <Price> tags).
<CancellationPolicies>
<CancellationPolicy>
<StartDate xmlns="WS_2013.Common">2019-04-21T14:19:00</StartDate>
<EndDate xmlns="WS_2013.Common">2019-04-26T14:19:00</EndDate>
<Price xmlns="WS_2013.Common">
<Currency xmlns="WS_2013">USD</Currency>
<Value xmlns="WS_2013">696.8</Value>
</Price>
</CancellationPolicy>
</CancellationPolicies>
The DoBooking method is used to make the reservation of the Tour and the activity that was chosen in SearchAvaliability and dealt with in GetCancellationPolices, this is another simple but very important step, as it will inform the main passenger and the companions and also answer questions from the supplier ( if it has returned in GetCancellationPolices).
To see all properties contained in the doBooking Request and Response, please refer to our reference page.
The credentials tag is the same as required on the SearchAvailability and GetCancellationPolicies Request with a UserName and a Password.
<ws:credential>
<ws1:UserName>?</ws1:UserName>
<ws1:Password>?</ws1:Password>
</ws:credential>
The UserName tag is where you're supposed to put in the UserName given you by the Operator. While the Password is where you're supposed to insert the Password given you by the Operator.
In this tag will be informed the id of the Tour chosen by the user and treated in the GetCancellationPolicies
<can:ResponseId>45243</can:ResponseId>
Here will be informed the data of all passengers who were informed in SearchAvaliability, the age criterion for children varies for each provider, in an example, if the user informs a child of 16 years of age and the supplier accepts the reservation will be confirmed, otherwise a technical problem will occur because this provider can accept children up to 12 years of age.
for each informed passenger, will have a Pax object with several tags where each one represents information about the passenger.
Usually the first passenger to be informed is the main one, but the rest are considered normal passengers.
<can:Pax>
<ws2:AddressNumber>1234</ws2:AddressNumber>
<ws2:CEPAddress>05560481</ws2:CEPAddress>
<ws2:DDI>55</ws2:DDI>
<ws2:DDD>11</ws2:DDD>
<ws2:PhoneNumber>40028922</ws2:PhoneNumber>
<ws2:Birthday>1993-11-14</ws2:Birthday>
<!--Optional:-->
<ws2:Name>Name</ws2:Name>
<!--Optional:-->
<ws2:LastName>NoBook</ws2:LastName>
<ws2:Age>23</ws2:Age>
<ws2:EnumTitle>Mr</ws2:EnumTitle>
<ws2:EnumPaxType>Main</ws2:EnumPaxType>
<ws2:PassengerEmail>Email.Test@t4w.com.br</ws2:PassengerEmail>
</can:Pax>
These are the vendor's questions that were presented in GetCancellationPolicies, here the user will respond to them and send their responses to the vendor.
If no vendor question is returned in GetCancellationPolicies this tag can be excluded.
<can:ProviderQuestions>
<!--Zero or more repetitions:-->
<can:QuestionaryRequest>
<!--Optional:-->
<ws3:QuestionCode>?</ws3:QuestionCode>
<!--Optional:-->
<ws3:Answer>?</ws3:Answer>
</can:QuestionaryRequest>
</can:ProviderQuestions>
In this tag you will be informed the Tour ID chosen by the user and treated in the GetCancellationPolicies, it should be the same one that was informed in the ResponseId tag.
<can:BookingId>45243</can:BookingId>
After informing the chosen Tour, the Id of the activity chosen by the user must be informed.
<can:TourItemId>1</can:TourItemId>
It is the id of the operator responsible for the reservation.
<can:ResponsibleOperatorId>0</can:ResponsibleOperatorId>
For the realization of some Tours, it is mandatory to reserve a Hotel, in case a reservation is required, the hotel id must be informed in this field.
<can:HotelId>?</can:HotelId>
The token generated in the search and handled in the GetCancellationPolicies will be used for the last time to close the Tour reservation.
remembering that each Token is unique for each search and in case the user wants to make a new reservation, it must carry out a new research.
<ws:token>54db8c34-be37-46f1-9004-306c2206898b</ws:token>
The date the user booked service occurs.
<ws:departureDate>2019-04-27T14:19:00</ws:departureDate>
This method is very simple, in which you will informe, in addition to the credentials of the customer, the ServiceId of your reservation made in the previous method.
in the request it will be necessary to inform only 3 parameters, below you can see which parameters are these.
for more information about the request and response fields of this method, please visit our reference page.
The credentials tag is the same as required on the SearchAvailability, GetCancellationPolicies and doBooking Request with a UserName and a Password as shown below:
<ws:credential>
<ws1:UserName>?</ws1:UserName>
<ws1:Password>?</ws1:Password>
</ws:credential>
After you enter the credentials of the user, the ServiceId of a reservation that was made with the credentials informed must be passed.
<ws:serviceId>1483</ws:serviceId>