Objective:

Thru this functionality users can create their own widget to embebed in web sites to access KIBE (KIU INTERNET BOOKING ENGINE) functionalities. 

This document will explain how to configure and show some examples for developers

Concepts

What is a Widget?

 -  it is a form on HTML with .CSS that could be embebed into an iframe on the client´s web page or other sites.

Does KIU offer a widget?  

 - Yes, KIU when create the KIBE for clients, supply a standard widget, but maybe this not adjust to the website customer requirements and decide to create one. 

Does the custom widget takes the general configuration of the KIBE?

 - The widget MUST take the configuration and content of the site in order to be accomplish with the operating and commercial intends of the client. All this information reside on the KIBE backoffice that should be completely configurated at time of widget´s creation.  During this document you will see the way to connect your custom widget with the KIBE.  

How to get content to build a widget.

When a user create a form in order to build a widget for KIBE, there are some mandatory fields that should had 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, the 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"
                });
                //Ejemplo sobre como consumir la 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: It has to be declared the KIBE domain (This data is provided by KIU at time of KIBE creation for client) followed by the parameters /api/get_complete_config_widget/. (Ex: 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 the enough data to build/display content on widget fields like:

• Origin - Destination: Populate the airports on the origin field and the destination field. Create a validation for pair of airports enables for search.
• Travel Type: Create a routine to allow user to search one way and round trips travels depending the enabled routes. 
• Travelers: List of supported passenger types and the ages for limit and validate each of them. 
• Departure and return Date: Create field that allow user to add departure date and return date in case the Round trip flights is enabled. 

Search Flights:

At time to process the form and redirect to the KIBE with all the parameters, into the form tag on the action attribute, the target MUST include:

• action: Target URL must be the KIBE domain

• :
• method: 'POST'.

Ex:

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

Declared this, when the user click over the submit button, KIBE will gather the parameters to execute the query: Origin, Destination, DepartureDateDeparture Date, ReturnDate (If it´s exists), Adults quantity, Childs quantity, infants quantity. The result of the seach will be display into the  KIBE´s result page  and users can 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.