Widget Customizable IBE - Guía para Desarrollador

Owned by Gerardo Nizetich (Deactivated)
Last updated: Mar 05, 2021 by Angelo Suarez
10 min read





Introducción y Conceptos

A lo largo de este instructivo, los usuarios podrán crear sus propios widgets para embeber en las páginas web y de este acceder vía parámetros a las funcionalidades de la IBE (KIU INTERNET BOOKING ENGINE).

Este documento es una guía para el desarrollador web que explica como obtener y conectar el Widget desarrollado con el motor de reservas. 

Esta guía no se adentra en como crear el widget, sino, los campos y contenido que debe contar para poder realizar las búsquedas a desplegarse luego en el motor web de KIU. 

  • Que es un widget?

                  Es un formulario en HTML que debe contener estilos .CSS y que permite embeberse dentro de un iframe a la página web del cliente y otros sitios.

  • Ofrece KIU un widget? 

                 Si. KIU provee de un widget estándar cuando el producto IBE es creado, pero, posiblemente este no contempla todos los aspectos que requiere el cliente por lo tanto, este último puede desarrollar su propio widget y conectarse con IBE. 

  • El widget desarrollado debe contemplar la configuración general de IBE? 

                 Si. El Widget debe contemplar y obtener el contenido en base a la configuración de la IBE con el objetivo de realizar las búsquedas de acuerdo a los requerimientos comerciales del cliente. Esta información reside en Backoffice y debe estar completamente configurado al momento de desarrollar e implementar el widget. En esta guía se explica como conectarse y como obtener el contenido a desplegar de acuerdo a la configuración mencionada. 

Para poder hacer un POST al servicio de búsqueda de vuelos, primero es necesario que en IBE se agregue el host desde donde se va a realizar la búsqueda a los sitios permitidos, para esto es necesario que la aerolínea envía a webservices@kiusys.com el host donde va a estar servido el widget y a cual ambiente de la IBE va a apuntar.

Importante:

Para que un carrier pueda utilizar el widget customizable, es necesario agregar en el settings del carrier la siguiente información:

  • CSRF_TRUSTED_ORIGINS
  • ALLOWED_HOSTS

Ambos con el DNS/HOST del carrier.


















back to top

Obtener Contenido para Construir el Widget

Cuando el desarrollador crea el formulario en HTML para generar el widget, hay ciertos campos mandatorios que deben existir para poder enviar la información mínima necesaria a la KIBE y de esta manera obtener resultados.
Con el objetivo de obtener este contenido el desarrollador debe agregar el siguiente Script dentro de la etiqueta <head> en el formulario.

<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 Se debe declarar el dominio de la KIBE (Este dato es proveído por KIU al momento de crear la instancia del producto para el cliente) agregando los parámetros /api/get_complete_config_widget/?callback (Ej: https://kibe-dev-xx.kiusys.net/api/get_complete_config_widget/?callback).

Esta URL va a devolver la siguiente respuesta en formato JSON:

{ "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 } ] }, "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 } }

Diccionario de Respuesta

Nombre

Descripción

Valores / Formato

Passengers

Contiene un objeto con las configuraciones para los distintos tipos de  pasajeros y la cantidad máxima permitidos

Objeto

max_pax_allowed

Viene dentro del objeto “Passengers” y es la máxima cantidad de pasajeros permitidas.

Número

pax_config

Es un objeto con las configuraciones necesarias por CATEGORÍAS permitidas en la KIBE.

Estan son ADULT, CHILD y INFANT.

Objeto

max_age

Es la edad máxima permitida de una categoría. El campo viene dentro cada objeto dentro de pax_config

Número / null

enable

Habilita o deshabilita la categoría. El campo viene dentro cada objeto dentro de pax_config.

true / false

name

Es el nombre de la categoría. El campo viene dentro cada objeto dentro de pax_config

ADULT / CHILD / INFANT

min_age

Es la edad mínima por categoría. El campo viene dentro cada objeto dentro de pax_config

Número

csrf_token

Es el HASH de validación de DJANGO para la validación del SUBMIT del formulario

HASH

airports

Objeto que contiene la información de los aeropuertos necesarias para la validación del formulario

Objeto

keys

Objeto con los aeropuertos de origen y destinos seteados desde el backoffice de la KIBE. El campo viene dentro cada objeto dentro de airports

Objeto

origin

Array de Objetos que contienen la información de los aeropuertos. El campo viene dentro cada objeto dentro de keys

Array

code

Código de IATA del aeropuerto. El campo viene dentro cada objeto dentro de origin

3 letras

data

Es el código que utiliza KIBE para la cotización.

4 letras

value

Texto como se muestra el aeropuerto en el formulario de la KIBE

Alfabético

destination

Idem origin. Mismo formato

Objeto

origin_destination

Objeto de los destinos habilitados en la KIBE con sus respectivas configuraciones

Objeto

keys

Array de objetos, que contiene los destinos habilitados. El campo viene dentro cada objeto dentro de origin_destination

Array

origin

Código IATA del aeropuerto de origen.  El campo viene dentro cada objeto dentro de keys

3 Letras

destination

