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.

IMPORTANTE:

A partir de Octubre 2022 es requerida una lista de IPs habilitadas para poder operar, las IP que no sean informadas como autorizadas serán bloqueadas impidiendo la operatoria.

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.

El uso de dichas credenciales excluye la posibilidad de aplicarlas para otros fines como trabajar con un robot que realice búsquedas de disponibilidad para obtener tarifas y almacenarlas u otra tarea no especificada en este documento; reservando a Price Surfer el derecho de deshabilitar dicho usuario. Cualquier cambio que se desee realizar deberá ser notificado y aprobado con anticipación.

Documentos de Certificacion a utilizar en los Webservices de hoteles se encuentran disponibles:

• Idioma español: http://wiki.psurfer.net/resources/CertificacionWS.docx
• Idioma ingles: http://wiki.psurfer.net/resources/Certification_WS_en.docx

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 - Entornos y Operaciones

Los entornos disponibles son:

• Produccion: http://service.psurfer.net/pricesurfer/

• Certificacion: http://service-cert.psurfer.net/pricesurfer/

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

Ejemplo de endpoint de busqueda en Entorno de Certificacion:

• http://service-cert.psurfer.net/pricesurfer/catalog/products/search

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

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 del booking cuando éste quede en estado Confirmada o Pendiente de Confirmación; de esta forma se creará correctamente la tarea de autocancelación para la reserva.

Nota: Se recomienda disparar una Consulta de una Reserva luego de realizar un booking ya que brinda el estado final en el sistema.

Lista de Mensajes XML por cada Operación

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

Documentación online: http://wiki.psurfer.net/resources/PSCEV-doc/pscev.html

Proyecto SoapUI para desarrollo (guia incluida): PS_WebServices-soapui-project.xml.zip

Mensajes xml:

• Operación: /catalog/products/search AvailabilityQueryRQ AvailabilityQueryRS

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.

• Operación: /catalog/product/detail AditionalInfoQueryRQ AditionalInfoQueryRS

Consulta de Información de un Hotel: Consulta la información y detalles de los hoteles provistos por el proveedor.

• Operación: /catalog/product/validate AvailabilityValidationRQ AvailabilityValidationRS

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.

• Operación: /booking/cancellation/fees CancellationFeesQueryRQ CancellationFeesQueryRS

Consulta de Gastos de Cancelación para una Tarifa ó Reserva: Consulta de condiciones de gastos de cancelación sobre una tarifa o reserva reportada.

• Operación: /catalog/product/book BookingProductsRQ BookingProductsRS

Reserva de Tarifa: Solicitud de reserva para una tarifa de hotel.

• Operación: /booking/detail BookingQueryRQ BookingQueryRS

Consulta de Reserva: Consulta de información y detalles sobre una reserva realizada. Es necesario para obtener el detalle final de la reserva confirmada en el sistema.

• Operación: /booking/cancel BookingCancellationRQ BookingCancellationRS

Cancelación de Reserva: Solicitud de cancelación de una reserva realizada.

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.

En Produccion -> http://service.psurfer.net/pricesurfer/application.wadl

En Staging -> http://service-cert.psurfer.net/pricesurfer/application.wadl

Especificaciones y recomendaciones

Administracion de los TripProductIDs

Para evitar inconvenientes respecto de expiración de tarifas cuando el tiempo del flujo de reserva es elevado, recomendamos utilizar siempre el TripProductID obtenido en cada mensaje previo del flujo de reserva y que no siempre es el mismo que se obtuvo en la búsqueda original:

1- En el mensaje AvailabilityValidationRQ (Validación de Tarifa) utilizar el TripProductID que se responde en el AvailabilityQueryRS (respuesta de la Búsqueda)

2- En el mensaje CancellationFeesQueryRQ (Politica de Gastos) utilizar el TripProductID que se responde en el AvailabilityValidationRS (respuesta de Validación de Tarifas)

3- En el mensaje BookingProductsRQ (Reserva) utiliza el TripProductID que se responde en el CancellationFeesQueryRS (respuesta de Política de Cancelación)

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 (entorno de Cert)

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

Solo es posible usar el modo 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.

Si algún proveedor supera el tiempo máximo permitido (timeout configurado por nosotros) no se devolverán resultados del mismo.

