Technical Requirements for Interaction Between Yandex and Customer Online Systems for the Provision of Materials by the Customer

This document is an English translation of Technical Requirements for the Communication between Yandex's and the Customer’s Web Systems for the Purposes of Providing Materials by the Customer. In case of conflict between the Russian version of Technical Requirements for the Communication between Yandex's and the Customer’s Web Systems for the Purpose of Providing Materials by the Customer and this translation the Russian version shall prevail. The Russian version of Technical Requirements for the Communication between Yandex's and the Customer’s Web Systems for the Purpose of Providing Materials by the Customer can be found here: https://yandex.ru/legal/airplane_timetable_requirements/?lang=ru.

1. Interaction When Materials are Received

General scheme:

  1. The User requests flight options between two points for the chosen date from Yandex.Flights.

  2. Yandex.Flights sends a request (GET or POST) to the Customer's website in accordance with the format:

    https://api.aviapartner.ru/search? [departure = <IATA or Sirena code of the
                point of departure>] &[arrival = <IATA or Sirena code of the point of
                arrival>] &[date_forward = <date of departure “to”>]
                &[date_backward = <date of departure “from”>] &[class = <class of
                service>] &[adults = <number of adult passengers>] &[children =
                <number of children>] &[infants = <number of infants>]
    departureDeparture airport code. IATA or Sirena-Travel code.
    arrivalArrival airport code. IATA or Sirena-Travel code.
    date_forwardOutbound flight date: YYYY-MM-DD.
    date_backwardReturn flight date: YYYY-MM-DD. May be omitted.
    class

    Letter symbol of service class. Acceptable values:

    • First class — R, F, P, A.
    • Business class — J, C, D, I, Z.
    • Economy class — W, S, Y, B, H, K, L, M, N, Q, T, V, X, E, U, G, O.
    adultsNumber of passengers over the age of 12.
    childrenNumber of passengers aged 2 to 12 (inclusive). May be omitted.
    infantsNumber of children under the age of 2 (inclusive). May be omitted.
    Request example
    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. The Customer's website returns XML with information on available offers. The response contains one or more variant, objects, each specifying trip details: a link to buy a ticket on the Customer's website and information on flights “to” (route_forward object) and “from” (route_backward object). A trip can include multiple flights.

    The route_forward and route_backward include the fareobject, which describes fares and luggage allowances.

    FieldDescriptionFormat
    urlA URL to redirect the user to the Customer's website. The Customer must process the URL in conformance with clause 3.4 in RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax.String
    route_forwardInformation on the flight “to”.Object
    route_backwardInformation on the flight “from”. Omitted if the request did not specify the date of the return flight.Object
    route_codeFlight number.String
    company_codeAirline code. IATA or Sirena-Travel code.String
    company_nameAirline name.String
    departure_airport_codeDeparture airport code. IATA or Sirena-Travel code.String
    arrival_airport_codeArrival airport code. IATA or Sirena-Travel code.String
    departure_datetimeDeparture date and time (local).String
    arrival_datetimeArrival date and time (local).String
    route_timeTime en-route in minutes.Numeric
    farecodeFare code.String
    tariff_adultFare for passengers over the age of 12.Numeric
    tariff_childFare for passengers aged 2 to 12 (inclusive). Omitted if the request did not specify the number of children.Numeric
    tariff_infantFare for children under the age of 2 (inclusive). Omitted if the request did not specify the number of infants.Numeric
    fareFare and luggage information.Object
    valueMinimum price in this service class.Numeric
    classLetter symbol of service class.String
    charterIndicates charter fare.Boolean
    blockIndicates block fare.Boolean
    selfconnectIndicates separate tickets issued for flights in a trip.Boolean
    currencyCurrency.String
    luggageWhether the transportation of checked luggage is included in the ticket price.Boolean
    pieces_of_luggageNumber of pieces of luggage included in the price.Numeric
    luggage_weightMaximum weight of luggage included in the price.Numeric
    luggage_dimensionsMaximum dimensions of luggage included in the price.Object
    lengthLength.Numeric
    widthWidth.Numeric
    heightHeight.Numeric
    sumTotal of length, width and height.Numeric

    All the above flight information must be included in the response (as per types of passengers in the request).

    Response example
    { "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. The Customer's offers received after 20 seconds of waiting or after the User manually interrupted the waiting are not included in the list of flight options for this user. Offers received after waiting from 20 seconds to 2 minutes are saved in the cache and displayed again if the user repeats the search, without sending another request to the Customer (until the cache expires).

  5. Customers who use the Sirena-Travel system shall respond to requests using the internal codes from this system.

  6. The Customer undertakes to use the HTTPS secure data transfer protocol on its website for redirecting Users from Yandex.Flights.

  7. If the Customer adopts a new information delivery protocol, said Customer undertakes to notify Yandex of the change at least thirty calendar days in advance.

  8. The quantity and total price of air tickets that Users purchased by clicking through from the Yandex.Flights website, which is reported by the Customer as per clause 3.3.9 of the Agreement, shall be provided in XSL/XSLX or CSV format.

  9. A list of acceptable regional routes may be defined in order to limit the number of requests. To do so, send a link to a CSV file with city/airport code pairs to the email address specified in the agreement (one pair per line, using a semicolon “;” to separate the codes). Either IATA codes or Sirena-Travel codes are acceptable. Each pair allows queries in both directions.

    The file shall be UTF-8 encoded.

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

    Download a sample file

    The data are uploaded once a day.

  10. Yandex appends a GET parameter marker, which is a unique string up to 200 symbols long, to the partner page URL when redirecting from Yandex.Flights.

    When booking/purchasing/canceling a ticket, the request https://avia.yandex.ru/order/pixel/[marker]/[status] shall be made to Yandex.Flights, where:

    marker

    is the value of the GET parameter that Yandex.Flights transmitted when redirecting to the partner.

    status

    is a value set depending on the event type. Acceptable values:

    • Booking

    • Paid

    • Cancel

    Possible types of requests to Yandex.Flights:

    • 1. CORS request from JavaScript when the event is completed;
    • 2. HTML code to insert in a page after the user made a purchase <img src="https://avia.yandex.ru/order/pixel/[marker]/[status]">;
    • 3. Request from the partner's server after the event is completed.

    Any of these requests will inform Yandex.Flights that the user with the transmitted marker parameter booked, purchased or canceled an air ticket on the partner's website.

2. Interaction When Sale is Initiated

Redirecting from Yandex.Flights to the Customer's website shall be conducted as follows:

  1. The user selects an offer and clicks on the link (the price of the air ticket provided by the Customer) on the Yandex.Flights service.

  2. The User is redirected to the Customer's website at the address received in the URL field of the variant for this offer in the response.

  3. The user begins the booking process on the Customer’s website:

    1. The offers selected by the user at Yandex.Flights shall be automatically checked for availability on the Customer's website (such check shall be performed before the User starts booking on the Customer’s website);

    2. If an option selected by the User is not available, then the relevant information message shall be displayed to the User, and the User shall be offered other options corresponding to the user’s request parameters;

      1. Deeplink redirection URL has to stay functional as provided in 3.2 for no less than 30 hours.

    3. If the option selected by the User is available, then a page shall be displayed containing detailed information about the selected option: airports and cities of departure and arrival, dates, flight time, number and duration of connections (if any), other information regarding services included in the fare, number and type of passengers, ticket price and fields to enter passenger information for booking purposes. The following requirements shall also be met for the page:

      • If payment is made online using a bank card, the price of the air ticket displayed on the page shall exactly correspond to the price specified by the Customer in the Materials, and it must be displayed prominently and visually separated from other available options offered by the Customer;

      • The description of the option selected shall contain comprehensive information on checked and carry-on baggage allowances applicable to this air ticket. This data shall be available on the same page and cannot be placed in blocks that are hidden by default.

      In case there are several tickets to be issued for one itinerary, the following information should be clearly displayed on the booking page:

      • How many tickets are to be issued;

      • Tickets may not be exchanged if the original flight is missed and/or delayed;

      • Checked luggage should be retrieved and checked in again in the connecting airport.

      This information should be immediately visible on the booking page without any further clicks.

    4. If the Customer offers any additional services to the User on the Customer's website along with air tickets, the Customer undertakes to enable the User to select such additional services on its website independently. All additional services shall be offered before the details of the User’s bank card are entered. No additional services shall be added to the air ticket cost until consent of the User is received.
  4. If the User begins the booking process on the Customer’s website and the selected option requires the Customer’s confirmation, the following requirements shall be met:

    • For air tickets that require manual confirmation, an automatic response shall be given specifying the terms of the final confirmation.

    • The timeframe for the final response on the availability of the selected offer and its cost shall not exceed 1 business day.

    • The User shall be informed if the offer is not confirmed.

  5. The Customer undertakes not to transfer the Materials in response to the request from Yandex.Flights in the following cases:

    1. If the parameters described herein are not fully displayed on the Customer’s website in obtaining the Materials;

    2. If the Customer’s website does not open as specified in the response according to clause 2 of Interaction When Sale is Initiated, and an error message is displayed;

    3. If there are any technical or other issues preventing the User from accessing the page with the selected option details (in accordance with clause 3.3 hereof) and completing the purchase process on the Customer website.

  6. In the event that any technical problems are detected, the Customer shall immediately inform representatives of Yandex.Flights at avia-info@yandex-team.ru. When requested by Yandex.Flights, the Customer undertakes to respond within three hours and promptly provide any and all technical information needed to diagnose and solve the problems.

  7. In that case, the purchase process shall continue in accordance with the technology used on the Customer website.

Date of publication: 24.07.2018 г.

Effective Date: 24.07.2018 г.

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/22062018/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/21072017/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/01032017/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/11112016/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/06102016/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/25072016/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/05042016/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/25012016/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/15122015/

Previous version of the document: https://yandex.ru/legal/airplane_timetable_requirements/25052015/