Price Surfer - Web Services

Price Surfer - Mensajes de Web Services

Introducción

El servicio Web de Price Server permite a sus agentes conectarse de manera transparente a la aplicación a través de un conjunto de funciones que pueden ser llamadas, desde las páginas web de sus sitios. Para lograr esto, se proveerá una Interfaz de Programación de Aplicaciones (API) para permitir que varios tipos de sistemas clientes se conecten al sistema propio de Nemo utilizando un juego de mensajes XML que han sido publicados y definidos en conformidad a los Estándares de Esquemas XML. La interfaz que provee servicios de búsquedas, reservas, etc. será entonces accesible vía una interfaz basada en XML y disponible para clientes registrados.

A través del servicio web un agente podrá consultar disponibilidad en hoteles para los proveedores asociados a su contrato, solicitar información sobre hoteles, gestionar reservas y cancelaciones. Todo a través de una interfaz única basada en el intercambio de documentos XML, que será descripta en esta guía de uso.

Propósito del presente documento

La función del documento es la de remarcar la estructura de la ya mencionada API, las funciones estándares que se proveen y aquellas funciones específicas que son dispuestas mediante la misma.

Implementación

Para poder iniciar la implementación y hacer pruebas a nuestro servidor de test, necesitará una serie de credenciales para utilizar durante el proceso de integración del servicio con su aplicación web, Las credenciales son: un "token" para el acceso al web service y un usuario y contraseña para acceder a la aplicación de Price Surfer y al Backoffice de configuración.

Luego de completada la integración deberá contactarnos nuevamente para solicitar una revisión para la certificación final de su sitio. Además de las credenciales provistas recibirá una descripción de los servicios provistos bajo WADL, el equivalente REST del Lenguaje de Descripción de Web Services (WSDL). Nuestro servicio es un servicio web estándar basado en REST para el intercambio de documentos XML, la seguridad es controlada a través de cabeceras WSS donde deberá incluir un Token de Autenticación.

Interfaz Cliente simplificada

La API publicada ofrece protocolos estándares de HTTPS que habilitan al servicio a través de solicitudes HTTPS bajo POST permitiendo así las siguientes ventajas:

• Protocolos estándares de acuerdo a la Industria
• No hay necesidad de establecer un middleware como componente adicional (ej. MQ Series)
• Seguridad establecida a través del uso de SSL
• Se provee un mecanismo más eficiente para el manejo de mensajes asíncronos mediante la tecnología “Push”

API REFERENCE - Operaciones

Las siguientes operaciones están disponibles en la API del servicio, para búsquedas y reservas de Hoteles.

/catalog/products/search

/catalog/product/detail

/catalog/product/validate

/catalog/product/book

/booking/cancellation/fees

/booking/detail

/booking/cancel

Todas las operaciones tienen un POST con el siguiente esquema:

POST

Request Body

media types:

application/xml

Response Body

media types:

application/xml

---

Cada operación de la API necesita un xml según el mensaje que corresponda. A continuación se presentarán los XML necesarios para cada operación. Este xml va adjuntado como "raw" en el POST del http.

Por ejemplo, en linux desde la consola con bash podemos probar la conexión y los parámetros necesarios haciendo:

 curl -i -H "Accept: application/xml" -H "Content-Type: application/xml" \
  -H "X-PS-AUTHTOKEN:xxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "`cat AvailabilityQueryRQ.xml`" \
  -o "result.xml" -v \
  -X POST "http://#url-servicio-psurfer#/pricesurfer/catalog/products/search"

Esto conectará al Web Service y hará un pedido de disponibilidad de productos.

Deberá existir el archivo AvailabilityQueryRQ.xml que contendrá un xml como por ejemplo el presentado más abajo.

La respuesta se guardará en el archivo result.xml.

El valor la cabecera X-PS-AUTHTOKEN es un token de seguridad que será suministrado por Soporte de Price Surfer cuando se les entreguen los usuarios correspondientes en el alta del servicio.

Para aumentar la velocidad de respuesta desde el servidor del WebService hasta el cliente, se recomienda agregar en la cabecera HTTP la solicitud de compresión de la respuesta, en el ejemplo con curl anterior se agregaría: -H "Accept-Encoding: gzip" \

Lista de Mensajes XML por cada Operación

Están disponibles los esquemas XSD de PriceSurfer: http://wiki.psurfer.net/resources/pscev-schema.zip

O si desea la documentación online: http://wiki.psurfer.net/resources/PSCEV-doc/pscev.html

Documentación generada automáticamente por el servicio: http://wiki.psurfer.net/resources/REST-doc/index.html

Búsqueda de Disponibilidad de Hoteles (AvailabilityQueryRQ)

Consulta de disponibilidad de tarifas de hoteles para un set de habitaciones, con una configuración de pasajeros, en un destino y un rango de fechas determinado. Retorna una colección de tarifas, una por cada hotel ofrecido por los proveedores habilitados para el contrato del usuario.

Operación: /catalog/products/search

Recibe AvailabilityQueryRQ

