Технические требования к организации взаимодействия веб-систем Яндекса и Заказчика для предоставления Заказчиком Материалов

Это старая версия документа, которая прекратила свое действие 22.06.2018 г. Действующая версия размещена по адресу: https://yandex.ru/legal/airplane_timetable_requirements

Общая схема работы:

1. Пользователь запрашивает у сервиса Яндекс.Авиабилеты варианты перелетов между двумя пунктами на выбранную дату.

2. Сервис Яндекс.Авиабилеты отправляет запрос (GET или POST) к веб-сайту Заказчика в соответствии с форматом:

   https://api.aviapartner.ru/search?
    [departure = <IATA либо Сирена-код пункта отправления>]
     &[arrival = <IATA либо Сирена-код пункта прибытия>]
     &[date_forward = <дата вылета «туда»>]
     &[date_backward = <дата вылета «обратно»>]
     &[class = <класс обслуживания>]
     &[adults = <количество взрослых пассажиров>]
     &[children = <количество детей>]
     &[infants = <количество младенцев>]

   departure	Код аэропорта отправления. Указывается код IATA или код в системе «Сирена-Трэвел».
   arrival	Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел».
   date_forward	Дата прямого вылета в формате YYYY-MM-DD.
   date_backward	Дата обратного вылета в формате YYYY-MM-DD. Может отсутствовать.
   class	Буквенное обозначение класса обслуживания. Допустимые значения: Первый класс — R, F, P, A. Бизнес-класс — J, C, D, I, Z. Экономический класс — W, S, Y, B, H, K, L, M, N, Q, T, V, X, E, U, G, O.
   adults	Количество пассажиров старше 12 лет.
   children	Количество пассажиров от 2 до 12 лет (включительно). Может отсутствовать.
   infants	Количество детей до 2 лет (включительно). Может отсутствовать.

   departure	Код аэропорта отправления. Указывается код IATA или код в системе «Сирена-Трэвел».
   arrival	Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел».
   date_forward	Дата прямого вылета в формате YYYY-MM-DD.
   date_backward	Дата обратного вылета в формате YYYY-MM-DD. Может отсутствовать.
   class	Буквенное обозначение класса обслуживания. Допустимые значения: Первый класс — R, F, P, A. Бизнес-класс — J, C, D, I, Z. Экономический класс — W, S, Y, B, H, K, L, M, N, Q, T, V, X, E, U, G, O.
   adults	Количество пассажиров старше 12 лет.
   children	Количество пассажиров от 2 до 12 лет (включительно). Может отсутствовать.
   infants	Количество детей до 2 лет (включительно). Может отсутствовать.

   Пример запроса

   https://api.aviapartner.ru/search?departure=MOW&arrival=AGP&date_forward=2017-03-19&date_backward=2017-03-26&class=E&adults=2&children=0&infants=1

