Introduction and Concepts

Through this guide, developers will be able to create their own widgets to embed in the web sites and from it, access via parameters to the E-COMMERCE booking functionalities.

This document explains how to obtain and connect the developed Widget with the booking engine, detailing the services and fields that must be considered in order to build the tool and achieve the searches to be displayed later in the next SPA, according to the selected flow.

The booking screen, is configurable, since different flows converge there, as listed below:

Search flight: Used only for flight searching and bookings generation

Manage my booking: Used to retrieve a booking previously generated and make changes to it

Web check-in: Dedicated to managing the check-in on a segment that is about to begin

What is a widget?

A Widget is a simple application that can be included on the airline's website aiming to extend the functionality to our e-commerce. We provide a widget that can be embedded using an HTML iframe tag into any website. Nevertheless, if this widget does not has all that is needed, a custom widget can be created using our API REST services. These services will provide all the necessary data to guarantee compatibility through the booking flow.

Embedded Widget via Iframe

Url for the iframe

In case you need to use KIU widget you can add it to yor code using an iframe <iframe src="https://ecommerce-xx-stage.kiusys.net/booking/widget/"</iframe>

Custom Widget

Assuming that the developer builds a HTML form, there are some mandatory fields to be sent in order to access the e-commerce filghtresults SPA or any other flow.

General considerations

E-COMMERCE is a client-server application, where the client is built under the Single Page Application (SPA) model. Each step of the flow is independent of the rest, and also, independent from the backend server where the business logic resides.

The widget must obtain the content and configurations stored in the e-commerce backoffice. This guide explains how to connect and get this content.

General Url to implement a custom widget

To consume the necessary services a valid url must be used, for example, this this url it is used for xx carrier int the testing enviroment

https://ecommerce-xx-stage.kiusys.net/

Services

Get Applications

E-COMMERCE is divided into applications searchflight, manage my booking y webcheckin. The flow of these apps is set in the backoffice. To get a list of the available applications this service can be used

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/applications/xx

ccccccccc:

Click here to expand...