Retorna AvailabilityQueryRS

Confirmación de Disponibilidad de una Tarifa obtenida en una Búsqueda Anterior (AvailabilityValidation)

Confirma la vigencia de una tarifa provista por una consulta de disponibilidad previa.

Operación: /catalog/product/validate

Recibe AvailabilityValidationRQ

Retorna AvailabilityValidationRS

Consulta de Información de un Hotel (AdditionalInfoQuery)

Consulta la información y detalles para un hotel provisto por el proveedor.

Operación: /catalog/product/detail

Recibe AditionalInfoQueryRQ

Retorna AditionalInfoQueryRS

Consulta de Gastos de Cancelación para una o varias Tarifas ó Reservas (CancellationFeesQuery)

Consulta de condiciones de gastos de cancelación sobre una o más tarifas o reservas reportadas.

Operación: /booking/cancellation/fees

Recibe CancellationFeesQueryRQ

Retorna CancellationFeesQueryRS

Reserva de Tarifa (BookingProducts)

Solicitud de reserva para una o varias tarifas de hoteles.

Operación: /catalog/product/book

Recibe BookingProductsRQ

Retorna BookingProductsRS

Consulta de Reserva (BookingQuery)

Consulta de información y detalles sobre una o varias reservas realizadas.

Operación: /booking/detail

Recibe BookingQueryRQ

Retorna BookingQueryRS

Cancelación de Reserva (BookingCancellation)

Solicitud de cancelación de una o varias reservas realizadas.

Operación: /booking/cancel

Recibe BookingCancellationRQ

Retorna BookingCancellationRS

Escenario básico de una operación de reserva

Especificación de documentos XML

Búsqueda de Disponibilidad de Hoteles (AvailabilityQuery)

API Reference: Búsqueda de Disponibilidad de Hoteles

Consulta de Información de un Hotel (AdditionalInfoQuery)

API Reference: Consulta de Información de un Hotel

Confirmación de Disponibilidad de una Tarifa obtenida en una Búsqueda Anterior (AvailabilityValidation)

API Reference: Confirmación de Disponibilidad de una Tarifa

Consulta de Gastos de Cancelación para una Tarifa ó Reserva (CancellationFeesQuery)

Operación exclusiva para Hoteles. Devuelve las condiciones de gastos de cancelación para una Tarifa ó una Reserva.

Request: CancellationFeesQueryRQ (Estructura del Documento)

Response: CancellationFeesQueryRS (Estructura del Documento)

Se pueden consultar de dos formas:

• Con el TripProductId de una búsqueda
• Con el BookingReference de una reserva

Reserva de Tarifa (BookingProducts)

Solicitud de reserva para una tarifa.

Request: BookingProductsRQ (Estructura del Documento)

Response: BookingProductsRS (Estructura del Documento)

Detalles y ejemplos: Reserva de una Tarifa - Hoteles

Cancelación de Reserva (BookingCancellation)

Solicitud de cancelación de una reserva confirmada.

Request: BookingCancellationRQ (Estructura del Documento)

Response: BookingCancellationRS (Estructura del Documento)

Detalles y ejemplos: Cancelación de una Reserva - Hoteles

Consulta de Reserva (BookingQuery)

Consulta de información y detalles sobre una reserva.

Request: BookingQueryRQ (Estructura del Documento)

Response: BookingQueryRS (Estructura del Documento)

Detalles y ejemplos: Consulta de una Reserva - Hoteles

Lenguaje de Descripción de la Aplicación Web (WADL)

Utilizando la especificación provista por Price Surfer los Clientes podrán acceder al catálogo de los servicios y recursos provistos en la API.

Especificaciones y recomendaciones

Autorización

Para acceder a las operaciones propias del servicio web será necesario el uso de credenciales por medio de un hash que actúa como Token de Autorización. El servicio utilizará para esto una cabecera especial denominada "X-PS-AUTHTOKEN" la cuál actuará como clave de seguridad interna para establecer la comunicación entre el sistema y el usuario.

Ejemplo de cabecera

• Solicitud

POST http://service-cert.psurfer.net/pricesurfer/catalog/products/search HTTP/1.1

Accept-Encoding: gzip,deflate

Accept: application/xml

Content-Type: application/xml

X-PS-AUTHTOKEN: 981d284d_bc57_c429_91b9_178fg07f78f0

Content-Length: 770

Host: http://service-cert.psurfer.net

Connection: Keep-Alive

User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

• Respuesta

HTTP/1.1 200 OK

X-Powered-By: Servlet/3.0

Server: GlassFish Server Open Source Edition 3.0.1

Content-Type: application/xml

Transfer-Encoding: chunked

Content-Encoding: gzip

Vary: Accept-Encoding

Date: Wed, 31 Jul 2013 10:39:32 GMT

TransactionMode Sincrónico y Asincrónico

Este modo se utiliza para Hoteles.

• Sincrónico: TransactionMode="Synchronous"

Las búsquedas en este modo esperarán que termine hasta el último proveedor en responder. Luego se ordenarán por precio y se retornarán. Esta es el método que utiliza la plataforma de PriceSurfer hsata este momento.

