Using this API

Use the Air Rest API to search, verify policies, and book air travel with over 100 different vendors around the world.

The Air Rest has the following methods to be consumed, in this order:

• Search: used to define the type of flight you want, which places you will be traveling to, and the number of passengers and the age of the passengers that will travel with you.

• GetCancellationPolicies: used to check which are the Cancellation Policies for the chosen flight.

• DoBooking: used to confirm a booking, send passenger's and payment informations. Read more about the possible status here.

• CancelBooking: Used to cancel a flight reservation.

• GetServiceDetails: Serves to view the details of your reservation.

The API works with Json in its requests and responses, so text parameters can be identified by enclosing double quotation marks ("example"), numbers and boolean parameters can be sent normally.

Below you will find more information on the most important rules, possibilities, points of attention and properties to use for each method.

Air API endpoint

Each method will have its own instance in the Cangooroo Booking Engine and, with that, each one will have its own endpoint. The end points of the air services will be:

• {{URL}}/ws/Rest/Flight.svc/Search

• {{URL}}/ws/Rest/Flight.svc/GetCancellationPolicies

• {{URL}}/ws/Rest/Flight.svc/Booking

• {{URL}}/ws/Rest/Flight.svc/Cancel

• {{URL}}/ws/Rest/Flight.svc/GetServiceDetails

*Note the BOLD words in the example above, since they vary depending on the method you will be using.

Search

This is where everything begins. The Search Request is where you will pass your credentials, define where you want to travel, whether you are traveling round-trip or one-way, the class you wish to fly, whether you want flights with baggage included and of course, the day you want to travel.

To see all properties contained in the Search Request and Response, please refer to this reference page.

Search 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":{

"DepartureDate": "2020-01-20",

"ReturnDate": "2020-01-26",

"IataOriginAirport": "GRU",

"IataDestinationAirport": "GIG",

"NumberOfAdults": 1,

"ChildrenAge": [7],

"NationalityPax": "BR",

"SearchType": "RoundTrip",

"ClassFlight": "All",

"Luggage": "Both"

}

}

Credential

The credentials field 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 the type of flight you are looking for and you will find the explanation for all the most important sections and properties.

DepartureDate and DateBack

Here you enter the departure dates and return (ReturnDate) of your flight, if you choose a oneway trip the ReturnDate field can be excluded from your request.

"DepartureDate": "2020-01-20",

"ReturnDate": "2020-01-26",

OriginCity and DestinationCity

Here you will enter the airport code of origin and destination of the trip, the standard of sending 3 letters.

"IataOriginAirport": "GRU",

"IataDestinationAirport": "GIG",

Passengers information

Here is where you will be informed of the number of passengers that will be flying with your nationality, the first parameter to be passed is the number of adults, followed by the number of children next to their ages, the children's refueling fields are optional, if the passengers choose not to travel with children, the fields should be excluded.

Finally, we will have the field of nationality, where the nationality of the main passenger will be passed.

"NumberOfAdults": 1,

"ChildrenAge": [7],

"NationalityPax": "BR",

Flight Preferences

Here you will inform the type of flight you want to book, whether it is a one way trip or the return trip, the desired class and if you want a flight with baggage included.

"SearchType": "RoundTrip",

"ClassFlight": "All",

"Luggage": "Both"

Search Response

After completing the requested fields, a list of flights will be returned based on these information, below we will explain each of these fields.

Token and information about the number of results

The Token field is extremely important, as explained on our Services page. You will need this token to confirm the reservation of choosen flight 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 NumberOfResults 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.

Flights

Here a list of flights is returned based on the parameters passed in the request, some flights (both round and round) have stopovers in other countries and this will interfere in both the price of the flight and the time of travel.

* Note that round trip flight IDs are returned as stretchId as shown in the examples below the search return.

Departure:

"Depart":[

{

"Airline": "Test Airlines",

"AirlineCod": "TM",

"ArrivalDate": "20/01/2020 18:35:00",

"Class": "Executiva",

"DepartureDate": "20/01/2020 01:46:00",

"FlightNumber": "TO48591; TO27093; TO27239",

"IataDestinyAirport": "GIG",

"IataOriginAirport": "GRU",

"Id": 1,

"Luggages": [...],

"QtdStops": 2,

"Legs": [...],

"Id": 2

}

]

Return:

"Return":[

{

"Airline": "Test Airlines",

"AirlineCod": "TM",

"ArrivalDate": "20/01/2020 18:35:00",

"Class": "Executiva",

"DepartureDate": "20/01/2020 01:46:00",

"FlightNumber": "TO48591; TO27093; TO27239",

"IataDestinyAirport": "GIG",

"IataOriginAirport": "GRU",

"Id": 1,

"Luggages": [...],

"QtdStops": 2,

"Legs": [...],

"Id": 2

}

]

These IDs will be used in cancellation policies to inform you of the outbound flight, and if so, the return flight.

GetCancellationPolicies

GetCancellationPolicies is the method to which you should call as soon as you receive the survey response, and then select the flight service you want to reserve. This is a mandatory step for our booking process, which means you must make this call before attempting to confirm your reservation.

It is important to be aware that many vendors work with cached information to decrease response time when responding to requests. Therefore, some values can be changed from Search Response to 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 the properties contained in the Cancellation Policy Request, please see our reference page.

Get Cancellation Policies Request