Código IATA del aeropuerto de destino. El campo viene dentro cada objeto dentro de keys

3 Letras

not_flying_days_return

Array con los dias de la semana que no tiene permitido volar de vuelta. El campo viene dentro cada objeto dentro de keys

0 a 6 (Siendo 0 Lunes)

not_flying_days_going

Array con los días de la semana que no tiene permitido volar de ida. El campo viene dentro cada objeto dentro de keys

0 a 6 (Siendo 0 Lunes)

frequency_return

Array con los días de la semana que tiene permitido volar de vuelta. El campo viene dentro cada objeto dentro de keys

0 a 6 (Siendo 0 Lunes)

frequency_going

Array con los días de la semana que tiene permitido volar de ida. El campo viene dentro cada objeto dentro de keys

0 a 6 (Siendo 0 Lunes)

direct_flight

Si es vuelo directo o permite conexiones.  El campo viene dentro cada objeto dentro de keys

true / false

date_from

Primera fecha de vuelo disponible.  El campo viene dentro cada objeto dentro de keys

DD/MM/YYYY

date_to

Ultima fecha disponible.  El campo viene dentro cada objeto dentro de keys

DD/MM/YYYY

country_settings

Contiene un objeto con las configuraciones para los distintos tipos de monedas y sus países de emisión

Objeto

label_es

Es el nombre del combo en español que trae las configuraciones de moneda/país.

50 caracteres alfanuméricos

label_en

Es el nombre del combo en inglés que trae las configuraciones de moneda/país.

50 caracteres alfanuméricos

currency_config

Es un objeto con las configuraciones necesarias por DESCRIPCIÓN de registros de la tabla country_settings permitidas en RES para los parámetros: TERMINAL, USUARIO, ISO_PAIS, ISO_MONEDA

Objeto

country_setting

Es el código del registro de country settings (moneda / país) seleccionado. El campo viene dentro de cada objeto de currency_config

Numérico

ISO_currency

Es el código de la moneda de cotización que utiliza RES. El campo viene dentro de cada objeto de currency_config

3 Letras

ISO_country

Es el código del país de cotización que utiliza RES. El campo viene dentro de cada objeto de currency_config

2 Letras

description_es

Es la descripción del registro en español. El campo viene dentro de cada objeto de currency_config

25 caracteres alfanuméricos

description_en

Es la descripción del registro en inglés. El campo viene dentro de cada objeto de currency_config

25 caracteres alfanuméricos

device_id

Es la terminal de cotización que utiliza RES. El campo viene dentro de cada objeto de currency_config

10 caracteres alfanuméricos

agent_sine

Es el usuario de cotización que utiliza RES. El campo viene dentro de cada objeto de currency_config

9 Letras

default

Es el campo que determina la moneda de cotización predeterminada para el carrier. El campo viene dentro de cada objeto de currency_config

true / false

enabled

Es el campo que determina si la configuración moneda / país debe ser visible o no en la lista de valores.El campo viene dentro de cada objeto de currency_config

true / false

type_of_journey

Contiene un objeto con la configuración del tipo de viaje default sugerido

Objeto

one_way

Habilita o inhabilita la selección default del tipo de viaje "One way / Ida" en el formulario front end

true / false

round_trip

Habilita o inhabilita la selección default del tipo de viaje "Round trip / Ida y vuelta" en el formulario front end

true / false

Basado en esta respuesta, el desarrollador cuenta con la suficiente información para desplegar dentro de los distintos campos del widget:

  • Aeropuertos de salida y arribo

  • Rutas habilitadas

  • Tipos de pasajeros soportados

  • Cantidad máxima permitida de pasajeros para búsquedas

  • Tipo de viajes soportados (Ida o Ida y vuelta)

  • Monedas soportadas, por país

También en base a esta información puede generar filtros y validaciones del lado del cliente. 

Formulario

Submit [ POST ]

El formulario se va a comunicar con la KIBE mediante un simple SUBMIT del mismo al HOST establecido de antemano para la aerolínea.

Autorización del Formulario

Al hacer POST / SUBMIT en el formulario de la KIBE, para que ésta pueda cotizar el vuelo elegido, deberá recibir si o si el campo csrfmiddlewaretoken con el HASH proveniente de la API en el campo csrf_token. En caso contrario, de no recibir dicho HASH, la KIBE  responderá a la petición dando un 403 Forbidden.

Campos Esperados

El aplicativo de la KIBE, está esperando los siguientes campos para poder realizar la cotización necesaria para el vuelo: 

Importante:

Se deben respetar los nombres al hacer el POST del formulario a la KIBE para que ésta realice correctamente la cotización y futura reserva. 

Nombre

Descripción

Valores / Formato

csrfmiddlewaretoken

HASH de autorización del formulario.

HASH

one_way

Si es oneway se envía este parámetro con valor true, en caso de ser roundtrip este no se envía.

True

origin

Código IATA del aeropuerto de origen

4 Letras

destination

Código IATA del aeropuerto de destino

4 Letras

departure_date

Fecha de vuelo de partida.

DD/MM/AAAA

return_date