3. Веб-сайт Заказчика возвращает информацию о доступных предложениях в формате XML. В ответе содержится один или несколько объектов variant, в каждом указаны сведения о перелете: ссылка для покупки билета на веб-сайте Заказчика и информация о рейсах «туда» (объект route_forward) и «обратно» (объект route_backward). Перелет может состоять из нескольких рейсов.

   Объекты route_forward и route_backward включают объект fare, в котором описывается тариф и нормы провоза багажа.

   Поле	Описание	Формат
   url	URL для перенаправления пользователя на сайт Заказчика. Обработка URL на стороне Заказчика должна происходить в соответствии с п. 3.4 RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax.	Строка
   route_forward	Информация о рейсе «туда».	Объект
   route_backward	Информация о рейсе «обратно». Отсутствует, если в запросе не была указана дата обратного вылета.	Объект
   route_code	Номер рейса.	Строка
   company_code	Код авиакомпании. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   company_name	Название авиакомпании.	Строка
   departure_airport_code	Код аэропорта вылета. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   arrival_airport_code	Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   departure_datetime	Дата и время отправления (местные).	Строка
   arrival_datetime	Дата и время прибытия (местные).	Строка
   route_time	Время в пути в минутах.	Число
   farecode	Код тарифа.	Строка
   tariff_adult	Тариф для пассажиров старше 12 лет.	Число
   tariff_child	Тариф для детей от 2 до 12 лет (включительно). Отсутствует, если в запросе не было указано количество детей.	Число
   tariff_infant	Тариф для детей до 2 лет (включительно). Отсутствует, если в запросе не было указано количество младенцев.	Число
   fare	Информация о тарифе и багаже.	Объект
   value	Минимальная цена в данном классе обслуживания.	Число
   class	Буквенное обозначение класса обслуживания.	Строка
   charter	Признак чартерного тарифа.	Логический
   block	Признак блочного тарифа.	Логический
   selfconnect	Признак выписки отдельных билетов для рейсов в перелете.	Логический
   currency	Валюта.	Строка
   luggage	Включен ли провоз сдаваемого багажа в стоимость билета.	Логический
   pieces_of_luggage	Количество мест багажа, включенное в стоимость.	Число
   luggage_weight	Максимальный вес включенного в стоимость багажа.	Число
   luggage_dimensions	Максимальный размер включенного в стоимость багажа.	Объект
   length	Длина.	Число
   width	Ширина.	Число
   height	Высота.	Число
   sum	Сумма длины, ширины и высоты.	Число

   Поле	Описание	Формат
   url	URL для перенаправления пользователя на сайт Заказчика. Обработка URL на стороне Заказчика должна происходить в соответствии с п. 3.4 RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax.	Строка
   route_forward	Информация о рейсе «туда».	Объект
   route_backward	Информация о рейсе «обратно». Отсутствует, если в запросе не была указана дата обратного вылета.	Объект
   route_code	Номер рейса.	Строка
   company_code	Код авиакомпании. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   company_name	Название авиакомпании.	Строка
   departure_airport_code	Код аэропорта вылета. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   arrival_airport_code	Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел».	Строка
   departure_datetime	Дата и время отправления (местные).	Строка
   arrival_datetime	Дата и время прибытия (местные).	Строка
   route_time	Время в пути в минутах.	Число
   farecode	Код тарифа.	Строка
   tariff_adult	Тариф для пассажиров старше 12 лет.	Число
   tariff_child	Тариф для детей от 2 до 12 лет (включительно). Отсутствует, если в запросе не было указано количество детей.	Число
   tariff_infant	Тариф для детей до 2 лет (включительно). Отсутствует, если в запросе не было указано количество младенцев.	Число
   fare	Информация о тарифе и багаже.	Объект
   value	Минимальная цена в данном классе обслуживания.	Число
   class	Буквенное обозначение класса обслуживания.	Строка
   charter	Признак чартерного тарифа.	Логический
   block	Признак блочного тарифа.	Логический
   selfconnect	Признак выписки отдельных билетов для рейсов в перелете.	Логический
   currency	Валюта.	Строка
   luggage	Включен ли провоз сдаваемого багажа в стоимость билета.	Логический
   pieces_of_luggage	Количество мест багажа, включенное в стоимость.	Число
   luggage_weight	Максимальный вес включенного в стоимость багажа.	Число
   luggage_dimensions	Максимальный размер включенного в стоимость багажа.	Объект
   length	Длина.	Число
   width	Ширина.	Число
   height	Высота.	Число
   sum	Сумма длины, ширины и высоты.	Число

   Вся указанная выше информация о перелете обязательно должна быть включена в ответ (в соответствии с типами пассажиров в запросе).

   Пример ответа

   { 
       "variant" : [
           {        
               "url": "https://api.aviapartner.ru/redirect?key=gdfkj435lkfg",
               {
                   "route_forward": 
                   [
                     {
                       "route_code": "0123АБ",
                       "company_code": "BL",
                       "company_name": "Blah-air",
                       "departure_airport_code": "DME",
                       "arrival_airport_code": "SVO",
                       "departure_datetime": "2011-04-01 18:12",
                       "arrival_datetime": "2011-04-01 21:20",
                       "route_time = "123",
                       "farecode": "WFLOWCS",
                       "tariff_adult": "80.00",
                       "tariff_child": "60.00",
                       "tariff_infant": "3.45",
                       "fare":
                       {
                           "value: "123.45",
                           "class: "E",
                           "charter: "false",
                           "block": "false",
                           "selfconnect": "false",
                           "currency": "RUB",
                           "luggage: "true", 
                           "pieces_of_luggage: 1,
                           "luggage_weight": 20, 
                           "luggage_dimensions:
                           {
                               "length: 90,
                               "width: 28,
                               "height: 40,
                               "sum: 158
                           }
                       }
                     },
                     {...},
                     {...}
                   ]              
               },
               {
                   "route_backward": [{...}, {...}, {...}]
               },
               {  
               }
           },
           {...},
           {...},
           ...
       ]
   }

