Hotel
Hotel contracts
Search
This is where everything begins, your booking flow should start here. Use the credential provided by the Cangooroo license owner (see the section authentication and authorization). The response will have the token that allows you to use the next methods and complete your booking flow.
Request
The Search Request is pretty simple, below you will find the most common usage of this method as well as some examples for the most Frequently Asked Questions we have.
{
"Credential": {
"Username": "your_Username",
"Password": "your_Password"
},
"Criteria": {
"DestinationId": "1003937",
"CheckinDate": "2020-04-01",
"NumNights": "1",
"Filters": {
"CheapestRoomOnly": "?",
"MaxPrice": "?",
"MinPrice": "?"
},
"HotelsIds": [],
"MainPaxCountryCodeNationality": "?",
"ReturnExtendedHotelStaticData": "?",
"ReturnHotelStaticData": "?",
"ReturnOnRequestRooms": "?",
"SearchRooms": [{
"ChildAges": [],
"NumAdults": "?",
"Quantity": "?"
}],
"Timeout": "?",
"SearchType": "?"
}
}
Credential
The credentials tag is fairly simple and only has the UserName and the Password as shown below:
"Credential": {
"Username": "your_Username",
"Password": "your_Password"
},
The UserName space 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.
Criteria
The Criteria section is where you define what you are looking for and you will find the explanation for all the sections and most important properties.
DestinationId
Is the ID of the destination city, where the user wishes to reserve the room.
"DestinationId": 1003937,
NumNights
The NumberOfNights field defines how long the user wants to spend.
"NumNights": 5,
SearchType
The default value for the search type is hotel. If you want to search for home, use the value "home".
"SearchType": "Hotel",
ReturnHotelStaticData
This property is responsible for returning hotel data such as latitude, longitude, hotel category, thumbnail used, hotel name and hotel id.
"ReturnHotelStaticData": false,
ReturnOnRequestRooms
Some providers already leave rooms reserved in some hotels to always have 1 room to book at that hotel, this field will show if the passenger wants to see these rooms in their search.
"ReturnOnRequestRooms": false,
CheckinDate
The CheckInDate field sets the check-in date for the desired reservation, note that the date format should be yyyy-mm-dd.
"CheckinDate": "2026-12-25",
HotelId
The maximum recommended is 300 Hotel ID's per request.
MainPaxCountryCodeNationality
It is the code that informs the nationality of the main passenger.
"MainPaxCountryCodeNationality": "BR",
SearchRooms
The SearchRooms field is an object that can receive from 2 to 3 different parameters.
The first one is the NumAdults that would receive the number of adults looking to stay.
"NumAdults": 1,
The second field to be completed is the children's ages, this is an optional field if the user wishes to travel with one or more children, he or she must state their ages, otherwise this field does not have to be completed and your request may be excluded.
"ChildAges": [7],
The third field is the number of rooms that the user wishes to reserve.
"Quantity": 1
Here are two separate examples of SearchRooms.
The first example below is a survey done for 1 child and 1 adult:
"SearchRooms": [{
"NumAdults": 1,
"ChildAges": [7],
"Quantity": 1
}]
The second example is a similar survey, however for only 1 adult
"SearchRooms": [{
"NumAdults": 1,
"Quantity": 1
}]
* Remember that a hotel search can only be done if the children are accompanied by at least 1 adult(MainPax), if a search is made with 0 adults, no hotel will be returned.
Filters
These are filters that can be used in the search, returning hotels based on user preferences, this is an optional field, so it is up to the user to fill it out or not.
"Filters": {
"MinPrice": 100.00,
"MaxPrice": 1000.00,
"CheapestRoomOnly": true,
"SelectedHotelsIds": [489479, 449267]
}
The properties below are related to the price range that will be returned to the user, so you can set a minimum price and a maximum price for your reservation.
"MinPrice": 100.00,
"MaxPrice": 1000.00,
The following property will receive a Boolean value, and if the value is true, will return only the cheapest room of each Hotel.
"CheapestRoomOnly": true,
A list of hotels Ids you want to search.
"SelectedHotelsIds": [489479, 449267]
If you have package rates available and want to hide it use the flag below:
"HidePackageRate": true
Response
Below you will find the most important sections and properties in the search response.
Token
The Token field is extremely important, as explained in our Services page. You will need this Token in order to confirm your booking and this information should be carried with each following Requests you make.
A Token will always be unique and the combination of Token + Credentials + expiration time guarantees that we will never have matching results stored within our servers.
Fields such as TotalHotelResults and TotalTime will give you information about the whole number of results we found and how many time has passed since the request
When your search gives you larger sets of results, those can affect your application's performance and in those occasions, you will have to work with filters and pagination of our results.
Hotels and Rooms
The Search Response will always be a composition of multiple Hotels with multiple Rooms 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 HotelId fields and the RoomId field must be mentioned since they behave very differently. While the HotelId is an integer value and will hardly change, the RoomId is a string value and will change constantly since it is the encrpyted result of multiple information. Therefore, never assume the RoomId format or size nor map it because it is a dynamic value.
Rooms extedend information, when available, should be matched using the RoomMediaId property. The data is available in our content API.
Other properties in the Search Response
We return a lot of information for each result. The decision of which of them you will use and how will depend largely on your Operator's strategy and your integration purpose.
getBookingConditions
The getBookingConditions (if you have already used older versions of our API this substitutes the getCancellationPolicies method) must be used before you use doBooking method.
It's important to be aware that your search result could have cached information. This is used to decrease supplier's search response time. Because of that some times rate information (such as prices, descriptions, cancellation policies, etc) might change. It is important that you compare, verify and update your information and properly notify your user in case of any changes.
If you need to have a token that lasts more than 30 minutes you can ask to have the "retoken" module. Please read this article.
Request
The getBookingConditions Request is pretty direct and simple and below you will find the overview of this method. Please read our FAQ, specially this question, to avoi errors.
Credentials
The credentials tag is the same as required on the Search Request with a UserName and a Password as shown below:
"Credential": {
"Username": "your_Username",
"Password": "your_Password"
},
Token
As stated before, the Token you received on the search response is extremely important because it is this information that binds the booking process together. To learn more about the Token, click here.
You must pass the Token on the Token field as shown below, since the combination of your Token + Credentials + expiration time will guarantee that you will have access to the rooms returned to you on the SearchAvailability Response.
"Token": "99f97a37-5b71-468e-995b-56db85081a12",
Hotel Id and Room Ids
HotelId field is where you must pass the Id of the desired hotel for the room or rooms you've chosen from the search Response. Is important to note that you can only call the getBookingConditions method for one Hotel Id at a time, meaning that you can't have more than one Hotel Id on the same Request.
The RoomIds fieldis a String list, meaning that you can request the cancellation policies for more than one Room at a time, provided that they're all rooms in the same Hotel. However, you should request the exact configuration of rooms that you searched for, which means that if you're trying to book 2 rooms, you should pass 2 and only 2 room id; if you're trying to book 1 room, you should pass 1 room id.
"HotelId": 622455,
"RoomIds": ["3160005"]
In order to request the getBookingConditions Policies for other rooms from your Search Availability Result, you must do so in a new getBookingConditions request. Essentially you can make many different getBookingConditions requests, but all of them must have the exact quantity of rooms you searched for.
In order to have a better user experience you can use the "GetNextRoomOnError" parameter. By sending this value as true Cangooroo will offer another room if the one you requested is not available to be booked. Note that the return will have a new node "RoomsNextOption" and you can decide the best way to present that information in your system.
Response
The field "MoreInformation" contains important informations that you should display to your user such as Taxes that should be paid at destination (resort fees, city taxes), etc.
It's mandatory that you recheck the price and currency, cancellation policies and other fields in the response of this method, because there'are suppliers that have cache in availability method and information can change.
It's mandatory that you check the HotelInfo (name and address) that we return in the response in order to check if it's the same hotel that you requested in search availability. If for some reason has a mapping error and we returned the correct hotel, we don't assume the costs.
You'll find taxes that are payed directly at the hotel under the PropertyTaxes structure.
The response is detailed booking details information.
doBooking
This method is used to confirme the booking. Besides the credential an token that need to be informed you must also inform the room, passenger and payment details
Credentials
The credentials tag is the same as required on the Search Request with a UserName and a Password as shown below:
"Credential": {
"Username": "your_Username",
"Password": "your_Password"
},
Token
As stated before, the Token you received on the search response is extremely important because it is this information that binds the booking process together. To learn more about the Token, click here.
You must pass the Token on the Token field as shown below, since the combination of your Token + Credentials + expiration time will guarantee that you will have access to the rooms returned to you on the SearchAvailability Response.
"Token": "99f97a37-5b71-468e-995b-56db85081a12",
RoomId
To reserve the chosen room, the roomId must be informed:
"RoomId": 123456
Passengers
Here you will be informed the data of each of the passengers in list format, where each passenger must inform their name, surname, CPF among others, this is a very important step since the first passenger to be informed here will be considered the main passenger.
"Passengers": [{
"Name": "test",
"Surname": "NoBook",
"Age": 25,
"Cpf": "011.400.289-22",
"Title": "Mr",
"MainPax": true,
"isChild": false,
"Address": "Rua do Rocio",
"City": "São Paulo",
"ZipCode": "04552000",
"State": "São Paulo",
"AddressNumber": "123",
"Email": "emailtest@t4w.com.br",
"PhoneDDD": "11",
"PhoneDDI": "55",
"PhoneNumber": "40028922"
}]
Payment
This field refers to the payment data of the user, if the user chooses to make the payment, or if the agency is anticipated and the reservation is in penalty, cangooroo will make the payment.
To make a payment it is necessary to inform the payment condition registered in our system in which the payment will be processed.
It is possible to obtain the payment condition id through the payment endpoint in the getPaymentConditionsByToken method
Important: If the chosen room has a prepayment fee or direct payment at the hotel, the card can be sent without informing the paymentConditionId and will only be sent to the supplier.
"Payment": {
"PaymentConditionId": "?",
"PaymentRequestCC1": {
"ContractingParty": {
"Address": "?",
"AddressComplement": "?",
"AddressNumber": "?",
"CPF": "?",
"CityName": "?",
"CountryCode": "?",
"DistrictName": "?",
"Email": "?",
"PersonName": "?",
"PhoneNumber": "?",
"PhoneNumberDDD": "?",
"PhoneNumberDDI": "?",
"ReceiveCreditCardReceipt": "?",
"StateCode": "?",
"ZipCode": "?"
},
"CreditCard": {
"CardNumber": "?",
"CardOperator": "?",
"Holder": "?",
"MonthExpiration": "?",
"NumberPayments": "?",
"SecurityCode": "?",
"YearExpiration": "?"
}
}
SetWaitingPayment
When you send SetWaitingPayment as true, your reservation will be created with the status awaiting payment. The reservation will be available for confirmation until the token expires and if it is not paid, it will be rejected. When paying within the period, the reservation will be sent to the supplier for confirmation.
To see all the properties contained in the Booking Request, please see our reference page.
CancelAllHotelServices
Use this method to to cancel all hotel services in a file (reservation). Please be aware that only hotel services will be canceled using this method. If you want to cancel all services from a file please use some backoffice method.
CancelByService
Use this method to cancel a specific service in a file (reservation). Please be aware that some services cannot be canceled alone, all services need to canceled and in this case, this method returns an error.
CheckBookingStatus
Use this method to check if the booking exists in the system or not. Please read this article to get a suggestion on how to use it.
URL and Examples
SOAP
http://ws-[clientIdentification].cangooroo.net/API/SOAP/Hotel.svc
REST
REST: http://ws-[clientIdentification].cangooroo.net/API/REST/Hotel.svc