Fecha de vuelo de regreso. En caso de ser viaje oneway, este campo debe ser enviado vacío.

DD/MM/AAAA

adults

Cantidad de pasajeros adultos.  Siempre se debe enviar por lo menos un pasajero adulto para la cotización.

Número

minors

Cantidad de pasajeros del tipo CHILD. En caso de no tener ninguno, para la cotización se debe enviar 0.

Número

infants

Cantidad de pasajeros del tipo INFANTS.  En caso de no tener ninguno, para la cotización se debe enviar 0.

Número

country_setting

Identificación única del registro country settings seleccionado

Número

Uso de WebAssembly

Para garantizar que los request de búsqueda sean solo desde una url certificada y únicamente desde un navegador, se implementa el uso de un componente encargado de generar un token inmediato, con el fin de enviarlo en el post del formulario. Éste token es válido para ser utilizado una sola vez, de este modo, para poder volver a hacer un submit con un token válido, es necesario refrescar el navegador.

El token generado mediante webassembly tiene una vigencia limitada, configurable desde el backend de kibe, por defecto tiene 180 segundos. Esto quiere decir que una vez hecha la búsqueda y obtenido el listado de vuelos disponibles, se puede refrescar la pantalla o cambiar de fecha mediante el carrusel, durante 3 minutos (tiempo configurado).

Para insertar esta funcionalidad, se necesita:

1: Agregar clase wasm-load al elemento form usado para enviar los datos a kibe.
   - Debe quedar:

<form class="searcher wasm-load" ...

2: Obtener url correspondiente al carrier por ejemplo: https://kibe-stage-xx.kiusys.net/static/wasm
 - Esta url es producto de la unión de la url usada para el submit y el path /static/wasm. Por lo que para cualquier carrier, solo necesita cambiar el xx por su código de 2 caracteres de la aerolínea .

3: Insertar el link style en el elemento head del html:

<link rel="stylesheet" type="text/css" href="https://kibe-stage-xx.kiusys.net/static/wasm/wasm.css">

4: Agregar  tags script de polyfill necesario para tratar compatibilidad con navegadores que no soporten ECMA6:

  - Debe ser en el elemento head del html

<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>

5: Agregar los siguientes tags scripts al final del elemento body usando la url obtenida en el paso 2:

<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>

































































































back to top

























Búsqueda de Vuelos

Una vez que el formulario ya se encuentra desarrollado y cuenta con el contenido anteriormente descrito, el desarrollador debe enviar estos parámetros a la KIBE, para lo cual, debe agregar dentro de la etiqueta <form> :

  • action: La URL de destino debe ser el dominio del a KIBE.
  • method: El método debe ser POST.

Ejemplo:

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

Incluidos estos atributos cuando el usuario envía el formulario, KIBE va a tomar los parámetros:

  • Origin
  • Destination
  • Fecha de Salida
  • Fecha de regreso (Si existe).
  • Cantidad de pasajeros adultos. 
  • Cantidad de pasajeros Menores e infantes (Si existen).

Realiza una serie de validaciones de datos y procesa el pedido. En este momento, los resultados obtenidos se van a desplegar dentro de la página de KIBE en el ambiente de KIBE. 













back to top

Validaciones Recomendadas

Mas allá que la aplicación KIBE tiene sus propias validaciones en el backend, debemos realizar ciertas recomendaciones a los desarrolladores sobre algunas validaciones a realizar del lado del cliente (Front-end) con el objetivo de evitar errores de búsqueda inconsistentes y generar un proceso mas eficiente. 

  1. Origen - Destino:


    La respuesta de JSON API devuelve la lista de rutas habilitadas para búsquedas configuradas en el backoffice de KIBE. Basado en esta información, el desarrollador puede filtrar y validar las opciones que estén relacionadas y así optimizar los resultados de las búsquedas. 

  2. Fechas:


    El formato soportado de fechas es DD/MM/YYYY (ejemplo: 19/01/2019). El desarrollador puede desplegar en el formulario en diferentes formatos de acuerdo a la zona en la que se encuentre, pero debe considerar hacer la transformación para respetar el formato soportado y evitar de esta manera que la KIBE devuelva error de formato. 

  3. Fecha de salida:


    La fecha de salida debe considerarse desde la fecha actual a futuro y no mas allá de 330 días en futuro. La aplicación por estándar de la industria soporta búsquedas de disponibilidad hasta 330 días a futuro de la fecha actual.

  4. Fecha de regreso:


    La fecha de regreso debe validarse contra la fecha de salida. Esta no puede ser anterior a la fecha fijada como salida y no debe ser superior a 330 días a futuro. 

  5. Pasajero adulto:


    Recomendamos que el valor default sea 1. No se acepte 0, para evitar la solicitud vía canal de ventas web de menores no acompañados que lleva consigo una proceso interno de la línea aérea para su autorización.

  6. Pasajeros infantes:

            Por una lógica propia de la industria, debe existir previamente un adulto antes de agregar un infante.

            Si existe mas de un pasajero Infante, debe existir la misma cantidad de adultos puesto que solamente se puede asociar un pasajero infante y solo uno a un pasajero adulto. 















back to top