Objective:

Through this functionality, users can create their own Widget to embed in web sites in order to access KIBE (KIU INTERNET BOOKING ENGINE) functionalities. 

This document explains how to configure the widget to get a guideline to develop.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 could be embedded into an iframe on the client´s web page or other sites.

Does KIU offer a Widget?

Yes. KIU provides a standard Widget when creating the KIBE, but it is not adjustable to the customer´s web site.

Is the custom Widget based on the KIBE general configuration?

The Widget is indeed based on the configuration and content of the site in order to accomplish the operating and commercial requirements of the client. All this information resides on the KIBE Backoffice and should be completely configurated once the Widget is created. Within this document, you will see many examples of how to connect your custom Widget with the KIBE.

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 next 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 on 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/ (Eg: https://kibe-dev-xx.kiusys.net/api/get_complete_config_widget/).

This URL will return the next JSON API:

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

Developers based on this response 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.Type of travel supported (One Way and Round Trip flights).

Search Flights:

When processing the form in order to redirect to KIBE, the form tag MUST include:

• action: Target URL must be the KIBE domain.
• method: Must be POST.

Example:

 <form class="searcher" id="search-form" name="searchWidgetForm" action="https://kibe-dev-xx.kiusys.net/" method="POST">

When user clicks on the submit button, KIBE will gather all the parameters (Origin, Destination, DepartureDate, ReturnDate - If it exists - , Adult quantity, Child quantity, Infant quantity) and 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 back-end validations, we strong recommend to developers pay attention to some validation on the front-end side that will make the process more efficient:

1. Origin - Destination: 
   The response of the JSON API return the routes enabled for search, configured on the back office of the KIBE. Based on this information, developer can allow only search that include an origin with only those destination airports that match and be returned on the response. 
   
   
2. Dates:
   The date format supported is DD-MM-YYYY. Developer can display on different format that feels more comfortable for user experience, but, they need to transform on the format mentioned in order to avoid any validation error returned from KIBE.
   
   
3. Departure Date: 
   The departure date must be from current date in advance and not beyond 330 days in future.
   
   
4. ReturnDate: 
   The return date should be validating to be never before departure date and not beyond 330 days in future. 
   
   
5. Adult Passenger:
   We recommend that the default value for adult passenger should be 1 and not allowed 0. This will avoid any possibility for unaccompanied minors (this should be resolved on Airline offices).
   
   
6. Infant passengers:
   For industry logic, there should be at least one adult for infant passenger only. If there are more than one infant it must be more than one adult for association purposes.