• Asincrónico: TransactionMode="StartAsync" y "ContinueAsync"

En este modo deberá iniciarse una búsqueda con el modo "StartAsync". La búsqueda termina cuando termine el primer proveedor, o sea el más rápido. El resto de los resultados se obtendrán con subsecuentes búsquedas pero con el modo "ContinueAsync".

Cada respuesta a este mensaje contiene un nodo "TransactionStatus" que se encuentra en la respuesta de Hoteles: {AvailabilityQueryRS//Details/Trips/TripList[n]/HotelsAvailabilityResponset/TransactionStatus} y su valor puede ser FINISHED, TIMEOUT o CONTINUE.

• FINISHED: significa que no hay más datos. Ésta es la última respuesta.
• TIMEOUT: significa que no hay más datos. Ésta es la última respuesta. La diferencia con FINISHED es que ha terminado con algún error en un proveedor y el mismo no pudo terminar el proceso.
• CONTINUE: significa que hay más datos de disponibilidad de hoteles. Debe seguir haciendo peticiones en modo "ContinueAsync" para obtener más resultados.

Sobre las Imágenes - Hoteles

• Recomendamos que tengan su propia librería de íconos para las amenities
• Para URL de las imágenes de los hoteles deben usar:
  • http://www.psurfer.net/imagecache/thumbnails/ (para las imágenes en miniatura)
  • http://www.psurfer.net/imagecache/full/ (para las fotos en tamaño original)

Sobre los tiempos de vida de los resultados de búsqueda en el Web Service

Los resultados de búsqueda se mantienen cacheados en el servicio durante 50 minutos, por lo cual los clientes del Web Service podrán usar los TripProductId devueltos por el mismo antes de los 50 minutos, caso contrario el Web Service podrá informar que los TripProductId ya no se encuentran disponibles o son inválidos.

Códigos de Error devueltos por el WebService

Código	Descripción	Significado
1000	Unexepected Error	Ha ocurrido un error inesperado, por favor informe al Soporte de PriceSurfer
5000	No Availability for your request	No ha habido disponibilidad para los parámetros de búsqueda dados
5010	The TripProductId %s was not found	El TripProductId dado no fue encontrado. Pudo haber expirado o es incorrecto (no corresponde a un TripProductId informado por el Web Service en una búsqueda)
5011	The TripProductId %s has expired	El TripProductId dado ha expirado. Sobre la expiración de los resultados de búsqueda
5012	The Search Results of your product have expired	Los Resultados de Búsqueda correspondientes al producto seleccionado han expirado. Sobre la expiración de los resultados de búsqueda
5020	The Product is Invalid: %s	El Producto es Inválido (Cambió el Precio ó Incurría en gastos de Cancelación al momento de reservar)
5100	Invalid Request Document: %s	Se ha enviado un documento inválido. El mensaje contiene información sobre lo que es inválido en el documento
401	Unauthorized	El Token de seguridad (X-PS-AUTHTOKEN) es inválido o no fue enviado

Importante: Información necesaria al reportar un error al Soporte de PriceSurfer

Si necesita informar de un fallo al soporte de PriceSurfer incluya la siguiente información:

• XML de Request enviado al Servicio
• XML de Response con que el Serivicio respondió
• Si es una operación posterior a la Búsqueda de Disponibilidad (Validación de Disponibilidad, Solicitud de Información Adicional, Solicitud de Gastos de Cancelación, Solicitud de Reserva) por favor especificar también el DestinationId (destino) correspondiente al producto sobre el que se intentó la operación.

Archivos adicionales

Para poder consultar disponibilidad en los hoteles necesitará de códigos de destinos, habitaciones, etc. Estos códigos son provistos por Price Surfer en esta sección.

Tablas de Códigos

Aplicable a	Tabla
Hoteles	Códigos de Grupos de Servicios e Instalaciones
Hoteles	Códigos de Estrellas
Reserva	Estados de la Reserva
Hoteles	Tipos de Alojamientos
Hoteles	Tipos de Descripciones
Destinos	Tipos de Destinos
Hoteles	Tipos de Estrellas
Reserva	Tipos de Gastos de Cancelación
Habitaciones	Tipos de Habitaciones
Pasajeros	Tipos de Identificadores de Pasajeros
Hoteles	Tipos de Imágenes
Reservas	Tipos de Localizadores (identificadores) de la Reserva
Pasajeros	Tipos de Nombres de Pasajeros
Pasajeros	Tipos de Pasajeros
Tarifa	Tipos de Pensiones
Hoteles	Tipos de Servicios e Instalaciones (Amenities)
Hoteles	Tipos de Teléfonos

Destinos

Listado de destinos de Price Surfer:

• Español : http://wiki.psurfer.net/resources/DESTINATION_ES.zip
• Inglés : http://wiki.psurfer.net/resources/DESTINATION_EN.zip
• Portugués : http://wiki.psurfer.net/resources/DESTINATION_PT.zip