Sletat Ru Provider API — различия между версиями

Версия 15:33, 21 января 2016

Service Description

In order to integrate with SLETAT.RU you need to create a web service that will perform the following tasks:

• Unload directories: cities of departure, countries, resorts, hotels, etc.
• Implement parameterized price search
• Actualize the selected tour by its ID

For simplicity, the service can be made as a web page that accepts GET or POST parameters and returns the answer in XML (not SOAP) format

The same address should be used for all methods of the web service. For example, if you implement the service at: http://mysite.com/services/sletatru.xml , then this address must remain the same for all requests.

For example: :

• http://mysite.com/services/sletatru.xml?action=GetCountries – list of countries request
• http://mysite.com/services/sletatru.xml?action=GetDepartCities – list of departure cities request

The results should be presented in XML. Described format should be applied for each method in the document.

Version attribute indicating the version of the protocol should be specified for the root element in the result. The attribute is needed to determine the version of the tour provider with SletatRu service.

Example:

<getCountriesResult version="1.0">
...
</getCountriesResult> 

This document describes 1.0 version of the protocol.

All methods should return XML in UTF-8.

Все параметры запросов, не помеченные как обязательные, являются необязательными только для стороны, формирующей запрос. Для серверной стороны обработка всех полученных параметров запроса обязательна.

Результат выполнения запросов (поискового в частности) должен строго соответствовать указанным параметрам. Если параметр не обязателен и не указан, запрос его не учитывает и возвращает все варианты.

Pool of IP addresses, from which the service SletatRu communicates the realized tour provider, is provided separately. Для его уточнения необходимо написать на support@sletat.ru

Additional Requirements to the Service

Maximum time of work with any executed method of service should not exceed 30 seconds, the recommended response time (including the tour booking method) is up to 5 seconds. If any method takes longer than 30 seconds to return the results, SletatRu will not process the data.

Any method of the service can be called simultaneously by different threads. Therefore, in realization of the methods, there should not be locks which synchronize access to the methods. The tour booking method must support simultaneous execution of multiple search queries.

The number of queries per day can be determined separately and depends on the following parameters:

• the number and popularity of the tour operator’s destinations
• the number of departure cities
• the number of search queries in SletatRu service.

Methods to Be Realized

The following elements have been specified in the document for each method: purpose of each method, the list of input parameters, the output format, description and the types of data used in the output of the methods.

The types of data listed below have been used in the methods:

• Int32 – integer (32 bits signed) from 2, 147, 483, 648 to 2, 147, 483, 647
• Int64 – integer (64 bits signed)
• UInt64 – integer (64 bits unsigned)
• String - text

Returning the List of Countries

This method returns all destinations of the tour operator.

Format of the query: ?action=GetCountries

Parameters:

• id – destination country identifier (optional; if specified, only one entry is queried)

The output format:

<getCountriesResult version="1.0">
 <country id="{Int32}" name="{String}" />
 ...
</getCountriesResult>

The root element getCountriesResult contains an arbitrary number of elements country, where each one of them describes destination with attributes: id (destination country identifier) and name (name of the country, Ru/Eng language).

Returning the List of Departure Cities

The method returns all available cities of departure, and also contains data on what tour destinations are available from each city of departure. SletatRu service calls this method periodically in order to update the list of available destinations from each city of departure.

Format of the query: ?action=GetDepartCities

Parameters:

• id – departure city identifier (optional; if specified, only one entry is queried)

The output format:

<getDepartCitiesResult version="1.0">
 <city id="{Int32}" name="{String}">
 <countryTo id="{Int32}" />
 ...
 </city>...
</getDepartCitiesResult>

The root element getDepartCitiesResult contains an arbitrary number of city elements, where each one of them describes the city of departure with attributes: id (city identifier) и name (name of the city, language Ru/Eng). Each city element also should contain a set of countryTo elements, where each one of them describes available destination from the city of departure; for countryTo element, id attribute (destination country identifier) should be specified.

Returning the List of Resorts

This method returns the list of all available resorts.

Format of the query: ?action=GetResorts

Parameters:

• id – resort identifier (optional; if specified, only one entry is queried)

The output format:

<getResortsResult version="1.0">
 <resort id="{Int32}" name="{String}" countryId="{Int32}" />
 ...
</getResortsResult>

The root element getResortsResult contains an arbitrary number of resort elements, where each one of them describes the resort with attributes: id (resort identifier), name (name of the resort, language Ru/Eng) and countryId (identifier of the home country of the resort).

Returning the List of Hotel Categories

This method returns the list of hotel categories, e.g. 3*, 4*, Apts, etc.

Format of the query: ?action=GetHotelCategories

Parameters:

• id – hotel category identifier (optional; if specified, only one entry is queried)

The output format:

<getHotelCategoriesResult version="1.0">
 <hotelCategory id="{Int32}" name="{String}" />
 ...
</getHotelCategoriesResult>

The root element getHotelCategoriesResult contains an arbitrary number of hotelCategory elements, where each one of them describes a hotel category with attributes: id (identifier) and name (name).

Returning the List of Hotels

This method returns the list of all available hotels, preferably only those, which actual prices are available through the tour operator.

Format of the query: ?action=GetHotels

Parameters:

• id – hotel identifier (optional; if specified, only one entry is queried).

The output format:

