| Table of Contents |
|---|
Objective:
|
Introduction and Concepts
Through this function, users can create their own Widget to embed in web sites in order to access KIBE IBE (KIU INTERNET BOOKING ENGINE) and it´s functionalities. This document is a guideline to get content and connect to the application.
Concepts
What is a Widget?
It is a form on HTML with .CSS that can be embedded displayed into an iframe on the client´s web page or other sites.
Does KIU offer a Widget?
Yes. KIU provides a standard Widget when KIBE is once IBE has created, but maybe nevertheless it might not follow fit the web site´s corporate requirements, such as height, width, etc.
Is the custom Widget based on the KIBE IBE´s general configuration?
The Widget is indeed Yes, indeed the widget is based on the KIBE IBE configuration and site´s content of the site in order to accomplish the operating operative and commercial requirements. All this Previously mentioned information resides on the KIBE Backoffice IBE´s Back office and should be been completely configurated configured once the Widget is widget created. Within this document, you will see find some examples of on how to connect your custom Widget widget with the KIBEIBE.
Getting content to build a Widget.When a user creates a form in order to build a widget for KIBE, there are some mandatory fields that it should have in order to send the minimal information to make it work and get content.To get that content and the information required for the KIBE application to work, developers have to add the following Script into the head tag of the form.
| Code Block | ||||
|---|---|---|---|---|
| ||||
| Tip | ||||
| ||||
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 |
| Tip | ||
|---|---|---|
| ||
In order for the carrier can use the custom widget it is necessary to add the following information in the carrier´s settings.
Both carrier DNS/HOST. |
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.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<script> $(document).ready(function(){ $.ajax({ url: "[KIBE URL domain]/api/get_complete_config_widget/?callback", 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/?callback.
(e.g.: https://kibe-dev-xx.kiusys.net/api/get_complete_config_widget/?callback).
This URL will return the following response on JSON APIformat:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{ "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
}
],
"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_fly | Toggle that displays if the flight is direct or allows connections. | true / false |
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:
},
"country_settings": {
"label_en": "Currency",
"label_es": "Moneda",
"currency_config": [
{
"country_setting": 1,
"ISO_currency": "ARS",
"ISO_country": "AR",
"description_es": "Peso Argentino - ARS $",
"description_en": "Argentine Peso - ARS $",
"device_id": "MIA00XXW01",
"agent_sine": "MIA00XXAB",
"default": true,
"enabled": true
},
{
"country_setting": 2,
"ISO_currency": "UYU",
"ISO_country": "UY",
"description_es": "Peso Uruguayo - UYU $",
"description_en": "Uruguayan Peso - UYU $",
"device_id": "MIA00XXW01",
"agent_sine": "MIA00XXAB",
"default": false,
"enabled": true
},
{
"country_setting": 3,
"ISO_currency": "CLP",
"ISO_country": "CL",
"description_es": "Peso Chileno - CLP $",
"description_en": "Chilean Peso - CLP $",
"device_id": "MIA00XXW01",
"agent_sine": "MIA00XXAB",
"default": false,
"enabled": false
}
]
},
"type_of_journey": {
"one_way": true,
"round_trip": 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 |
| country_setting | Object that contains configurations for currency and countries | Object |
| label_es | Label for Spanish that contains information of currency/country | 50 alphanumeric characters |
| label_en | Label for English that contains information of currency/country | 50 alphanumeric characters |
| currency_config | Is an object with the configuration needed by the field DESCRIPTION of the country_settings table records allowed in RES for the parameters: DEVICE, USER, ISO_COUNTRY and ISO_CURRENCY | Object |
| country_setting | Code for country settings registry. The field is within currency_config object | Numeric |
| ISO_currency | Currency code for quotation in KIU RES. The field is within currency_config object | 3 alphabetic characters |
| ISO_country | Country code for quotation in KIU RES. The field is within currency_config object | 2 alphabetic characters |
| description_es | Spanish description of the registry. The field is within currency_config object | 50 alphanumeric characters |
| description_en | English description of the registry. The field is within currency_config object | 50 alphanumeric characters |
| device_id | Device id used in KIU RES. The field is within currency_config object | 10 alphanumeric characters |
| agent_sine | User id used in KIU RES. The field is within currency_config object | 9 alphabetic characters |
| default | Field that declares default registry. The field is within currency_config object | true / false |
| enabled | Field that declares whether the registry is displayed or not. The field is within currency_config object | true / false |
| type_of_journey | Contains object with the default type of journey. | Object |
| one_way | Controls default selection of One Way trip at the front end. | true / false |
| round_trip | Controls default selection of Round Trip trip at the front end. | true / false |
Based on this response, developers have enough data to build display content on Widget fields
- Origin and destination
- Available routes/dates
- Types of passengers
- Quantity of passengers
- Type of travel (One Way or Round Trip)
- Currency/country
Form
Submit [ POST ]
The form will communicate with KIBE through a simple SUBMIT of the carrier's HOST
Authorisation Form
For making a POST / SUBMIT in KIBE's form, it's mandatory to received the field csrfmiddleware token with the API's HASH in the field csrf_token. If the HASH is not received, KIBE will respond to the request with 403 Forbidden.
Expected Fields
KIBE application will expect the following fields in order to proceed with the flight search/quotation
Field names should be respected when the POST is done in order to have a proper quotation and flight search
Field Name | Description | Values/Format |
|---|---|---|
csrfmiddlewaretoken | Authorisation HASH | HASH |
one_way | If oneway parameter will be sent as true, if roundtrip it won't be sent. | True |
origin | IATA airport code for origin | 4 alphabetic characters |
destination | IATA airport code for destination | 4 alphabetic characters |
departure_date | Departure date | DD/MM/YYYY |
return_date | Arrival date, if it is oneway this field should be empty. | DD/MM/YYYY |
adults | Amount of adult passengers, at least one should be sent for search and quotation | Numeric |
minors | Amount of child passengers, if none it should be sent as 0 | Numeric |
infants | Amount of infant passengers, if none it should be sent as 0. | Numeric |
| country_setting | Unique identification of the country setting registry | Numeric |
WebAssembly
To ensure that purchase requests are only from a certified URL and only from a browser. The use of a component responsible for generating an immediate token to send it in the submit of the form is implemented. This is valid for use only once. Therefore, in order to resend a valid token, it is necessary to update the browser.
The token generated by webassembly has a finite validity, configurable from the kibe backend. By default it has 180 seconds. This means that once the search has been performed and the list of available flights has been obtained, the screen can be updated or the date changed with the carousel, for 3 minutes (configurable time).
To insert this functionality, you need:
- Add wasm-load class to the form element used to send the data to kibe:
- It should be:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<form class="searcher wasm-load" ... |
- Get url corresponding to the carrier for example: https://kibe-stage-xx.kiusys.net/static/wasm:
This url is a product of the union between the submit url and the path / static / wasm. So for any carrier, you only need to change the xx for your IATA code - Insert the link style in the html head element:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<link rel="stylesheet" type="text/css" href="https://kibe-stage-xx.kiusys.net/static/wasm/wasm.css"> |
- Add polyfill script tags needed to address compatibility with browsers that don't support ECMA6:
It must be in the html head element
| Code Block | ||||
|---|---|---|---|---|
| ||||
<script crossorigin="anonymous" src="https://polyfill.io/v3/polyfill.min.js?features=blissfuljs%2Cdefault%2Ces2015%2Ces2016%2Ces2017%2Ces2018%2Ces5%2Ces6%2Ces7%2CBlob%2CArray.prototype.forEach"></script> |
- Add the following scripts tags to the end of the body element using the previously obtained url:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<script type="text/javascript"> document.addEventListener("DOMContentLoaded", function(event) { var ua = window.navigator.userAgent; if ( ua.indexOf("MSIE ") > -1 || ua.indexOf("Trident/") > -1) { alert('This website does not support your current version of your web browser') } }); </script> <script type="text/javascript"> const WASM_URL = "https://kibe-stage-xx.kiusys.net/static/wasm"; </script> <script type="text/javascript" src="https://kibe-stage-xx.kiusys.net/static/wasm/wasm_load.js"></script> |
Search Flights
When processing the form in order to redirect to KIBE, the form<form> tag must include:
- action: Target URL must be the KIBE KIBE´s domain.
- method: Must be POST.
Example:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<form class="searcher" id="search-form" name="searchWidgetForm" action="https://kibe-dev-xx.kiusys.net/" method="POST"> |
When Once the user clicks on the submit button, the KIBE will gather all the parameters (Origin, Destination, DepartureDateDeparture date, ReturnDate Return date - If it exists - , Adult quantity, Child quantity, Infant quantity) and will then it will process the request and display the results into the environment of KIBE page in order to complete the booking flow normally.
Anexo 1:
Validations recommended:
So far the KIBE has 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 strong recommend strongly advice developers to developers pay attention to some validation on the frontother front-end side that will make the process more efficient: validations that could help to process´ efficiency:
- Origin - Destination:
The response of the JSON API return the response returns routes enabled for search, this routes are configured on the KIBE´s back office of the KIBE. Based on this information, developer developers can allow only search searches that include an origin with only those destination airports that match and be returned on the responseon response.
The value provided to KIBE must be the one given in the API under the name "data" and not the code. - Dates:
The supported date format supported is DD-MM-YYYY. Developer Developers can display dates on different format that feels formats in order to make the user experience more comfortable for user experience, but , they need to transform change dates on the mentioned format mentioned in order to avoid any validation error returned from by KIBE. - Departure Date:
The departure Departure date must can be from current date in advance and not beyond the day in which the request is being made up to a maximum of 330 days in futureadvanced. - ReturnDate:
The return date should be validating to be never must not be before departure date and not beyond cannot exceed 330 days in the future. - Adult Passenger:
We recommend that the to set as default value for adult passenger should be 1 and not allowed 0. This will avoid any possibility for unaccompanied 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:
For According to industry logic, there should be at least only one infant passenger per adult for infant passenger only. If there are is more than one infant it per adult passenger, there must be more than one adult passenger for association purposes.
- One way / Round trip:
The post of this value must be "one_way" with the value true or false depending if it is one way (true) or round trip (false)