let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net'
}
var url = 'https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/applications/xx'
fetch(url, {
 	    method: 'GET',
 	    headers: headers
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => handleAppsResponse(response)
)

Response:

response with the list of applications

{
   "kiu_internals":{
      "duration":3.25775146484375,
      "id_tracking":"backendsearchflight.5b8e970fa8d1_04245c28f792435f92d1f513d4824d41"
   },
   "response":[
      "ecommerce",
      "manage",
      "webcheckin"
   ]
}

Get Flow

GetFlow is the second service to use, where you should obtain a session key and the flow configuration of the selected app. This sessionkey it's going to be used in the next request. Additionally having the flow will give us the next screen to be rendered.

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/flow/?carrier=xx&app=ecommerce

Implementation:

Click here to expand...

let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net'
}
var url = 'https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/flow/?carrier=xx&app=ecommerce'
fetch(url, {
 	    method: 'GET',
 	    headers: headers
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => customHandleResponseFunction(response)
)

Response:

Click here to expand...

{
   "kiu_internals":{
      "duration":0.19812583923339844,
      "id_tracking":"backendsearchflight.29bad7c320a2_6a0a84986ffd41cc8fb90dee945baf21"
   },
   "response":{
      "flow":[
         {
            "id":1,
            "spaflow_id":1,
            "url":"/searchflight/",
            "zorder":0
         },
         {
            "id":2,
            "spaflow_id":1,
            "url":"/flightresults/",
            "zorder":1
         },
         {
            "id":5,
            "spaflow_id":1,
            "url":"/travellerdetails/",
            "zorder":2
         },
         {
            "id":8,
            "spaflow_id":1,
            "url":"/extraservices/",
            "zorder":3
         },
         {
            "id":6,
            "spaflow_id":1,
            "url":"/purchase/",
            "zorder":4
         },
         {
            "id":7,
            "spaflow_id":1,
            "url":"/endflow/",
            "zorder":5
         }
      ],
      "session_key":"fake-test-key.rPnZwFJPXkQ"
   }
}

Response dictionary:

Click here to expand...

field		description	Value/format
flow		List of screens inside the flow	Array → Object
	spaflow_id	id of the record inside the flow manager	Int
	url	Path of the screen inside the flow	String, Ej. '/flightresults/'
	zorder	Order of the screen	Int

Get configs

This is the main service where we will have all the selected app configuration (only for searchflight and webcheckin)

Click here to expand...

const appsSchema = {
			ecommerce: {
			app: 'ecommerce',
			module: 'searchflight',
			needConfigs: true
		},
		manage: {
			app: 'manage',
			module: 'managebooking',
			needConfigs: false
		},
		webcheckin: {
			app: 'manage',
			module: 'retrievebooking',
			needConfigs: true
		}
	};

This json is a suggestion for the developer. It shows what is needed in each app.

Url (app searchflight):

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/configs/

Implementation:

Click here to expand...

let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net',
    'authorization': 'Token session_key obtenido en get_sessions'
}
fetch('https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/configs/', {
 	    method: 'GET',
 	    headers: headers
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => customHandleResponseFunction(response)
)

Response:

Click here to expand...

{
   "kiu_internals":{
      "duration":2645.9577083587646,
      "id_tracking":"backendsearchflight.29bad7c320a2_3f5d1423f4504527b433ede5a4cbd14c"
   },
   "response":{
      "cabin":{
         "business":true,
         "business_default":false,
         "economy":true,
         "economy_default":false,
         "economy_premium":false,
         "economy_premium_default":false,
         "first":true,
         "first_default":true,
         "id":2,
         "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "carrier":{
         "code":"XX",
         "enable":true,
         "name":"EQUIS",
         "numcode":"001",
         "uuid":"982726d9-965b-4ea4-a22b-aa765dbe8dc7"
      },
      "country_settings":[
         {
            "currency_code":"USD",
            "default":true,
            "device_id":"AEP00XXW04",
            "enable":true,
            "id":45,
            "iso_country_code":"AR",
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6",
            "user_id":"AEP00XXSM"
         }
      ],
      "display_logics":[
         {
            "airport_code":true,
            "airport_name":true,
            "city_code":true,
            "city_name":true,
            "country_code":true,
            "country_name":true,
            "device_type":"m",
            "id":4,
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         },
         {
            "airport_code":true,
            "airport_name":true,
            "city_code":true,
            "city_name":true,
            "country_code":true,
            "country_name":true,
            "device_type":"d",
            "id":5,
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         },
         {
            "airport_code":true,
            "airport_name":true,
            "city_code":true,
            "city_name":true,
            "country_code":true,
            "country_name":true,
            "device_type":"t",
            "id":6,
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         }
      ],
      "eligibilities":[
         {
            "code":"KIU",
            "enable":true,
            "id":3,
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         }
      ],
      "journey_type":{
         "id":2,
         "multicity":false,
         "multicity_default":false,
         "one_way":true,
         "one_way_default":true,
         "round_trip":true,
         "round_trip_default":false,
         "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "languages":[
         {
            "lang":"en"
         },
         {
            "lang":"es"
         }
      ],
      "passenger_types":[
         {
            "code":"ADT",
            "enable":true,
            "id":9,
            "max_quantity":6,
            "ptc":"ADT",
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         },
         {
            "code":"INF",
            "enable":true,
            "id":10,
            "max_quantity":6,
            "ptc":"INF",
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         },
         {
            "code":"CHD",
            "enable":true,
            "id":11,
            "max_quantity":3,
            "ptc":"CHD",
            "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
         }
      ],
      "privacy_policy":{
         "confirmation_button":false,
         "enable":true,
         "id":2,
         "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "promo":{
         "codes":[
            {
               "code":"PROMO1",
               "id":4,
               "promo":2
            }
         ],
         "enable":true,
         "id":2,
         "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "routes":[
         {
            "carrier":"982726d9-965b-4ea4-a22b-aa765dbe8dc7",
            "destination":{
               "city":{
                  "code":"BUE",
                  "country":{
                     "code":"AR",
                     "description":"ARGENTINA",
                     "id":17
                  },
                  "description":"BUENOS AIRES",
                  "id":35
               },
               "code":"AEP",
               "description":"AEROPARQUE JORGE NEWBERY",
               "id":79
            },
            "id":47,
            "origin":{
               "city":{
                  "code":"COR",
                  "country":{
                     "code":"AR",
                     "description":"ARGENTINA",
                     "id":17
                  },
                  "description":"CORDOBA",
                  "id":26
               },
               "code":"COR",
               "description":"PAJAS BLANCAS",
               "id":27
            }
         }
      ],
      "setting":{
         "carrier":"982726d9-965b-4ea4-a22b-aa765dbe8dc7",
         "enable":true,
         "name":"init",
         "uuid":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "temporary_message":{
         "color":"primary",
         "details":[
            {
               "datetime":"2020-03-17T16:20:41.331326Z",
               "enable":true,
               "id":26,
               "link":"http:XX.com",
               "name":"b'U1\\x03\\x9d'",
               "show_datetime":false,
               "temporary_message":2
            }
         ],
         "id":2,
         "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6"
      },
      "translations":{
         "en":{
            "aaaa":"aaaa",
            "child":"Child",
            "descriptions":"xczvzxv",
            "descriptionseeeee":"dddddd",
            "language_description":"English",
            "lugateste":"lugatest",
            "luggage":"Luggage",
            "meal":"Meal",
            "pax":"Passenger",
            "test123":"test"
         },
         "es":{
            "aaaa":"12345",
            "child":"Ni\u00f1o",
            "descriptions":"zsvzvxdv",
            "descriptionseeeee":"dddd",
            "infant":"infante",
            "meal":"Comida",
            "pax":"Pasajero",
            "testing":"fff"
         },
         "kiu_internals":{
            "id_tracking":"kiu-translate.kiu-translate-qa_fe9212c0a9604a619fa34deab8341f61"
         }
      }
   }
}

Response Dictionary:

Click here to expand...

field	next level field	description	values/format
routes		List of origin destination combinations	Array → Object
	origin	Origin information, country, city, code, description	Object
	destination	Destination information, country, city, code, description	Object
country_settings		Country and currency configurations. This informations it is used to build the point of sale	Array → Object
	currency_code	currency code	String, Ej. ‘USD’
	default	indicates whether is the defualt config	Boolean
	device_id	PSS terminal_id/device_id	String. Ej. ‘AEP00XXW04’
	user_id	PSS user_id/agente_id	String. Ej. ‘AEP00XXSM’
	enable	indicates whether is enable	Boolean
	iso_country_code	Country code	String. Ej. ‘AR’
display_logics		Backoffice configuration, indicates how to display origin and destination in the form in each device	Array → Object
	airport_code		Boolean
	airport_name		Boolean
	city_code		Boolean
	city_name		Boolean
	country_code		Boolean
	country_name		Boolean
	device_type	m: mobile, d: desktop, t: tablet	String: Ej. ('m', ‘t', 'd’)
journey_type		Indicate the availble and default type of journey	Object
	one_way		Boolean
	one_way_default		Boolean
	round_trip		Boolean
	round_trip_default		Boolean
	multicity		Boolean
	multicity_default		Boolean
passenger_types		Type of passenger configuration	Array → Object
	code	ADT: Adult, INF: Infant, CHD: Child	String. Ej. 'ADT'
	enable		Bolean
	max_quantity		Int
	ptc		String. Ej. 'MIL'
eligibilities		List of eligibilities to display on the form	Array → Object
	code		String
	enable		Boolean
cabin		Cabin configurations	Objet
	“Business“		Boolean
	“Business_default“		Boolean
temporary_message		temporary messages configured at the back office	Object
	color		String
	details		Array -> Object
translations		translations foreach label	Object → Object
promo		promo codes configurations	Object
	enable		Boolean
	codes		Array → Object
privacy_policy		privacy policie configured at the backoffice	Object
	confirmation_button	indicates whether confiramtion button must be shown	Boolean
	enable	indicates whether is enable	Boolean
languages		list of available languages	Array → Object

Based on thius response the developer has enough information to display some fields on the widget, enable routes, different types of pax, and max quantity, types of journey, currencies, cabins, temporary messages, etc...

Url (app webcheckin):

https://ecommerce-xx-stage.kiusys.net/retrievebooking/api/v1/configs/

Implementation:

Click here to expand...

let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net',
    'authorization': 'Token session_key obtenido en get_sessions'
}
fetch('https://ecommerce-xx-stage.kiusys.net/retrievebooking/api/v1/configs/', {
 	    method: 'GET',
 	    headers: headers
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => customHandleResponseFunction(response)
)

Response:

Click here to expand...

{
   "kiu_internals":{
      "duration":15.575170516967773,
      "id_tracking":"backend_retrieve_booking.1a3b98991b77_20b1ae1b2abf4dc5b1c0b04a1c4ddefe"
   },
   "response":[
      {
         "currency_code":"ARS",
         "default":true,
         "device_id":"AEP00XXW04",
         "enable":true,
         "id":3,
         "iso_country_code":"AR",
         "setting":"c256b8d5-dd08-45ba-a546-7057bef51199",
         "user_id":"AEP00XXSM"
      }
   ]
}

Diccionario de respuesta:

Click here to expand...

Field	Description	Valores/formato
	Country and currency configurations. This informations it is used to build the point of sale	Array
currency_code	currency code	String, Ej. ‘USD’
default	indicates whether is the defualt config	Boolean
device_id	PSS terminal_id/device_id	String. Ej. ‘AEP00XXW04’
user_id	PSS user_id/agente_id	String. Ej. ‘AEP00XXSM’
enable	indicates whether is enable	Boolean
iso_country_code	Country code	String. Ej. ‘AR’

Get Dates (Usado para searchflight)

Returns a list of dates with the availability of flights from today up to 330 days. Origin and destination must be specified

Parameters:

origin: airport code, for example 'MAD'

destination: airport code, for example 'CUN'

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/dates/?origin=${origin}&destination=${destination}

Implementation:

Click here to expand...

Este endpoint se ejecuta por get, enviado query params

let origin = 'AEP';
let destination = 'COR';
let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net',
    'authorization': 'Token session_key obtenido en get_sessions'
}
fetch(`https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/dates/?origin=${origin}&destination=${destination}`, {
 	    method: 'GET',
 	    headers: headers
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => customHandleResponseFunction(response)
)

Response:

Click here to expand...

{
   "kiu_internals":{
      "duration":39.411306381225586,
      "id_tracking":"backendsearchflight.29bad7c320a2_650ed89aeee64f209f6f9b4357a57a6a"
   },
   "response":{
      "ow":[
         "2020-04-03",
         "2020-04-04",
         "2020-04-05",
         "2020-04-06",
         "2020-04-07",
         "2020-04-08",
         "2020-04-09",
         "2020-04-10",
         "2020-04-11",
         "2020-04-12",
         "2020-04-13",
         "2020-04-14",
         "2020-04-15",
         "2020-04-16",
      ],
      "rt":[
         "2020-04-03",
         "2020-04-04",
         "2020-04-05",
         "2020-04-06",
         "2020-04-07",
         "2020-04-08",
         "2020-04-09",
         "2020-04-10",
         "2020-04-11",
         "2020-04-12",
         "2020-04-13",
         "2020-04-14",
      ]
   }
}

This response can be used to disable days in the datepicker input.

Post action (searchflight)

This service is used to send all the required data for a flight search. The request must be done using POST AJAX and after the response, a redirect must take place to the next step of the flow.

Parameters:

country_setting: Config selected by the passenger
session_key: previously obtained session_key (get_sessions)
journey_type: type of journey (ow/rt)
origin
destination
departure_date
return_date
adults
minors
infants
cabin
promo

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/action/

Implementation:

Click here to expand...

var formData = {
	country_setting: {
        "currency_code":"USD",
        "default":true,
        "device_id":"AEP00XXW04",
        "enable":true,
        "id":45,
        "iso_country_code":"AR",
        "setting":"0be29d7e-c626-4d07-b60f-6917cc890bc6",
        "user_id":"AEP00XXSM"
    },
	session_key: 'session_key previously obtained in get_sessions',
	journey_type: 'one_way',
	origin: 'AEP',
	destination: 'COR',
	departure_date: '2021-02-03',
	return_date: null, // if journey_type = 'round_trip' return_date must be completed
	adults: 1,
	minors: 0,
	infants: 0,
	cabin: 'economy', // not required
	promo: 'PROMO1' // not required
}
let headers = {
    'Content-Type': 'application/json',
    'accept': 'application/json', 
    'carrier': 'xx',
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/',
    'authority': 'ecommerce-xx-stage.kiusys.net',
    'authorization': 'Token session_key obtenido en get_sessions'
}
fetch('https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/action/', {
 	    method: 'POST',
 	    headers: headers,
        body: JSON.stringify(formData)
    }
).then(res => res.json())
.catch(error => console.error('Error:', error))
.then(
	response => customHandleResponseFunction(response)
)

E-commerce Custom Widget - Developers guide

Introduction and Concepts

What is a widget?

Embedded Widget via Iframe

Url for the iframe

Custom Widget

General considerations

General Url to implement a custom widget

Services

Url:

Get Flow

Url:

Implementation:

Response:

Response dictionary:

Get configs

Url (app searchflight):

Implementation:

Response:

Response Dictionary:

Url (app webcheckin):

Get Dates (Usado para searchflight)

Parameters:

Url:

Implementation:

Response:

Post action (searchflight)

Parameters:

Url:

Implementation: