Мастер-Тур(15):API для отдачи цен в поисковые системы

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

Версия статьи от 11-08-2016.

Поддерживаемые версии ПК «Мастер-Тур»:
Начиная с 15 версии


Введение

Данный web-сервис разработан для отдачи цен во внешние поисковые системы и выполняет следующие задачи:

  • выгружает справочники (города вылета, страны, курорты, отели и т.д.)
  • осуществляет поиск цен с указанныеми параметрами
  • актуализирует выбранный вариант тура по его идентификатору

Выдача результатов осуществляется в формате JSON

Установка

Для работы с web-сервисом необходимо установить службу поиска.
После установки web-сервис будет доступен по адресу http://значение настройки "serviceAddress" в TourSearchOwin/searchApi (пример: http://localhost:9000/TourSearchOwin/searchApi)

Загрузка справочников

Выгрузка списка стран (GetCountries)

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

  • Формат запроса:
    •  ?action=GetCountries
  • Принимаемые параметры:
    • id – идентификатор страны (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор страны
    • name – название страны (рус/анг)
Пример

Вызов метода GetCountries

http://localhost:9000/TourSearchOwin/searchApi?action=GetCountries

Возвращаемый результат метода GetCountries (в формате JSON)

{
   "version": "1.0",
   "countries":    [
            {
         "id": 97,
         "name": "Тунис"
      },            
            {
         "id": 90,
         "name": "Австрия"
      },
            {
         "id": 30,
         "name": "Франция"
      }            
   ]
}


Выгрузка списка городов вылета (GetDepartCities)

Метод производит выгрузку всех доступных городов вылета, а также содержит данные о том, какие направления доступны из каждого города вылета.

  • Формат запроса:
    •  ?action=GetDepartCities
  • Принимаемые параметры:
    • id – идентификатор города вылета (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор города
    • name – название города (рус/анг)
    • countriesTo – идентификаторы стран, которые присутствуют в данном городе вылета
Пример

Вызов метода GetDepartCities

http://localhost:9000/TourSearchOwin/searchApi?action=GetDepartCities

Возвращаемый результат метода GetDepartCities (в формате JSON)

{
   "version": "1.0",
   "departCities":    [
            {
         "id": -1,
         "name": "Не указан",
         "countriesTo":          [
            97,
            90
         ]
      },
            {
         "id": 1,
         "name": "Москва",
         "countriesTo":          [
            90,
            30
         ]
      }
   ]
}


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

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

  • Формат запроса:
    •  ?action=GetResorts
  • Принимаемые параметры:
    • id – идентификатор курорта (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор курорта
    • name – название курорта (рус/анг)
    • countryId – идентификатор страны, в котором расположен курорт
Пример

Вызов метода GetResorts

http://localhost:9000/TourSearchOwin/searchApi?action=GetResorts

Возвращаемый результат метода GetResorts (в формате JSON)

{
   "version": "1.0",
   "countries":    [
            {
         "id": 1,
         "name": "Каринтия",
         "countryId": 90
      },           
            {
         "id": 42,
         "name": "Хаммамед",
         "countryId": 97
      },
            {
         "id": 40,
         "name": "Сусс",
         "countryId": 97
      }           
   ]
}


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

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

  • Формат запроса:
    •  ?action=GetHotelCategories
  • Принимаемые параметры:
    • id – идентификатор категории отеля (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор категории отеля
    • name – название категории отеля
Пример

Вызов метода GetHotelCategories

http://localhost:9000/TourSearchOwin/searchApi?action=GetHotelCategories

Возвращаемый результат метода GetHotelCategories (в формате JSON)

{
   "version": "1.0",
   "hotelCategories":    [
            {
         "id": 59,
         "name": "5*"
      },
            {
         "id": 58,
         "name": "4*"
      },
            {
         "id": 57,
         "name": "3*"
      }
   ]
}


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

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

  • Формат запроса:
    •  ?action=GetHotels
  • Принимаемые параметры:
    • id – идентификатор отеля (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор отеля
    • name – название отеля
    • hotelCategoryId – идентификатор категории отеля
    • resortId – идентификатор курорта, в котором расположен отель
Пример

Вызов метода GetHotels

http://localhost:9000/TourSearchOwin/searchApi?action=GetHotels

Возвращаемый результат метода GetHotels (в формате JSON)

{
   "version": "1.0",
   "hotels":    [
            {
         "id": 672,
         "name": "'Opal",
         "hotelCategoryId": 59,
         "resortId": 0
      },
            {
         "id": 106,
         "name": "OPERA LAFAYETTE",
         "hotelCategoryId": 23,
         "resortId": 42
      },
            {
         "id": 683,
         "name": "Altstadt Vienna",
         "hotelCategoryId": 23,
         "resortId": 0
      },
            {
         "id": 702,
         "name": "Albatros",
         "hotelCategoryId": 57,
         "resortId": 0
      },
            {
         "id": 709,
         "name": "Am Brilliantengrund",
         "hotelCategoryId": 23,
         "resortId": 40
      },
            {
         "id": 2362,
         "name": "Gastehaus Franz Riml",
         "hotelCategoryId": 58,
         "resortId": 0
      }            
   ]
}


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

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

  • Формат запроса:
    •  ?action=GetMeals
  • Принимаемые параметры:
    • id – идентификатор вида питания (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор вида питания
    • name – название вида питания
Пример

Вызов метода GetMeals

http://localhost:9000/TourSearchOwin/searchApi?action=GetMeals

Возвращаемый результат метода GetMeals (в формате JSON)

{
   "version": "1.0",
   "meals":    [
            {
         "id": 1,
         "name": "Пансион"
      },
            {
         "id": 2,
         "name": "Полупансион"
      },
            {
         "id": 4,
         "name": "Завтрак буфет"
      },
            {
         "id": 11,
         "name": "Шведский стол"
      }
   ]
}


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

Метод возвращает список используемых валют.

  • Формат запроса:
    •  ?action=GetCurrencies
  • Принимаемые параметры:
    • id – идентификатор валюты (опциональный, если указан, то запрашивается только одна запись)
  • Возвращаемый результат:
    • id – идентификатор валюты
    • name – название валюты
Пример

Вызов метода GetCurrencies

http://localhost:9000/TourSearchOwin/searchApi?action=GetCurrencies

Возвращаемый результат метода GetCurrencies (в формате JSON)

{
   "version": "1.0",
   "currencies":    [
            {
         "id": 1,
         "name": "USD"
      },
            {
         "id": 2,
         "name": "EUR"
      },
            {
         "id": 3,
         "name": "RUR"
      },
            {
         "id": 9,
         "name": "UAH"
      }
   ]
}


Поиск туров (GetTours)

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

  • Формат запроса:
    •  ?action=GetTours&count=int&countryId=int&departCityId=int&dateFrom=date&dateTo=date&adults=int&kids=int&nightsMin=int&nightsMax=int&currencyId=int
  • Принимаемые параметры ( * – обязательный):
    • offerId – уникальный идентификатор ранее найденного предложения. В случае, если данный параметр задан, все остальные параметры не обязательны и не принимаются в расчет, метод возвращает одну запись.
    • count * – максимальное количество предложений в выдаче.
    • countryId * – идентификатор страны.
    • departCityId * – идентификатор города вылета.
    • dateFrom * – начальная дата в диапазоне дат вылета в формате dd.MM.yyyy (пример: 31.12.2016).
    • dateTo * – конечная дата в диапазоне дат вылета в формате dd.MM.yyyy (пример: 31.12.2016).
    • adults * – количество взрослых.
    • kids * – количество детей.
    • kidsAges – количество полных лет каждому ребёнку, передается в виде строки, перечисление через запятую (пример: 3,6).
    • nightsMin * – минимальное количество ночей в туре.
    • nightsMax * – максимальное количество ночей в туре.
    • resorts – идентификаторы курортов, перечисление через запятую.
    • hotelCategories – идентификаторы категорий отелей, перечисление через запятую.
    • hotels – идентификаторы отелей, перечисление через запятую.
    • meals – идентификаторы видов питания, перечисление через запятую.
    • currencyId * – валюта, в которой будут выданы цены, а также валюта для входящих параметров priceMin и priceMax (если они есть).
    • priceMin – Цена тура от.
    • priceMax – Цена тура до.
    • hotelIsNotInStop – при значении 1 в результатах не должно быть отелей в стопе (отели со статусом «под запрос» допустимы). При значении 0 в результат должны попадать как отели в стопе, так и отели с наличием мест и с местами по запросу.
    • ticketsIncluded – при значении 1 в результатах должны быть только туры с включенной стоимостью перелета («только отель» недопустимы). При значении 0 в результат должны попадать как туры без перелета, так и туры с перелетом.
    • hasTickets – при значении 1 в результатах должны быть туры только с реальным наличием билетов в перелете (не должно быть туров со стопом на перелете, перелеты со статусом «под запрос» недопустимы). При значении 0 в результат должны попадать как туры без билетов на рейс, так и туры с наличием билетов и с билетами по запросу.
  • Возвращаемый результат ( * – обязательный):
    • offerId * – уникальный идентификатор предложения, по которому в дальнейшем можно провести актуализацию тура или бронирование.
    • tourName * – название программы тура.
    • hotelId * – идентификатор отеля.
    • hotelUrl – ссылка на страницу с описанием отеля.
    • resortId * – идентификатор курорта, в котором расположен отель.
    • hotelCategoryId * – идентификатор категории отеля.
    • mealId * – идентификатор вида питания.
    • htPlaceName * – название размещения в номере (примеры: DBL, TRP, 2 ADL + 1 CH (2-12), 2 ADL + INF).
    • roomTypeName – название типа номера (примеры: standard, deluxe, family, deluxe super ocean view).
    • tourDate * – дата начала тура в формате dd.MM.yyyy (пример: 31.12.2016).
    • tourEndDate – дата окончания тура (дата прилета) в формате dd.MM.yyyy (пример: 31.12.2016).
    • nights * – количество ночей в туре.
    • price * – цена тура в валюте, которая была указана во входном параметре currencyId.
    • hotelIsInStop * – наличие мест в отеле, допустимы значения: 0 – есть места, 1 – нет мест, 2 – запрос.
    • ticketsIncluded * – включена ли стоимость билетов в стоимость тура, допустимы значения: 0 – не включена (тур только отель), 1 – включена (пакетный тур).
    • hasEconomTicketsDpt * – наличие билетов эконом класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано. Группы перелетов задаются в настройке flightTariffGroups.
    • hasEconomTicketsRtn * – наличие обратных билетов эконом класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано. Группы перелетов задаются в настройке flightTariffGroups.
    • hasBusinessTicketsDpt * – наличие билетов бизнес класса на место отдыха, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано. Группы перелетов задаются в настройке flightTariffGroups.
    • hasBusinessTicketsRtn * – наличие обратных билетов бизнес класса, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. При значении атрибута ticketsIncluded = 0 значение данного параметра будет проигнорировано. Группы перелетов задаются в настройке flightTariffGroups.
    • tourUrl * – ссылка на корзину (при переходе по которой можно забронировать тур).
    • spoUrl – ссылка на описание тура (указывается в программе тура).
    • fewPlacesInHotel – параметр не обрабатывается, всегда возвращается -1.
    • fewTicketsDptY – параметр не обрабатывается, всегда возвращается -1.
    • fewTicketsRtnY – параметр не обрабатывается, всегда возвращается -1.
    • fewTicketsDptB – параметр не обрабатывается, всегда возвращается -1.
    • fewTicketsRtnB – параметр не обрабатывается, всегда возвращается -1.
    • flags – параметр не обрабатывается, всегда возвращается 0.
    • description – условия бронирования тура (указывается в программе тура).
    • receivingParty – параметр не обрабатывается.
    • earlyBookingValidTill – параметр не обрабатывается.
Пример

Вызов метода GetTours

http://localhost:9000/TourSearchOwin/searchApi?action=GetTours&count=20&countryId=22&departCityId=1
&dateFrom=10.08.2016&dateTo=10.08.2016&adults=2&kids=0&nightsMin=7&nightsMax=7&currencyId=1

Возвращаемый результат метода GetTours (в формате JSON)

{
   "version": "1.0",
   "tours": [   {
      "offerId": 256,
      "tourName": "Тур в Португалии_авиа",
      "hotelId": 3239,
      "hotelUrl": "www.tophotels.com/NapHotel",
      "resortId": 45,
      "hotelCategoryId": 64,
      "mealId": 38,
      "htPlaceName": "2 Adult",
      "roomTypeName": "Sea View",
      "tourDate": "10.08.2016",
      "tourEndDate": "17.08.2016",
      "nights": 7,
      "price": 1036,
      "hotelIsInStop": 2,
      "ticketsIncluded": 1,
      "hasEconomTicketsDpt": 1,
      "hasEconomTicketsRtn": 2,
      "hasBusinessTicketsDpt": 0,
      "hasBusinessTicketsRtn": 1,
      "tourUrl": "http://localhost/TourSearchClient/Basket?departureCities=1&destination=1_22&tour=161&date=10.08.16&duration=8&hotelScheme=1_7_3239_221_10760
&adultCount=2&hotelQuota=7&aviaQuota=7&serviceDescriptions=2_1_586_89_1_22_33_221_10760_1_0,
1_3_3239_1148_38_22_33_221_10760_1_7,3_1_587_89_33_460_1_221_10760_8_0&currency=$",
      "spoUrl": "wiki.megatec.ru",
      "fewPlacesInHotel": -1,
      "fewTicketsDptY": -1,
      "fewTicketsRtnY": -1,
      "fewTicketsDptB": -1,
      "fewTicketsRtnB": -1,
      "flags": 0,
      "description": "При раннем бронировании предоставляется скидка 20%",
      "receivingParty": "",
      "earlyBookingValidTill": ""
   }]
}


Актуализация тура (ActualizeTour)

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

  • Формат запроса:
    •  ?action=ActualizeTour
  • Принимаемые параметры ( * – обязательный):
    • offerId * – уникальный идентификатор ранее найденного предложения.
    • currencyId * – валюта, в которой рассчитывается цена и доплаты.
  • Возвращаемый результат ( * – обязательный):
    • price * – актуализированная цена тура в валюте, которая была указана во входном параметре currencyId.
    • ticketsIsIncluded * – включена ли стоимость билетов в стоимость тура, допустимы значения: 0 – не включена (тур только отель), 1 – включена (пакетный тур).
    • hotelIsInStop – наличие мест в отеле, допустимы значения: 0 – есть места, 1 – нет мест, 2 – запрос.
    • 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 – ссылка на корзину (при переходе по которой можно забронировать тур).
    • services – список услуг, которые могут быть в туре
      • id * – идентификатор услуги, уникальный в рамках данного предложения.
      • type * – Тип услуги. Может принимать одно из следующих значений:
        • Insurance – страховка
        • DptTransport – перелет туда
        • RtnTransport – перелет обратно
        • MidDptTransport – промежуточный перелет туда (при пересадке)
        • MidRtnTransport – промежуточный перелет обратно (при пересадке)
        • AdditionalService – дополнительная услуга
        • Transfer – трансфер
        • Excursion – экскурсия
        • Visa – виза
      • name * – наименование услуги
      • isIncluded * – включена ли данная услуга в стоимость текущей конфигурации тура, допустимы значения: 0 – не включена, 1 – включена.
      • description – описание услуги в произвольной форме (не обрабатывается).
      • surcharge – стоимость услуги.
      • flightCompatibleIds – совместимые перелеты. Идентификаторы услуг перелетов, представленных в секции services, которые могут применяться совместно с текущей услугой перелета. Для перелета туда заполняется id перелетов обратно и наоборот. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightClass – класс перелета. Группы перелетов для классов задаются в настройке flightTariffGroups. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport. Может принимать одно из следующих значений:
        • ECONOM – эконом
        • BUSINESS – бизнес
      • flightAvailability – наличие билетов, допустимы значения: 0 – нет мест, 1 есть места, 2 – запрос. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightPlacesCount – параметр не обрабатывается, всегда возвращается -1.
      • flightAirportFrom – код аэропорта вылета. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightAirportTo – код аэропорта прилета. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightNum – номер рейса. Применяется и является обязательным только для услуг типа: DptTransport, RtnTransport.
      • flightAirline – код авиакомпании. Применяется только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightStartDateTime – Дата и время вылета в формате dd.MM.yyyy HH:mm (пример: 31.12.2016 14:30). Применяется только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightEndDateTime – Дата и время прилета в формате dd.MM.yyyy HH:mm (пример: 31.12.2016 14:30). Применяется только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
      • flightAircraft – тип самолета. Применяется только для услуг типа: DptTransport, RtnTransport, MidDptTransport, MidRtnTransport.
Пример

Вызов метода ActualizeTour

http://localhost:9000/TourSearchOwin/searchApi?action=ActualizeTour&offerID=256&currencyId=1

Возвращаемый результат метода ActualizeTour (в формате JSON)

{
   "version": "1.0",
   "actualizedTour":    {
      "price": 1036,
      "ticketsIsIncluded": 1,
      "hotelIsInStop": 2,
      "hasEconomTicketsDpt": 1,
      "hasEconomTicketsRtn": 2,
      "hasBusinessTicketsDpt": 0,
      "hasBusinessTicketsRtn": 1,
      "fewPlacesInHotel": -1,
      "fewEconomTicketsDpt": -1,
      "fewEconomTicketsRtn": -1,
      "fewBusinessTicketsDpt": -1,
      "fewBusinessTicketsRtn": -1,
      "tourUrl": "http://localhost/TourSearchClient/Basket?departureCities=1&destination=1_22&tour=161&date=10.08.16&duration=8&hotelScheme=1_7_3239_221_10760
&adultCount=2&hotelQuota=7&aviaQuota=7&serviceDescriptions=2_1_586_89_1_22_33_221_10760_1_0,
1_3_3239_1148_38_22_33_221_10760_1_7,3_1_587_89_33_460_1_221_10760_8_0&currency=$",
      "services":       [
                  {
            "id": 0,
            "type": "DptTransport",
            "name": "А_П::Москва/Лиссабон/3G001, DME-LUS, 11:00-13:00/Y Экономический класс",
            "isIncluded": 1,
            "description": "",
            "surcharge": 100,
            "flightCompatibleIds": "2",
            "flightClass": "ECONOM",
            "flightAvailability": 1,
            "flightPlacesCount": -1,
            "flightAirportFrom": "DME",
            "flightAirportTo": "LUS",
            "flightNum": "001",
            "flightAirline": "3G",
            "flightStartDateTime": "10.08.2016 11:00",
            "flightEndDateTime": "10.08.2016 13:00",
            "flightAircraft": "310"
         },
                  {
            "id": 1,
            "type": "",
            "name": "HOTEL::Лиссабон/Отель в Лиссабоне-4,7 ночей/Double(Sea View),2 Adult/TT NewP",
            "isIncluded": 1,
            "description": "",
            "surcharge": 836,
            "flightCompatibleIds": null,
            "flightClass": null,
            "flightAvailability": -1,
            "flightPlacesCount": -1,
            "flightAirportFrom": null,
            "flightAirportTo": null,
            "flightNum": null,
            "flightAirline": null,
            "flightStartDateTime": null,
            "flightEndDateTime": null,
            "flightAircraft": null
         },
                  {
            "id": 2,
            "type": "RtnTransport",
            "name": "А_П::Лиссабон/Москва/3G002, LUS-DME, 20:00-21:00/Y Экономический класс",
            "isIncluded": 1,
            "description": "",
            "surcharge": 100,
            "flightCompatibleIds": "0",
            "flightClass": "ECONOM",
            "flightAvailability": 2,
            "flightPlacesCount": -1,
            "flightAirportFrom": "LUS",
            "flightAirportTo": "DME",
            "flightNum": "002",
            "flightAirline": "3G",
            "flightStartDateTime": "17.08.2016 20:00",
            "flightEndDateTime": "17.08.2016 21:00",
            "flightAircraft": "310"
         }
      ]
   }
}