Introduction and Concepts
Through this function, users can create their own Widget to embed in web sites in order to access IBE (KIU INTERNET BOOKING ENGINE) and it´s functionalities. This document is a guideline to get content and connect to the application.
What is a Widget?
It is a form on HTML with .CSS that can be displayed into an iframe on the client´s web page or other sites.
Does KIU offer a Widget?
Yes. KIU provides a standard Widget once IBE has created, nevertheless it might not fit the web site´s corporate requirements, such as height, width, etc.
Is the custom Widget based on the IBE´s general configuration?
Yes, indeed the widget is based on the IBE configuration and site´s content in order to accomplish operative and commercial requirements. Previously mentioned information resides on the IBE´s Back office and should been completely configured once the widget created. Within this document, you will find some examples on how to connect your custom widget with the IBE.
In order to make a POST to the flight search services it is necessary to add the host from where the widget is going to be served to the IBE's white listed sites and which IBE environment is going to point to. This information shall be sent to webservices@kiusys.com to be authorised
Uploading Content to Widget
Whenever a user creates a form in order to build a widget for KIBE, there are some mandatory fields that must be included in order to send the minimal information to make it work and retrieve content.
To get this content and the information required for the KIBE application to work, developers have added the following Script into the <head> tag of the form.
<script>
$(document).ready(function(){
$.ajax({
url: "[KIBE URL domain]/api/get_complete_config_widget/",
success: function(response){ formatResponse(response);},
dataType: "jsonp"
});
//Example of how to consume the data
function formatResponse(response){
$("#csrfmiddlewaretoken").val(response.csrf_token);
$.each(response.airports.keys.origin, function(i,e){
$("#id_origin").append("<option value='"+ e.data +"'>"+ e.value +"</option>")
})
$.each(response.airports.keys.destination, function(i,e){
$("#id_destination").append("<option value='"+ e.data +"'>"+ e.value +"</option>")
})
}
});
</script>
URL: The KIBE domain has to be declared (this data is provided by KIU once KIBE is created), followed by the parameters /api/get_complete_config_widget/.
(e.g.: https://kibe-dev-xx.kiusys.net/api/get_complete_config_widget/).
This URL will return the following response on JSON format:
{
"passengers": {
"max_pax_allowed": 9,
"pax_config": [
{
"max_age": null,
"enable": true,
"name": "ADULT",
"min_age": 12
},
{
"max_age": 12,
"enable": true,
"name": "CHILD",
"min_age": 2
},
{
"max_age": 2,
"enable": true,
"name": "INFANT",
"min_age": 0
}
]
},
"csrf_token": "vgTgLRd6L1XKeeJdWdMSPDOhyUURzF02XJUl0CarwNc3ABHAQeWdMkmgi93QMVOI",
"airports": {
"keys": {
"origin": [
{
"code": "AEP",
"data": "QUVQ",
"value": "BUENOS AIRES (BUE), JORGE NEWBERY AIRPORT (AEP), Argentina"
}
],
"destination": [
{
"code": "MDQ",
"data": "TURR",
"value": "MAR DEL PLATA (MDQ), ASTOR PIAZZOLA AIRPORT - MERY (MDQ), Argentina"
},
{
"code": "LAS",
"data": "TEFT",
"value": "LAS VEGAS (LAS), MCCARRAN INTERNATIONAL AIRPORT (LAS), United States"
}
]
}
},
"origin_destination": {
"keys": [
{
"origin": "AEP",
"destination": "MDQ",
"not_flying_days_return": [],
"not_flying_days_going": [],
"frequency_return": [
0,
1,
2,
3,
4,
5,
6
],
"frequency_going": [
0,
1,
2,
3,
4,
5,
6
],
"direct_fly": false
}
]
}
}
Response Dictionary
| Key | Description | Values / Format |
|---|---|---|
| Passengers | Supported passenger types and maximum quantity allowed. | Object |
| max_pax_allowed | Maximum quantity of passengers allowed. | Integer |
| pax_config | Supported passenger types (ADULT, CHILD and INFANT). | Object |
| max_age | Maximum age allowed per passenger category. It is within the pax_config node. | Integer / null |
| enable | Toggle that indicates if a category is enabled or disabled. It is within the pax_config node. | true / false |
| name | Name of the passenger category. It is within the pax_config node. | ADULT / CHILD / INFANT |
| min_age | Minimum age allowed for each passenger category. It is within the pax_config node. | Integer |
| csrf_token | Hash for validation purposes that must be included in the form submit. | HASH |
| airports | Object that contains the information of valid airports set for customer. This information is offered for validation purposes (Front-end validation). | Object |
| keys | List of origins-destinations set on Backoffice as allowed routes. This key is within the object airports. It represents which origin to which destination is allowed to request content. | Object |
| origin | List of enabled origin airports only. This field is within keys node. | Array |
| code | ISO IATA origin airport code. This key is within the origin node. | 3 Alphabetical chars |
| data | This is for internal KIBE purposes only. | 4 Alphabetical chars |
| value | Associated description of the airport code. This key is within the origin node. | Alphabetical |
| destination | List of enabled destination airports only. This field is within keys node. | Object |
| code | ISO IATA destination airport code. This key is within the destination node. | 3 Alphabetical chars |
| data | This is for internal KIBE purposes only. | 4 Alphabetical chars |
| value | Associated description of the airport code. This key is within the destination node. | Alphabetical |
| origin_destination | List of enabled commercial routes set in the KIBE Backoffice. | Object |
| keys | List of objects that contains the offered pair of airports enabled. This key is within the origin_destination node. | Array |
| origin | ISO IATA origin airport code. It is within the keys node. | 3 Alphabetical chars |
| destination | ISO IATA destination airport code. It is inside the keys node. | 3 Alphabetical chars |
| not_flying_days_return | List of week days for return flights not enabled to operate. It is within the keys node. | 0 to 6 (0: Monday; 1: Tuesday, etc.) |
| not_flying_days_going | List of week days for origin flights not enabled to operate. It is within the keys node. | 0 to 6 (0: Monday; 1: Tuesday, etc.) |
| frequency_return | List of week days for return flight enabled to operate. It is within the keys node. | 0 to 6 (0: Monday; 1: Tuesday, etc.) |
| frequency_going | List of week days for origin flights enabled to operate. It is within the keys node. | 0 to 6 (0: Monday; 1: Tuesday, etc.) |
direct_flight | Toggle that displays if the flight is direct or allows connections. | true / false |
| date_from | First available date for route. The field is within keys node. | DD/MM/YYYY |
| date_to | Last available date for route. The field is within keys node | DD/MM/YYYY |
Based on this response, developers have enough data to build display content on Widget fields like origin-destination and make the validations of routes enabled to search, types of passengers and quantity of passengers enabled to search and supported type of travel (One Way or Round Trip).
Search Flights
When processing the form in order to redirect to KIBE, the <form> tag must include:
- action: Target URL must be the KIBE´s domain.
- method: Must be POST.
Example:
<form class="searcher" id="search-form" name="searchWidgetForm" action="https://kibe-dev-xx.kiusys.net/" method="POST">
Once the user clicks on submit button, the KIBE will gather all the parameters (Origin, Destination, Departure date, Return date - If it exists - , Adult quantity, Child quantity, Infant quantity) and will then process the request and display the results into the KIBE´s environment. Once this process has been completed the regular booking-payment flow will be followed.
Suggested Validations
Despite of KIBE´s back-end validations, we strongly advice developers to pay attention to some other front-end validations that could help to process´ efficiency:
- Origin - Destination:
The JSON API response returns routes enabled for search, this routes are configured on the KIBE´s back office. Based on this information, developers can allow only searches that include an origin with only those destination airports that match on response. - Dates:
The supported date format is DD-MM-YYYY. Developers can display dates on different formats in order to make the user experience more comfortable, but they need to change dates on the mentioned format in order to avoid any validation error returned by KIBE. - Departure Date:
Departure date can be from the day in which the request is being made up to a maximum of 330 days in advanced. - ReturnDate:
The return date must not be before departure date and cannot exceed 330 days in the future. - Adult Passenger:
We recommend to set as default value for adult passengers in "1" and that it should not allow "0". This will prevent the creation of bookings for unaccompanied minors (this should be resolved on Airline offices). - Infant passengers:
According to industry logic, there should be only one infant passenger per adult passenger. If there is more than one infant per adult passenger, there must be more than one adult passenger for association purposes.