Puede ocurrir que los resultados retornados por el WS no sean los mismos que los resultados del sitio online de PriceSurfer. Esto ocurre porque un proveedor que se interrumpe por timeout sigue guardando resultados en la cache de resultados, que están disponibles solo en la aplicación online, y no en el ws. Por consiguiente si se interrumpe algún proveedor por timeout se perderán esos datos por 30 minutos, ya que quedarán ocultos por la caché del ws.

Aconsejamos ajustar el timeout en un tiempo no muy corto para no tener falta de tarifas.

Contemplar las restricciones generales en la cantidad de peticiones de como máximo 10 peticiones cada 10 segundos.

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 peticiones con hasta 20 HotelDetailIds (realizar pedidos en batch de hasta 20 HotelDetailsIds 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. Contemplar las restricciones generales en la cantidad de peticiones de como maximo 10 peticiones cada 10 segundos.

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:

• http://psurfer-img.net/imagecache-cert/full/ (para las fotos en tamaño original)
• http://psurfer-img.net/imagecache-cert/thumbnails/ (para las imágenes en miniatura)

Para el entorno de PRODUCCIÓN:

• http://psurfer-img.net/imagecache-prod/full/ (para las fotos en tamaño original)
• http://psurfer-img.net/imagecache-prod/thumbnails/ (para las imágenes en miniatura)

Importante:

• Las imágenes también están disponibles a través de una URL segura (indicar el protocolo https en lugar de http)
• Existen excepciones en algunos proveedores de hoteles, y algunas imágenes ya vienen con la URL completa, o sea, ya comienzan con http.....En estos casos no colocar la URL delante porque les fallaría.

Ejemplo:

- URL normalizada para imágenes: <ImageURL>IDJ/B/B/BB3898629BE8D3DB188164A6611AA350.jpg</ImageURL>

- URL completa <ImageURL>http://psurfer-img.net/pathalaimagen/imagen.jpg</ImageURL>

(En este caso por favor no pegar la URL base delante)

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:

• http://psurfer-img.net/imagecache-cert/full/IDJ/B/B/BB3898629BE8D3DB188164A6611AA350.jpg
• http://psurfer-img.net/imagecache-cert/thumbnails/IDJ/4/A/4A78390A062E3F504912F5E9ADEDBDB5.jpg

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

• http://psurfer-img.net/imagecache-prod/full/IDJ/B/B/BB3898629BE8D3DB188164A6611AA350.jpg
• http://psurfer-img.net/imagecache-prod/thumbnails/IDJ/4/A/4A78390A062E3F504912F5E9ADEDBDB5.jpg

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.

Sobre los comentarios del proveedor

Los proveedores pueden llegar a enviar comentarios/remarks en dos instancias diferentes:

La primera en el resultado de la búsqueda: Tag Item Comments del Rate API Reference: Búsqueda de Disponibilidad de Hoteles

La segunda alternativa en la respuesta de la consulta de la reserva: SupplierComments API Reference: Consulta de una Reserva - Hoteles

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.
1101	The TripProductId %s is not available	El TripProductId no fue encontrado. Este mensaje aparece cuando el rate no se encuentra disponible en el proveedor, porque ha cambiado alguno de los diferentes atributos del rate (regimen / precio / tipo de disponibilidad) Para estas situaciones, se debe cambiar a otro tripProductID, para chequear su disponibilidad en el proveedor.
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.
1105	The booking of this product has been rejected by deadline: the product has cancellation charges	El booking no se realizo ya que fue abortado el proceso (previo a la reserva) porque el contrato tiene activado el bloqueo para reservar items con "gastos de cancelacion".
1106	The booking of this product has been rejected because price has changed	El booking no se realizo ya que fue abortado el proceso porque la validacion pre-booking detecto que el precio ha cambiado.
1107	Rate's live time in cache has been expired	El tiempo de vida del rate en cache ha sido expirado.
1108	Connectivity error	Error de conectividad detectado en dicho momento. En dicha situacion se debe enviar nuevamente el mensaje del caso.
1109	Unable to Query Booking	Errores generados al consultar el Detalle de Reserva.
3000	Request detail for current booking - Relationated with TripProductId: xxxyyy	Ante dicha situacion se debe realizar la consulta de detalle de reserva para recuperar la info detallada y actualizada de la reserva.
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.
5120	There are not availability when is booking	El rate no esta disponible para ser reservado.
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
General	Códigos de proveedores
Tarifa	Tipos de tarifa

Destinos

Listado de destinos de Price Surfer:

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