<getHotelsResult version="1.0">
 <hotel id="{Int32}" name="{String}" hotelCategoryId="{Int32}" resortId="{Int32}" />
 ...
</getHotelsResult> 

The root element getHotelsResult contains an arbitrary number of hotel elements, where each one of them describes a hotel with attributes: id (identifier), name (name of the hotel), hotelCategoryId (hotel category identifier) and resortId (identifier of the resort in which this hotel is located).

Returning Meal Options

This method returns the list of meal options available, e.g. HB, BB, no meals, etc.

Format of the query: ?action=GetMeals

Parameters:

• id – identifier of the meal type (optional; if specified, only one entry is queried)

Формат выдачи:

<getMealsResult version="1.0">
 <meal id="{Int32}" name="{String}" />
 ...
</getMealsResult>  

The root element getMealsResult contains an arbitrary number of meal elements, where each of them describes a meal option with attributes: id (identifier) and name (name).

Выгрузка списка валют

Метод возвращает список используемых валют. Список обязательно должен содержать рубли, доллары и евро.

Формат запроса: ?action=GetCurrencies

Параметры:

• id – идентификатор валюты (опциональный; если указан, то запрашивается только одна запись)

Формат выдачи:

<getCurrenciesResult version="1.0">
 <currency id="{Int32}" name="{String}" />
 ...
</getCurrenciesResult>

Корневой элемент getCurrenciesResult содержит произвольное количество элементов currency, каждый из которых описывает валюту атрибутами id (идентификатор) и name (название).

Поиск туров

Метод поиска туров использует множество параметров для поиска и фильтрации туров. Метод лишь должен возвращать наиболее дешевые предложения, найденные по предоставленным параметрам. Количество туров в выдаче регулируется параметром count.

Формат запроса: ?action=GetTours

Параметры:

Формат выдачи:

<getToursResult version="1.0">
 <tour
  offerId="{Int64}"
  tourName="{String}"
  hotelId="{Int32}"
  hotelUrl="{String}"
  resortId="{Int32}"
  hotelCategoryId="{Int32}"
  mealId="{Int32}"
  htPlaceName="{String}"
  roomTypeName="{String}"
  tourDate="{String}"
  nights="{Int32}"
  price="{Int32}"
  hotelIsInStop="{Int32}"
  ticketsIncluded="{Int32}"
  hasEconomTicketsDpt="{Int32}"
  hasEconomTicketsRtn="{Int32}"
  hasBusinessTicketsDpt="{Int32}"
  hasBusinessTicketsRtn="{Int32}"
  tourUrl="{String}"
  spoUrl="{String}"
  fewPlacesInHotel="{Int32}"
  fewTicketsDptY="{Int32}"
  fewTicketsRtnY="{Int32}"
  fewTicketsDptB="{Int32}"
  fewTicketsRtnB="{Int32}"
  flags="{UInt64}"
  description="{String}"
  receivingParty="{String}"
  earlyBookingValidTill="{String}"
  />
 ...
</getToursResult>

Корневой элемент getToursResult содержит произвольное количество элементов tour (от 0 элементов, но не более количества указанного в параметре count), каждый из которых описывает тур следующими атрибутами:

Актуализация тура

Метод служит для получения окончательной цены тура (со всеми обязательными доплатами и сборами), списка включенных в стоимость тура услуг, а также вариантов перелета, возможных дополнительных услуг и доплат по ним. Метод должен возвращать цену самой дешевой конфигурации запрашиваемого предложения. Для корректной работы метода необходимо, чтобы offerId был уникален для предложений с разным составом группы туристов, даже в случае если все прочие параметры предложений совпадают.

Формат запроса: ?action=ActualizeTour

Параметры:

Формат выдачи:

<actualizeTourResult version="1.0">
 <actualizedTour
  price="{Int32}"
  ticketsIsIncluded="{Int32}"
  hotelIsInStop="{Int32}"
  hasEconomTicketsDpt="{Int32}"
  hasEconomTicketsRtn="{Int32}"
  hasBusinessTicketsDpt="{Int32}"
  hasBusinessTicketsRtn="{Int32}"
  fewPlacesInHotel="{Int32}"
  fewEconomTicketsDpt="{Int32}"
  fewEconomTicketsRtn="{Int32}"
  fewBusinessTicketsDpt="{Int32}"
  fewBusinessTicketsRtn="{Int32}"
  tourUrl="{String}"
 >
  <services>
   <service
    id="{Int32}"
    type="{String}"
    name="{String}"
    isIncluded="{Int32}"
    description="{String}"
    surcharge="{Int32}"
    flightCompatibleIds="{String}"
    flightClass="{String}"
    flightAvailability="{Int32}"
    flightPlacesCount="{Int32}"
    flightAirportFrom="{String}"
    flightAirportTo="{String}"
    flightNum="{String}"
    flightAirline="{String}"
    flightStartDateTime="{String}"
    flightEndDateTime="{String}"
    flightAircraft="{String}"
   />
   ...
  </services>
 </actualizedTour>
</actualizeTourResult>

Корневой элемент actualizeTourResult должен содержать единственный элемент actualizedTour, который описывается следующими атрибутами:

Элемент actualizedTour может содержать секцию services, которая в свою очередь содержит произвольное число элементов service. Каждый элемент service описывает услугу включенную в стоимость тура, либо услугу, добавление которой возможно в текущей конфигурации тура. Атрибуты элемента service: