Manual de usuario Web Services 3.0


Web Services 3.0

Manual de Referencia - Inicial






Cambios desde la versión anterior de los Web Services


Los Web Services 3.0 son una reescritura de las interfaces de aplicación mantenidas desde la primera versión. Se adopta como modelo el standard OTA y se deja de lado el sistema de llamada remota SOAP en favor del uso de XML puro mediante métodos HTTP POST sobre SSL. La nueva suite de mensajes provee mayor flexibilidad y funcionalidades no cubiertas y es a partir de la misma sobre la que se van a realizar los futuros desarrollos, por lo que recomendamos iniciar el proceso de migración de todo aquello implementado sobre las versiones 2.X, así como la implementación en 3.0 de los nuevos desarrollos. Los Web Services son la interfaz que permite acceder en forma programática al inventario del sistema de reservas, desde la disponibilidad hasta la la emisión. El propósito de este manual de referencia es describir en forma detallada cada uno de los mensajes soportados así como sus respuestas. Las definiciones de los mensajes están basadas en estandar OTA, descripto por la Open Travel Alliance (http://www.opentravel.org). Recomendamos leer la información provista por ellos, siendo el modelo en el cual se basa nuestra implementación. Asimismo, el roadmap de implementación de nuevas características toma en cuenta las disponibles en la definición OTA que no estén aun desarrolladas. Se presupone que el equipo encargado de la implementación posee un conocimiento adecuado de las tecnologías que forman la base de la misma y por ende no serán cubiertas dentro de este manual. Es responsabilidad del implementador ocuparse de cómo hará los requerimientos usando POST vía HTTPS, formar mensajes XML válidos e interpretar adecuadamente los mensajes XML que recibe en respuesta.


La comunicación se iniciará siempre del lado de la linea aérea o agencia de viaje y consiste de una petición POST vía HTTPS, conteniendo tres campos:

User
: Usuario asignado para acceso a los Web Services.
Password
: Clave de acceso asignada para los Web Services.
Request
: Texto XML con el mensaje cuyo procesamiento se solicita.

A lo largo de la guía se da por presupuesto que cada mensaje es enviado en esta forma, por lo que solo se hablará del contenido de los mensajes XML, sin hacer ninguna otra mención al modo en que se realiza la llamada a través del medio HTTPS.

Las validaciones sobre los datos enviados se implementan en la forma más restrictiva posible, por lo que es importante tenerlas en cuenta a fin de evitar rechazos por cuestiones de formatos. Los formatos reconocidos son:


Entero: Es un entero positivo o negativo sin espacios ni ningún otro símbolo especial que el de signo menos (-) al inicio de ser negativo. Ejemplo: 123, 0, -44.
Decimal: Sigue el formato del entero pero admite un punto decimal (.) y una segunda sucesión de dígitos. Ejemplo: -44, 0.00038, -456.55.
Alfabético: Es una cadena de caracteres de la A a la Z, mayúsculas sin eñes, tildes, espacios ni ningún símbolo de puntuación. Ejemplo: LIM, BASED.
Alfanumérico: Es una cadena de caracteres de la A a la Z y del 0 al 9. Ejemplo: 29FEB, JFK0XX01.
Alfanumérico con Caracteres Especiales: Es una cadena que acepta los caracteres de la definición de Alfanumérico y anexa los caracteres especiales definidos en el standard DISH 20.1, a saber: espacio en blanco, punto decimal, guión medio y barra de fecha. Ejemplo: PEREZ/JUAN. ESPACIO EN BLANCO.
Fecha: Definición Calendar Date según ISO 8601 (YYYY-MM-DD). Ejemplo: 2013-03-27.
Fecha y Hora: Definición Date and Time según ISO 8601 (YYYY-MM-DDThh:mm:ss). Ejemplo: 2013-03-27T22:45:36.
Lista: En los casos de listas definidas, se enumerarán entre corchetes separadas por el carácter pipe. Ejemplo: [Production|Testing].

En los casos de campos opcionales, estos aceptan además de su formato reconocido el recibir una cadena vacía.

Para cada funcionalidad existe un par de mensajes, uno que identifica la petición y uno que le corresponde en respuesta. El identificador del mensaje corresponde al elemento raíz del XML. Este par se halla normalmente asociado por nombre (por ejemplo, a la petición KIU_AirAvailRQ corresponderá en respuesta el mensaje KIU_AirAvailRS), pero en algunos casos puntuales a un determinado nombre de petición le corresponde un nombre distinto de respuesta (por ejemplo, el mensaje KIU_ReadRQ es respondido con el mensaje KIU_ProfileReadRS).

Volver al índice


Elementos comunes en las peticiones


Todo mensaje de petición incluye en su cabecera un set de atributos que facilita su identificación y procesamiento. Estos elementos son:

EchoToken: Alfanumérico [0...128] (Opcional). Sirve como identificación y se envía junto con la respuesta sin modificación alguna. Se recomienda implementar un sistema que envíe las llamadas con un identificador único en este campo para facilitar la posterior búsqueda de llamadas en logs.
TimeStamp: Fecha y Hora ISO. Momento de generación del mensaje.
Target: [Production|Testing]. Partición sobre la cual va a trabajarse.
Versión: Decimal (Opcional). Versión implementada.
SequenceNmbr: Entero positivo. Sirve para identificar un número de secuencia en un set de mensajes relacionados. Se envía junto con la respuesta sin modificación alguna. Se recomienda implementar un sistema que asigne números correlativos del 1 en adelante a cada llamada que un mismo cliente genera en una visita a la web, para facilitar la posterior identificación de la secuencia de llamadas en logs.

Ejemplo de inicio de petición:

<KIU_AirAvailRQ EchoToken="12345" TimeStamp="2010-07-17T09:30:47-02:00" Target="Production" Version="3.0" SequenceNmbr="1">

Volver al índice


Elementos comunes en las respuestas


Además de los elementos comunes en las peticiones, las respuestas incluyen elementos para informar el éxito o fracaso de las operaciones realizadas. En caso de éxito, se incluye el elemento "Success" junto con los datos de la respuesta. De esta forma, el encabezado de la respuesta para una petición sería:

<KIU_AirAvailRQ EchoToken="12345" TimeStamp="2010-07-17T09:30:47-02:00" Target="Production" Version="3.0" SequenceNmbr="1">
<Success/>


Mientras que en caso de fracaso, se incluye un elemento "Error" el cual incluye un "ErrorCode" con el código numérico y un "ErrorMsg" con una descripción:

<KIU_AirAvailRQ EchoToken="12345" TimeStamp="2010-07-17T09:30:47-02:00" Target="Production" Version="3.0" SequenceNmbr="1">
<Error>
      <ErrorCode>55023</ErrorCode>
      <ErrorMsg>Test error message</ErrorMsg>
</Error>

Volver al índice


Errores comunes en las respuestas

                                                                                     

Código

Mensaje

Explicación

10001

Called method unknown.

El nombre del método invocado no existe o no es válido.

10002

Invalid Access.

La dirección IP del servidor que llamó a los Web Services no está cargada en la lista de acceso para el usuario.

10003

Not allowed in this partition.

Se solicitó el entorno de producción con la contraseña del entorno de testeo o viceversa.

10004

XML message could not be parsed.

El mensaje XML enviado no está bien formado.

10005

Invalid Credentials.

El usuario o contraseña enviados no son válidos.

10011

XML response has an error. Please try again.

El mensaje XML de respuesta no está bien formado. Se recomienda intentar nuevamente y contactar a webservices@kiusys.com si se reitera el error.

10026

The TerminalID is not an authorized device.

El TerminalID enviado no está declarado en la opción "Devices and Sines List" del Web Services Manager.

10027

The AgentSine is not authorized for this device.

El AgentSine enviado no está asociado a ningún TerminalID en la opción "Devices and Sines List" del Web Services Manager.

11001

Error at parameter EchoToken.

El valor del atributo "EchoToken" no se corresponde con el formato descripto (alfanumérico en mayúsculas de entre 0 y 128 caracteres inclusive).

11002

Error at parameter SequenceNmbr.

El valor del atributo "SequenceNmbr" no se corresponde con el formato descripto (número entero mayor o igual a 1).

11036

Error at parameter TerminalID.

El TerminalID enviado no se corresponde con el formato descripto (alfanumérico de diez caracteres) o no pertenece al usuario.

11037

Error at parameter AgentSine.

El AgentSine enviado no se corresponde con el formato descripto (alfanumérico de nueve caracteres) o no pertenece al usuario.

11073

Error at parameter Target.

El valor del atributo "Target" no es una de las dos opciones válidas (Production/Testing).

12001

Error processing your request. Please try again.

Hubo un error de procesamiento de la llamada. Se recomienda intentar nuevamente y contactar a webservices@kiusys.com si se reitera el error.

13001

Server response was invalid or incomplete.

Hubo un error interno de servidores. Se recomienda intentar nuevamente y contactar a webservices@kiusys.com si se reitera el error.

Volver al índice