The GetCancellationPolicies Request is pretty direct and simple and below you will find the most Frequently Asked Questions we have about it.

{

"Credential": {

"Username": "Your_Username",

"Password": "Your_Password"

},

"Token": "917eb346-660e-4e7d-9717-25cb381a4221",

"SolutionId": "17",

"DepartId": "1",

"ReturnId": "2"

}

Credentials

The credentials field is the same as required on the Search 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, you can check our Services page.

You must pass the Token in the Token field as shown below, since the combination of your Token + Credentials + expiration time will ensure that you have access to the flight services returned to you in the Search SearchResponse.

"Token": "917eb346-660e-4e7d-9717-25cb381a4221",

SolutionId

It is the service id (SolutionId) next to the outbound flight ID (DepartureId) and, if it has, the return flight id (ReturnId).is the id of the chosen service returned in Search, then the id of the outbound flight (DepartureId) must be informed and if the user has opted for a return flight, the flight id must be informed (ReturnId).

"SolutionId": "17",

"DepartId": "1",

"ReturnId": "2"

Get Cancellation Policies Response

In response, in addition to displaying the chosen flight service information with the updated data, cancellation policies will also be returned.

CancelationPolicies

In addition to the information updated by the supplier, the user will also see the description of the service updated by the supplier.

"CancelationPolicies": "Após a emissão, consulte a Operadora."

PaymentConditions

If available, the payment terms of the service, along with the accepted cards and minimum value of each installment can also be seen.

[

{

"CreditCard": {

"MinimumParcelValue": {

"Currency": "BRL",

"Value": 15

},

"NumberPaymentAmex": 6,

"NumberPaymentDiners": 6,

"NumberPaymentElo": 6,

"NumberPaymentMaster": 6,

"NumberPaymentVisa": 6

},

"Name": "Parcelamento direto na Gol sem Juros"

}

]

doBooking

The DoBooking method is used to confirm the reservation of the flight that was chosen in the survey and dealt with in the GetCancellationPolices, this is another simple but very important step, as it will inform the main passenger and the escorts (if any).

To see all the properties contained in the doBooking Request and Response, please see our reference page.

doBooking Request

The DoBooking request is already a bit more complex, in addition to informing the IDs of the outbound flights and (if it has) return, the passenger must inform the main passenger (The first informed passenger is considered the principal).

{

"Credential": {

"Username": "Your_Username",

"Password": "Your_Password"

},

"Token": "a4670c56-8b92-43fb-84dd-eb37b748e583",

"SolutionId": 17,

"DepartId": 1,

"ReturnId": 2,

"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":{

"CreditCard": {

"Holder": "Nikolas K",

"CardNumber": "4111111111111111",

"SecurityCode": "123",

"YearExpiration": 2020,

"MonthExpiration": 12,

"Installments": 3,

"CardOperator": "VISA"

}

}

}

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

The token that was generated in the survey and handled in the GetCancellationPolicies will be used for the last time to close the room reservation.

"Token": "7c1088f2-6a0b-4a1a-9548-66768adee375",

SolutionId and Tacks Ids

It is the service ID (SolutionId) followed by the outbound flight Id (DepartureId) and, if it has, the return flight ID (ReturnId) that were returned in the search and handled in the GetCancellationPolicies.

"SolutionId": "17",

"DepartId": "1",

"ReturnId": "2",

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.

"Payment":{

"CreditCard": {

"Holder": "Nikolas K",

"CardNumber": "4111111111111111",

"SecurityCode": "123",

"YearExpiration": 2020,

"MonthExpiration": 12,

"Installments": 3,

"CardOperator": "VISA"

}

}

doBooking Response

Here you can see the result of your request, along with other information on your booking, such as the number of flights (both the outbound and the return flights), reservation Id, flight dates, it is worth noting the ServiceId fields that shows the reserved service id and the Status field that shows the status of your reservation in the system.

Cancel

This method is very simple, where the client will inform, in addition to the credentials of the client, the ServiceId of his reservation made in the previous method.

To see all properties contained in Cancel request and response, see our reference page.

Cancel Request

This is a simple method, because with it the customer can cancel their reservations made in the system, being necessary only the service id that is generated in the booking process.

{

"Credential": {

"Username": "cangooroov3",

"Password": "cangooroo@123"

},

"ServiceId": 379

}

Credential

The credentials tag is the same as required on the Search, cancellationPolicies and DoBooking Request with a UserName and a Password as shown below:

{

"Credential": {

"Username": "Your_Username",

"Password": "Your_Password"

},

ServiceId

After you enter the credentials of the user, the ServiceId of a reservation that was made with the credentials informed must be passed.

"ServiceId": 379

Cancel Response

In the answer of this method the customer can see the status of his reservation and verify that it has been successfully canceled, it is worth noting that if a reservation is canceled after its cancellation policies take effect, the customer may pay a fine for the service.

GetServiceDetails

In this method the user can check the details of his reservation without making any changes.

GetServiceDetails Request

The request of this method is similar to that of cancel, besides the credentials the client will inform the id of the reserved service (ServiceId).

{

"Credential": {

"Username": "cangooroov3",

"Password": "cangooroo@123"

},

"ServiceId": 379

}

GetServiceDetails Respose

in the response the customer will be able to see the details of his reservation, such as the status of his reservation, the payment status, cancellation policies and flight data.