4. Предложения Заказчика, поступившие после 20 секунд ожидания либо после того как пользователь вручную прервал процесс ожидания, не отображаются в списке вариантов перелетов для этого пользователя. Предложения, которые поступили в период от 20 секунд до 2 минут, сохраняются в кэше и при повторном поиске отображаются без нового запроса к Заказчику (пока не истечет время актуальности кэша).

5. Заказчики, использующие систему «Сирена-Трэвел», должны отвечать на запросы с внутренними кодами, которые используются в этой системе.

6. Заказчик обязуется использовать защищенный протокол передачи данных https на своем сайте при переходе с сервиса Яндекс.Авиабилеты.

7. Заказчик обязуется информировать Яндекс о переходе на новый протокол предоставления информации не менее чем за тридцать календарных дней до начала перехода.

8. Отчет о количестве и общей стоимости приобретенных Пользователями авиабилетов в результате их перехода с веб-страниц сервиса Яндекс.Авиабилеты, который предоставляется Заказчиком согласно пункту 3.3.9. Договора, должен передаваться в форматах xsl/xslx, либо csv.

9. Для ограничения количества запросов можно задать допустимые региональные направления. Для этого на указанный в договоре адрес пришлите ссылку на csv-файл с парами кодов городов/аэропортов (по одной в каждой строке с разделителем «;»). Допускается использовать как коды IATA, так и коды системы «Сирена-Трэвел». Каждая пара разрешает опрос в обе стороны.

   Файл должен быть сохранен в кодировке UTF-8.

   Пример задания допустимых направлений

   • ATH;CMB
   • ATH;DXB
   • GBB;GOI
   • GPA;HAV
   • HER;KLX
   • KVD;LCA
   • LIS;LLK
   • LWN;MAD
   • MLE;NAP
   • СХТ;RHO
   • СХТ;СПТ

   Скачать пример файла

   Данные выгружаются раз в сутки.

10. В url страницы партнера при переходе с сервиса Авиабилеты Яндекс передает get-параметр marker, который представляет из себя уникальную строку длиной до 200 символов.

    При совершении бронирования/покупки/отмены билета необходимо делать запрос https://avia.yandex.ru/order/pixel/[marker]/[status] к сервису Яндекс.Авиабилеты, где:

    marker	Значение переданного Яндекс.Авиабилетами get-параметра при переходе к партнеру
    status	Значение, которое выставляется в зависимости от типа события. Допустимые значения: Booking Paid Cancel

    marker	Значение переданного Яндекс.Авиабилетами get-параметра при переходе к партнеру
    status	Значение, которое выставляется в зависимости от типа события. Допустимые значения: Booking Paid Cancel

    Возможные способы запроса к Яндекс.Авиабилетам:

    • 1. CORS запрос из javascript в момент завершения события;
    • 2. Вставка html-кода на страницу после покупки пользователя <img src="https://avia.yandex.ru/order/pixel/[marker]/[status]">;
    • 3. Запрос с сервера партнера после завершения события.

    Любой из этих запросов передаст Яндекс.Авиабилетам информацию о том, что пользователь с переданным параметром marker забронировал, купил или отменил билет на сайте партнера.