Sletat Ru Provider API

Материал из wiki.Sletat.ru
Версия от 14:46, 21 января 2016; Vm (обсуждение | вклад) (→‎Выгрузка списка городов вылета)

Перейти к: навигация, поиск

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: :

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>

Корневой элемент getDepartCitiesResult содержит произвольное количество элементов city, каждый из которых описывает город вылета атрибутами id (идентификатор города) и name (название города, язык рус/анг). Каждый элемент city также должен содержать набор элементов countryTo, каждый из которых описывает доступное направление из города вылета. Для элемента countryTo указывается атрибут id с идентификатором страны.

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.

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

Метод возвращает список всех доступных курортов.

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

Параметры:

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

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

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

Корневой элемент getResortsResult содержит произвольное количество элементов resort, каждый из которых описывает курорт атрибутами id (идентификатор курорта), name (название курорта, язык рус/анг) и countryId (идентификатор страны в котором расположен курорт).

Выгрузка списка категорий отелей

Метод возвращает список категорий отелей (примеры: 3*, 4*, Apts и т.д.).

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

Параметры:

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

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

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

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

Выгрузка списка отелей

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

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

Параметры:

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

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

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

Корневой элемент getHotelsResult содержит произвольное количество элементов hotel, каждый из которых описывает отель атрибутами id (идентификатор), name (название отеля), hotelCategoryId (идентификатор категории отеля) и resortId (идентификатор курорта в котором расположен отель).

Выгрузка видов питания

Метод возвращает список видов питания (примеры: HB, BB, без питания и т.д.).

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

Параметры:

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

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

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

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

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

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

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

Параметры:

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

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

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

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

Поиск туров

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

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

Параметры:

Параметр; обязательный Тип данных Описание
offerId Int64 Уникальный идентификатор ранее найденного предложения. В случае, если данный параметр задан, все остальные параметры не обязательны и не должны приниматься в расчет. Метод должен возвращать одну запись.
count Int32 Максимальное количество предложений в выдаче.
countryId Int32 Идентификатор страны.
departCityId Int32 Идентификатор города вылета.
dateFrom String Начальная дата в диапазоне дат вылета в формате dd.MM.yyyy (пример: 31.12.2015).
dateTo String Конечная дата в диапазоне дат вылета в формате dd.MM.yyyy (пример: 31.12.2015).
adults Int32 Количество взрослых.
kids Int32 Количество детей.
kidsAges String Количество полных лет каждому ребёнку. Передаётся в виде строки, перечисление через запятую (пример: 3,6). Значения 0 или 1 используются для обозначения инфантов.
nightsMin Int32 Минимальное количество ночей в туре.
nightsMax Int32 Максимальное количество ночей в туре.
resorts String Идентификаторы курортов, перечисление через запятую.
hotelCategories String Идентификаторы категорий отелей, перечисление через запятую.
hotels String Идентификаторы отелей, перечисление через запятую.
meals String Идентификаторы видов питания, перечисление через запятую.
currencyId Int32 Валюта, в которой должны быть выданы цены, а также валюта для входящих параметров priceMin и priceMax (если они есть).
priceMin Int32 Цена тура от.
priceMax Int32 Цена тура до.
hotelIsNotInStop Int32 При значении "1" - в результатах не должно быть отелей в стопе (отели со статусом «под запрос» допустимы). При значении "0" в результат должны попадать как отели в стопе, так и отели с наличием мест и с местами по запросу.
ticketsIncluded Int32 При значении "1" в результатах должны быть только туры с включенной стоимостью перелёта («только отель» - недопустимы). При значении "0" в результат должны попадать как туры без перелета, так и туры с перелетом.
hasTickets Int32 При значении "1" в результатах должны быть туры только с реальным наличием билетов в перелёте. Не должно быть туров со стопом на перелёте, перелёты со статусом «под запрос» недопустимы. При значении "0" в результат должны попадать как туры без билетов на рейс, так и туры с наличием билетов и с билетами по запросу.
excludeUsualTours Int32 При значении "1" из результатов должны быть исключены туры, являющиеся обычными турами (не являющиеся комбинированными, экскурсионными или шоп-турами). При значении "0" или отсутствии данного параметра, такие туры должны быть включены в результат.
excludeCombined Int32 При значении "1" из результатов должны быть исключены туры, являющиеся комбинированными (в рамках которых турист посещает несколько курортов). При значении "0" или отсутствии данного параметра, такие туры должны быть включены в результат.
excludeShopTours Int32 При значении "1" из результатов должны быть исключены шоп-туры и туры с обязательствами. При значении "0" или отсутствии данного параметра, такие туры должны быть включены в результат.
excludeExcursionTours Int32 При значении "1" из результатов должны быть исключены экскурсионные туры. При значении "0" или отсутствии данного параметра, такие туры должны быть включены в результат.

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

