Price Surfer - Web Services

De Wiki PriceSurfer
Ir a la navegaciónIr a la búsqueda

Sumario

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


Flujo de Mensajes para la correcta implementación del Servicio

Flujo.jpg

Flujo de mensajes para la correcta implementación del Servicio


Atención: Para los productos hoteles, si su operador tiene el módulo de CANCELACION AUTOMATICA activado deberá disparar una Consulta de una Reserva inmediatamente luego de la reserva cuando ésta quede en estado Confirmada o Pendiente de Confirmación; de esta forma se creará correctamente la tarea de autocancelación para la reserva.

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

Mensajes xml:

Búsqueda de Disponibilidad de Hoteles: 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.


Confirmación de Disponibilidad de una Tarifa obtenida en una Búsqueda Anterior: Confirma la vigencia de una tarifa provista por una consulta de disponibilidad previa.


Consulta de Información de un Hotel: Consulta la información y detalles para un hotel provisto por el proveedor.


Consulta de Gastos de Cancelación para una o varias Tarifas ó Reservas: Consulta de condiciones de gastos de cancelación sobre una o más tarifas o reservas reportadas.


Reserva de Tarifa: Solicitud de reserva para una o varias tarifas de hoteles.


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


Cancelación de Reserva: Solicitud de cancelación de una o varias reservas realizadas.

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:

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 y otras cabeceras necesarias

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.

Además de la cabecera para la autorización deben enviarse las cabeceras estandars

  • Accept con valor application/xml
  • Accept-Encoding con valor gzip,deflate (solicitar la compresión de la respuesta para acelerar el tiempo de llegada de la misma)

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. La sumarizacion 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.


  • Cuando se hace una petición del tipo AvailabilityQueryRQ con el atributo TransactionMode="StartAsync", no hace falta colocar nada en la propiedad TransactionId (no colocar nada o poner TransactionId="").
  • En la respuesta a este mensaje (AvailabilityQueryRS), se obtendrá un TransactionId="1ff8f362_2dd0_4d5d_87f8_3b07567de116" (por ejemplo).
  • Cada siguiente llamado a AvailabilityQueryRQ con TransactionMode="ContinueAsync" se deberá usar este TransactionId.

[Cabe aclarar que en el modo ContinueAsync no se tomará en cuenta el resto de la petición xml del request (GeneralParameters, Trips, Passengers), pero por ahora como son obligatorios se tendrá que colocar los mismos.]

Sobre el pedido de información de hoteles

Para descargar las fichas con la información de los hoteles (Mensaje AdditionalInfoQuery: API Reference: Consulta de Información de un Hotel), recomendamos enfáticamente generar una cola con un pull de hasta 5 peticiones simultaneas (esto es, hacer pedidos en batch de 5 peticiones por vez). De esta forma se puede ir descargando la información de hoteles a lo largo de todo el día sin afectar a la performance.

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:

Para el entorno de TEST:

Para el entorno de PRODUCCIÓN:

Importante: Las imágenes también están disponibles a través de una URL segura (indicar el protocolo https en vez de http)


Ejemplos: Suponiendo que la respuesta a la consulta de información adicional de un hotel es <AdditionalInfoQueryRS> 

 <Details>
   <Products>
     <Hotels>
       <Hotel HotelCode="2444" SupplierID="HDO" Sequence="1" HotelDetailId="IDJ-1YT-4MO">
         <HotelName>El Conquistador Hotel</HotelName>
         <HotelDescriptions>
           ...
         </HotelDescriptions>
         <Amenities>
           ...
         </Amenities>
         <Addresses>
           ...
         </Addresses>
         <Position>
           ...
         </Position>
         <HotelRating HotelRatingCode="NMO.HTL.RTN.4ST" HotelRatingType="NMO.HTL.RTT.STR">
           ...
         </HotelRating>
         <ImageLinks>
           <ImageLink>
             <ImageLink>
             <ImageDescription ImageDisplayType="NMO.GBL.IMG.IMG"/>
             <ImageHeight UnitOfMeasureCode="9">185</ImageHeight>
             <ImageWidth UnitOfMeasureCode="9">250</ImageWidth>
             <ImageURL>IDJ/B/B/BB3898629BE8D3DB188164A6611AA350.jpg</ImageURL>
             <ThumbnailURL>IDJ/4/A/4A78390A062E3F504912F5E9ADEDBDB5.jpg</ThumbnailURL>
           </ImageLink>
         </ImageLinks>
         <LocationDetails>
           ...
         </LocationDetails>
       </Hotel>
     </Hotels>
   </Products>
 </Details>

</AdditionalInfoQueryRS>

Entonces las URLs quedarían:

Si la respuesta fue del Web Service de TEST:

Si la respuesta fue del Web Service de PRODUCCIÓN:

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 30 minutos, por lo cual los clientes del Web Service podrán usar los TripProductId devueltos por el mismo antes de los 30 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
1015 No credit for doing the booking. El Contrato tiene establecido un límite de crédito que ha sido alcanzado, la reserva es rechazada por ese motivo.
1103 The booking of this product has been rejected by configuration: the product has cancellation charges as of this moment La reserva del producto ha sido rechazada porque, por configuración del contrato, el sistema rechazará las reservas que entren en Gastos de Cancelación al momento de realizarlas.
1104 The system couldn't check the cancellation charges of the product El sistema no pudo obtener los Gastos de Cancelación del producto.
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:

  • Fecha en que ocurrió la incidencia
  • Entorno (Test / Producció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
General Tipos de Email

Destinos

Listado de destinos de Price Surfer:

Obtenido de «https://wiki.psurfer.net/index.php?title=Price_Surfer_-_Web_Services&oldid=2060»