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

1. Схема взаимодействия при получении Материалов

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

  • Пользователь запрашивает у сервиса Яндекс.Авиабилеты варианты перелетов между двумя пунктами на выбранную дату.
  • Сервис Яндекс.Авиабилеты отправляет запрос (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

Буквенное обозначение класса обслуживания. Допустимые значения:

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

Буквенное обозначение класса обслуживания. Допустимые значения:

  • Бизнес-класс — J, C, D, I, Z, BUSINESS.
  • Экономический класс — W, S, Y, B, H, K, L, M, N, Q, T, V, X, E, U, G, O, ECONOMY.
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"

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

Для каждого варианта передаются:

  • цена , в том числе для каждого типа пассажиров, если это применимо,
  • валюта,
  • URL для перенаправления на сайт,
  • количество оставшихся мест,
  • возвратность (по сегменту с самими строгими условиями).

Остальные параметры заполняются для каждого сегмента.

*Поля обязательные к заполнению и наличию в ответе.

Поле Описание Формат
url* URL для перенаправления пользователя на сайт Заказчика. Обработка URL на стороне Заказчика должна происходить в соответствии с п. 3.4 RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax. Строка
price* Цена варианта. Объект (Price)
route_forward* Информация о рейсе «туда». Список объектов (Segment)
route_backward* Информация о рейсе «обратно». Отсутствует, если в запросе не была указана дата обратного вылета. Список объектов (Segment)
value* Цена варианта в данном классе обслуживания. Число
currency* Валюта. Строка
tariff_adult В том числе стоимость для пассажиров старше 12 лет. Число
tariff_child В том числе стоимость для детей от 2 до 12 лет (включительно). Отсутствует, если в запросе не было указано количество детей. Число
tariff_infant В том числе стоимость для детей до 2 лет (включительно). Отсутствует, если в запросе не было указано количество младенцев. Число
refundable Возможность вернуть билет. Логический
seats_remaining Количество оставшихся мест по данной цене Число
Поле Описание Формат
url* URL для перенаправления пользователя на сайт Заказчика. Обработка URL на стороне Заказчика должна происходить в соответствии с п. 3.4 RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax. Строка
price* Цена варианта. Объект (Price)
route_forward* Информация о рейсе «туда». Список объектов (Segment)
route_backward* Информация о рейсе «обратно». Отсутствует, если в запросе не была указана дата обратного вылета. Список объектов (Segment)
value* Цена варианта в данном классе обслуживания. Число
currency* Валюта. Строка
tariff_adult В том числе стоимость для пассажиров старше 12 лет. Число
tariff_child В том числе стоимость для детей от 2 до 12 лет (включительно). Отсутствует, если в запросе не было указано количество детей. Число
tariff_infant В том числе стоимость для детей до 2 лет (включительно). Отсутствует, если в запросе не было указано количество младенцев. Число
refundable Возможность вернуть билет. Логический
seats_remaining Количество оставшихся мест по данной цене Число

 

Segment
flight_number* Номер рейса. Строка
marketing_carrier* Код авиакомпании, которая продает билет. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
operating_carrier* Перевозчик, выполняющий перевозку. Строка
operating_flight_number* Номер рейса оперирующего перевозчика. Строка
validating_carrier Код перевозчика, выписывающего билет. Строка
fare_family Название семейства тарифов. Строка
carrier_name Название авиакомпании. Строка
departure_airport_code* Код аэропорта вылета. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
arrival_airport_code* Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
departure_datetime* Дата и время отправления (местные). Строка
arrival_datetime* Дата и время прибытия (местные). Строка
fare_code* Код тарифа. Строка
class* Обозначение класса обслуживания. Строка
charter* Признак чартерного тарифа. Логический
technical_stop* Техническая остановка Логический
selfconnect* Признак выписки отдельных билетов для рейсов в перелете. Логический
luggage* Включен ли провоз сдаваемого багажа в стоимость билета.Объект, включающий поля с информацией о багаже. Объект (Baggage)
hand_luggage* Объект, включающий поля с информацией о допустимых размерах ручной клади. Объект (Baggage)
Segment
flight_number* Номер рейса. Строка
marketing_carrier* Код авиакомпании, которая продает билет. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
operating_carrier* Перевозчик, выполняющий перевозку. Строка
operating_flight_number* Номер рейса оперирующего перевозчика. Строка
validating_carrier Код перевозчика, выписывающего билет. Строка
fare_family Название семейства тарифов. Строка
carrier_name Название авиакомпании. Строка
departure_airport_code* Код аэропорта вылета. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
arrival_airport_code* Код аэропорта прибытия. Указывается код IATA или код в системе «Сирена-Трэвел». Строка
departure_datetime* Дата и время отправления (местные). Строка
arrival_datetime* Дата и время прибытия (местные). Строка
fare_code* Код тарифа. Строка
class* Обозначение класса обслуживания. Строка
charter* Признак чартерного тарифа. Логический
technical_stop* Техническая остановка Логический
selfconnect* Признак выписки отдельных билетов для рейсов в перелете. Логический
luggage* Включен ли провоз сдаваемого багажа в стоимость билета.Объект, включающий поля с информацией о багаже. Объект (Baggage)
hand_luggage* Объект, включающий поля с информацией о допустимых размерах ручной клади. Объект (Baggage)

 

Baggage
included* Наличие возможности без дополнительной оплаты провезти сдаваемый багаж. Логический
pieces* Число мест багажа. Число
weight* Вес багажа. Число
units* Единицы изменения веса. Строка
dimensions Объект, включающий поля с информацией о допустимых размерах багажа. Объект (Dimensions)
Baggage
included* Наличие возможности без дополнительной оплаты провезти сдаваемый багаж. Логический
pieces* Число мест багажа. Число
weight* Вес багажа. Число
units* Единицы изменения веса. Строка
dimensions Объект, включающий поля с информацией о допустимых размерах багажа. Объект (Dimensions)

 

Dimensions
length Длина. Число
width Ширина. Число
height Высота. Число
sum Сумма длины, ширины и высоты. Число
Dimensions
length Длина. Число
width Ширина. Число
height Высота. Число
sum Сумма длины, ширины и высоты. Число

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

Пример ответа
{
    "variant": [
        {
            "url": "https://api.aviapartner.ru/redirect?key=gdfkj435lkfg",
            "price": {
                "value": 123.45,
                "currency": "RUB",
                "tariff_adult": 80.00,
                "tariff_child": 40.00,
                "tariff_infant": 3.45,
                "refundable": false,
                "seats_remaining": 9
            },
            "route_forward": [
                {
                    "flight_number": "BL 123",
                    "carrier_name": "Jetstar Pacific AirLines",
                    "marketing_carrier": "BL",
                    "operating_flight_number": "OH 123",
                    "operating_carrier": "OH",
                    "validating_carrier": 'OH',
                    "departure_airport_code": "DME",
                    "arrival_airport_code": "SVO",
                    "departure_datetime": "2011-04-01 18:12",
                    "arrival_datetime": "2011-04-01 21:20",
                    "fare_code": "WFLOWCS",
                    "fare_family": "FLEX ECONOMY",
                    "class": "E",
                    "charter": false,
                    "selfconnect": false,
                    "technical_stop": false,
                    "luggage": {
                        "included": true,
                        "pieces": 1,
                        "weight": 20,
                        "units": "kg",
                        "dimensions": {
                            "length": 110,
                            "width": 90,
                            "height": 50,
                            "sum": 213
                        }
                    },
                    "hand_luggage": {
                        "included": true,
                        "pieces": 1,
                        "weight": 7,
                        "units": "kg",
                        "dimensions": {
                            "length": 55,
                            "width": 35,
                            "height": 20
                        }
                    }
                },
                {...}
            ],
            "route_backward": [
                {...}
            ]
        },
        {...}
    ]
}

4. Предложения, которые будут получены после 120 секунды с начала опроса, не будут сохранены в кэше Яндекс.Авиабилетов и при повторном поиске будут запрошены снова.

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

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

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

8. Отчет о количестве и общей стоимости приобретенных Пользователями авиабилетов в результате их перехода с веб-страниц сервиса Яндекс.Авиабилеты, который предоставляется Заказчиком согласно пункту 3.3.9. Договора, должен передаваться в форматах xls/xlsx, либо 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 символов.

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

Обязательные параметры:

[marker] Значение переданного в диплинке get-параметра
[status]

Значение, которое выставляется в зависимости от типа события.

Допустимые значения:

  • paid - заказ оплачен
  • booking - заказ забронирован, но не оплачен
  • cancel - бронь отменена

refunded – оформлен возврат оплаченного заказа
[orderid] Номер заказа или аналог, например PNR
[price] Цена заказа
[currency] Валюта заказа, в ISO4217
[created_at] Дата создания заказа
[changed_at] Дата изменения статуса заказа
[marker] Значение переданного в диплинке get-параметра
[status]

Значение, которое выставляется в зависимости от типа события.

Допустимые значения:

  • paid - заказ оплачен
  • booking - заказ забронирован, но не оплачен
  • cancel - бронь отменена

refunded – оформлен возврат оплаченного заказа
[orderid] Номер заказа или аналог, например PNR
[price] Цена заказа
[currency] Валюта заказа, в ISO4217
[created_at] Дата создания заказа
[changed_at] Дата изменения статуса заказа

Дополнительные параметры:

[type] Типа перелета: возможные параметры OW или RT.
[from] Пункт отправления
[to] Пункт назначения
[pax] Количество взрослых пассажиров в заказе
[type] Типа перелета: возможные параметры OW или RT.
[from] Пункт отправления
[to] Пункт назначения
[pax] Количество взрослых пассажиров в заказе
Отчет должен быть предоставлен в одном из следующих форматов:
  • Через API. Детали реализации согласуются с Яндекс.Авиабилетами по электронной почте.
  • o Файл в формате XML/XLS/CSV/JSON, выложенный в закрытый раздел сайта партнера, который автоматически обновляется не реже, чем раз в час и содержит данные за последние 62 дня.

2. Схема взаимодействия при переходе к продаже

Переход с сервиса Яндекс.Авиабилеты на веб-сайт Заказчика осуществляется следующим образом:

1. Пользователь выбирает предложение и нажимает на ссылку (стоимость авиационного билета, указанную в валюте, переданной Заказчиком), на сервисе Яндекс. Авиабилеты.

2. Пользователь перенаправляется на веб-сайт Заказчика по адресу, полученному в ответе в поле url блока variant для данного предложения.

3. Пользователь на веб-сайте Заказчика начинает процесс бронирования:

a. на веб-сайте Заказчика должна осуществляться автоматическая проверка возможности забронировать предложение, которое пользователь выбрал на сервисе Яндекс.Авиабилеты (проверка должна осуществляться перед тем, как пользователь на веб-сайте Заказчика начинает процесс бронирования);

b. если выбранный Пользователем вариант бронирования не доступен, то пользователю должно показываться соответствующее информационное сообщение и должны предлагаться другие варианты, соответствующие параметрам запроса пользователя;

i. Url для перенаправления пользователя на сайт партнера должен сохранять работоспособность согласно логике, описанной в пункте 3.2 в течение 30 часов.

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

  • Стоимость авиационного билета при оплате банковской картой в сети Интернет, отображаемая на странице, должна полностью соответствовать стоимости, предоставленной Заказчиком в Материалах, а также располагаться на видном месте и визуально отделена от других возможных предлагаемых Заказчиком вариантов.
  • В описании выбранного варианта бронирования должна содержаться исчерпывающая информация о применимых к этому билету нормах провоза багажа и ручной клади. Эти данные должны быть доступны на этой же странице и не могут находиться в скрытых по умолчанию блоках.
  • При переходе на сайт партнера с мобильных устройств пользователь также должен видеть полную информацию о перелете. В пределах одного экрана должны быть видны следующие параметры: цена варианта, аэропорты прилета и вылета, информация о багаже и пересадках, длительность перелета и пересадок, информация о чартерности рейса и, при необходимости, предупреждение о том, что в пределах одного варианта будет выписано несколько билетов. Страница должна быть адаптирована под размер экрана мобильного устройства и предоставлять удобный интерфейс бронирования билетов.

Если на перелет будет выписано более одного билета, на странице бронирования необходимо указать следующую информацию:

  • Количество билетов которые будут выписаны при покупке этого варианта;
  • При отмене или задержке одного из рейсов в таком перелёте билеты на другие рейсы могут не подлежать замене;
  • На пересадке багаж должен быть получен самостоятельно и при необходимости зарегистрирован заново.

Надпись должна находиться в пределах видимости, без необходимости дополнительного клика.

d. В течение всего процесса бронирования цена, показанная при переходе с Яндекс.Авиабилетов, должна быть явно выделена, все дополнительные услуги должны быть в явном виде отключены. Также запрещается использовать всплывающие окна, отдельные страницы со списком услуг и аналогичные инструменты, прерывающие процесс бронирования билета.

4. В случае если Пользователь на веб-сайте Заказчика начинает процесс бронирования и по выбранному варианту требуется подтверждение от Заказчика, должны выполняться следующие требования:

  • Для авиационных билетов, требующих ручного подтверждения должен осуществляться автоматический ответ с указанием сроков окончательного подтверждения.
  • Срок окончательного ответа о наличии выбранного предложения и его стоимости должен составлять не более 1 рабочего дня.
  • Пользователь должен быть проинформирован в случае, если предложение не подтверждается.

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

a. если параметры, описанные в настоящем документе, при получении Материалов, отображается на веб-сайте Заказчика не полностью;

b. если веб-сайт Заказчика по адресу, полученному в ответе согласно п. 2. Схемы взаимодействия при переходе к продаже не загружается и выдает сообщения об ошибке;

c. при любых технических и иных проблемах, не позволяющих Пользователю перейти на страницу с подробной информации о выбранном варианте (согласно п.3.3 настоящего документа) и завершить процесс покупки на веб-сайте Заказчика.

В случае обнаружения технических проблем Заказчик обязан немедленно известить представителей сервиса Яндекс.Авиабилеты по почте avia-info@yandex-team.ru. При поступлении запроса от Яндекс.Авиабилетов Заказчик обязуется в течение трех часов ответить на обращение и в кратчайшие сроки предоставить всю техническую информацию, необходимую для диагностики и решения проблем.

Далее процесс покупки должен продолжаться согласно технологии, принятой на веб-сайте Заказчика.

Дата публикации 01.10.2021 г.

Дата вступления в силу: 01.10.2021 г.

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/06102020

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/03062019

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/26102018

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/21082018

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/24072018

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/22062018

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/21072017

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/01032017

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/11112016

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/06102016

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/25072016

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/05042016

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/25012016

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/15122015

Предыдущая версия документа: https://yandex.ru/legal/airplane_timetable_requirements/25052015