<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 Уникальный идентификатор предложения, по которому в дальнейшем можно провести актуализацию тура или бронирование.
tourName Произвольное название тура.
hotelId Идентификатор отеля.
hotelUrl Ссылка на страницу с описанием отеля.
resortId Идентификатор курорта, в котором расположен отель.
hotelCategoryId Идентификатор категории отеля.
mealId Идентификатор вида питания.
htPlaceName Произвольное название размещения в номере (примеры: DBL, TRP, 2 ADL + 1 CH (212), 2 ADL + INF). Название должно отображать допустимые возрасты детей (если поиск был с указанием количества детей более 0) или то, что размещение с учетом инфанта (+ INF), в соответствующем случае.
roomTypeName Название типа номера (примеры: standard, deluxe, family, deluxe super ocean view).
tourDate Дата начала тура в формате dd.MM.yyyy (пример: 31.12.2015).
tourEndDate Дата окончания тура (дата прилета) в формате dd.MM.yyyy (пример: 31.12.2015).
nights Количество ночей в туре.
price Цена тура в валюте, которая была указана во входном параметре currencyId.
hotelIsInStop Наличие мест в отеле, допустимы значения: 0 – есть места, 1 – нет мест, 2 – запрос.
ticketsIncluded Включена ли стоимость билетов в стоимость тура, допустимы значения: 0 – не включена (тур только отель), 1 – включена (пакетный тур).
hasEconomTicketsDpt Наличие билетов эконом класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasEconomTicketsRtn Наличие обратных билетов эконом класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasBusinessTicketsDpt Наличие билетов бизнес класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasBusinessTicketsRtn Наличие обратных билетов бизнес класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
tourUrl Ссылка, при переходе по которой можно забронировать тур (ссылка может вести на страницу авторизации, но после авторизации должны автоматически попасть на страницу бронирования тура).
spoUrl Ссылка на описание тура, его программы (если есть).
fewPlacesInHotel Поле заполняется, если есть указание на то, что мест в отеле мало. Если нельзя указать точное количество оставшихся мест, то заполняется значением -1, иначе указывается точное количество оставшихся мест.
fewTicketsDptY Поле заполняется, если есть указание на то, что мест эконом класса туда мало. Если нельзя указать точное количество оставшихся мест, то заполняется значением -1, иначе указывается точное количество оставшихся мест.
fewTicketsRtnY Поле заполняется, если есть указание на то, что мест эконом класса обратно мало. Если нельзя указать точное количество оставшихся мест, то заполняется значением -1, иначе указывается точное количество оставшихся мест.
fewTicketsDptB Поле заполняется, если есть указание на то, что мест бизнес класса туда мало. Если нельзя указать точное количество оставшихся мест, то заполняется значением -1, иначе указывается точное количество оставшихся мест.
fewTicketsRtnB Поле заполняется, если есть указание на то, что мест бизнес класса обратно мало. Если нельзя указать точное количество оставшихся мест, то заполняется значением -1, иначе указывается точное количество оставшихся мест.
flags Набор битовых флагов тура. Тур может иметь несколько установленных флагов одновременно, данное значение является их суммой. Возможные флаги тура:
  • 1 – туроператор рекомендует данный тур;
  • 2 – доступно мгновенное подтверждение;
  • 4 – туроператор считает данный тур лучшим предложением;
  • 8 – тур раннего бронирования;
  • 16 – тур позднего бронирования;
  • 32 – туроператор предоставляет скидку на данный тур;
  • 64 – VIP предложение;
  • 128 – тур доступен в кредит;
  • 256 – тур является эксклюзивным предложением туроператора;
  • 512 – при покупке тура туристу подарок;
  • 1024 – тур является комбинированным (турист посещает несколько курортов);
  • 2048 – тур с обязательством (шоп - тур);
  • 4096 – зарезервировано для использования системой;
  • 8192 – экскурсионный тур;
description Дополнительная информация по туру, например, для комбинированных туров может содержать информацию о проживании в отелях.
receivingParty Принимающая сторона.
earlyBookingValidTill Если тур является туром раннего бронирования и известна последняя дата ранней брони, то в данном поле должна быть указана эта дата.

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

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

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

Параметры:

Параметр; обязательный Тип данных Описание
offerId Int64 Уникальный идентификатор ранее найденного предложения.
currencyId Int32 Валюта, в которой должна быть рассчитана цена и доплаты.

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

<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, который описывается следующими атрибутами:

