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

Это старая версия документа, которая прекратила свое действие 03.06.2019 г. Действующая версия размещена по адресу: 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 символов. Для передачи Яндексу информации о бронировании необходимо использовать один из следующих вариантов:

    1. При совершении бронирования/покупки/отмены билета необходимо делать запрос 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 забронировал, купил или отменил билет на сайте партнера.

    2. Партнер обязан предоставить отчет, который содержит следующую информацию о бронированиях, совершенных пользователями после перехода с сервисов Яндекса:

    • id заказа (PNR, любой другой уникальный идентификатор бронирования);
    • Дата создания заказа;
    • Статус заказа на момент формирования отчета (booked, paid, cancelled);
    • Стоимость заказа c указанием валюты;
    • Информация по перелете: откуда, куда, тип билета (туда или туда-обратно);
    • Маркер.

    Отчет должен быть предоставлен в одном из следующих форматов:

    • Файл в формате XML/XLS/CSV/JSON, выложенный в закрытый раздел сайта партнера, который автоматически обновляется не реже, чем раз в час и содержит данные за последние 62 дня.
    • Через API. Детали реализации согласуются с Яндекс.Авиабилетами по электронной почте.