Параметр; обязательный Описание
price Актуализированная цена тура в валюте, которая была указана во входном параметре currencyId
ticketsIsIncluded Включена ли стоимость билетов в стоимость тура, допустимы значения: 0 – не включена (тур только отель), 1 – включена (пакетный тур)
hasEconomTicketsDpt Наличие билетов эконом класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasEconomTicketsRtn Наличие обратных билетов эконом класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasBusinessTicketsDpt Наличие билетов бизнес класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
hasBusinessTicketsRtn Наличие обратных билетов бизнес класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано.
fewPlacesInHotel Поле заполняется, если есть указание на то, что мест в отеле мало. Если нельзя указать точное кол-во оставшихся мест, то заполняется значением -1, иначе указывается точное кол-во оставшихся мест.
fewEconomTicketsDpt Поле заполняется, если есть указание на то, что мест эконом класса туда мало. Если нельзя указать точное кол-во оставшихся мест, то заполняется значением -1, иначе указывается точное кол-во оставшихся мест.
fewEconomTicketsRtn Поле заполняется, если есть указание на то, что мест эконом класса обратно мало. Если нельзя указать точное кол-во оставшихся мест, то заполняется значением -1, иначе указывается точное кол-во оставшихся мест.
fewBusinessTicketsDpt Поле заполняется, если есть указание на то, что мест бизнес класса туда мало. Если нельзя указать точное кол-во оставшихся мест, то заполняется значением -1, иначе указывается точное кол-во оставшихся мест.
fewBusinessTicketsRtn Поле заполняется, если есть указание на то, что мест бизнес класса обратно мало. Если нельзя указать точное кол-во оставшихся мест, то заполняется значением -1, иначе указывается точное кол-во оставшихся мест.
tourUrl Ссылка, при переходе по которой можно забронировать тур (ссылка может вести на страницу авторизации, но после авторизации должны автоматически попасть на страницу бронирования тура).

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

Параметр; обязательный Описание
id Идентификатор услуги, уникальный в рамках данного предложения.
type Тип услуги. Может принимать одно из следующих значений:
  • “Insurance” – страховка;
  • “DptTransport” – перелет туда;
  • “RtnTransport” – перелет обратно;
  • “AdditionalService ” – дополнительная услуга;
  • “AdditionalMeal” – дополнительное питание;
  • “Transfer” – трансфер;
  • “Excursion” – экскурсия;
  • “Charge” – доплата;
  • “Visa” – виза;
  • “NoGoGuarantee” – страховка от невыезда;
name Наименование услуги.
isIncluded Включена ли данная услуга в стоимость текущей конфигурации тура, допустимы значения: 0 – не включена, 1 – включена.
description Описание услуги в произвольной форме.
surcharge Доплата за включение услуги в стоимость тура. Применяется только для услуг, не включенных в стоимость текущей конфигурации тура.
flightCompatibleIds Совместимые перелеты. Идентификаторы услуг перелетов, представленных в секции services, которые могут применяться совместно с текущей услугой перелета. Для перелета туда заполняется id перелетов обратно и наоборот. Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.
flightClass Класс перелета. Может принимать одно из следующих значений:
  • “ECONOM” – эконом;
  • “BUSINESS” – бизнес;

Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.

flightAvailability Наличие билетов, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.
flightPlacesCount Количество оставшихся билетов. Заполняется, если количество билетов мало. Если кол-во билетов известно – заполняется этим числом, иначе значением -1. Применяется только для услуг типа DptTransport и RtnTransport.
flightAirportFrom Аэропорт отправления. Значение должно начинаться с кода IATA, за которым может следовать дополнительная информация, например о терминале (пример: SVO C). Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.
flightAirportTo Аэропорт прибытия. Значение должно начинаться с кода IATA, за которым может следовать дополнительная информация, например о терминале (пример: AYT 1). Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.
flightNum Рейс (например UN 7422). Применяется и является обязательным только для услуг типа DptTransport и RtnTransport.
flightAirline Авиакомпания. Применяется только для услуг типа DptTransport и RtnTransport.
flightStartDateTime Дата и время вылета в формате dd.MM.yyyy HH:mm (пример: 31.12.2015 14:30). Применяется только для услуг типа DptTransport и RtnTransport.
flightEndDateTime Дата и время прибытия в формате dd.MM.yyyy HH:mm (пример: 31.12.2015 14:30). Применяется только для услуг типа DptTransport и RtnTransport.
flightAircraft Информация о воздушном судне. Применяется только для услуг типа DptTransport и RtnTransport.
Источник — «https://wiki.sletat.ru/index.php?title=Sletat_Ru_Provider_API&oldid=1529»