Skip to content

API EN

Jump to bottom Edit New page
Павел Петров edited this page Oct 14, 2024 · 45 revisions

Requesting price/availability

Request example

curl 'http://example.com/api/search?from=BKK&to=BOM&date1=2017-09-25&date2=2017-10-01&adults=2&children=1&infants=1&cabin=Y&partner=jtrdr&password=pass&locale=en&currency=usd&market=us'

Request parameters

  • from - IATA code of departure city/airport.
  • to - IATA code of arrival city/airport.
  • date1 - YYYY-MM-DD date of departure.
  • date2 - YYYY-MM-DD date of departure for a roundtrip journey. Sould be omitted for oneway searches.
  • adults - "1" if omitted!
  • children - "0" by default.
  • infants - "0" by default.
  • cabin - preferred booking class
    • "Y" - economy
    • "W" - comfort
    • "C" - business
    • "F" - first/premium.
  • partner - partner company identificator. We will send 'aviasales' value.
  • password - password of current partner.
  • locale - User locale (en by default).
  • currency - User currency (usd by default).
  • market - Market where integration launches (us by default).

Response example

<?xml version='1.0' encoding='utf-8' ?>
 <variants>
  <variant>
   <price>2664</price>
   <currency>usd</currency>
   <url>BOOKING_PAGE_DEEPLINK</url>
   <seats>6</seats>
   <commission>0.045</commission>
   <segment>
    <flight>
     <operatingCarrier>UN</operatingCarrier>
     <marketingCarrier>SU</marketingCarrier>
     <number>3</number>
     <departure>BKK</departure>
     <departureDate>2021-09-25</departureDate>
     <departureTime>09:55</departureTime>
     <arrival>BOM</arrival>
     <arrivalDate>2012-09-25</arrivalDate>
     <arrivalTime>11:10</arrivalTime>
     <equipment>735</equipment> 
     <cabin>Y</cabin>
     <baggage>1PC23</baggage>
     <handbags>1PC5</handbags>
     <totalBaggageCount>1</totalBaggageCount>
     <virtualInterline>false</virtualInterline>
     <fareCode>WOW1</fareCode>
     <isBus>false</isBus>
     <isTrain>false</isTrain>
     <technicalStop>
         <airportCode>AER</airportCode>
     </technicalStop>
     <technicalStop>
         <airportCode>AAQ</airportCode>
     </technicalStop>
     <fare>
           <returnBeforeFlight>
               <available>true</available>
               <currency>RUB</currency>
               <penalty>0</penalty> --- return before departure is possible free of charge
           </returnBeforeFlight>
           <returnAfterFlight>
               <available>true</available>
               <currency>RUB</currency>
               <penalty>2940.00</penalty> --- return after departure is possible for a surcharge
           </returnAfterFlight>
           <changeBeforeFlight>
               <available>false</available> --- exchange before departure is not possible
           </changeBeforeFlight>
           <changeAfterFlight>
               <available>true</available>
               <currency>RUB</currency>
               <penalty>7640.00</penalty>
           </changeAfterFlight>
      </fare>
    </flight>
   </segment>
   <segment>
    <flight>
      <operatingCarrier>UN</operatingCarrier>
        <marketingCarrier>SU</marketingCarrier>
        <number>3</number>
        <departure>BOM</departure>
        <departureDate>2021-10-01</departureDate>
        <departureTime>09:55</departureTime>
        <arrival>DEL</arrival>
        <arrivalDate>2017-10-01</arrivalDate>
        <arrivalTime>11:10</arrivalTime>
        <equipment>736</equipment>
        <cabin>Y</cabin>
        <baggage>1PC23</baggage>
        <handbags>1PC5</handbags>
        <totalBaggageCount>1</totalBaggageCount>
        <virtualInterline>false</virtualInterline>
        <fareCode>WOW1</fareCode>
        <isBus>false</isBus>
        <isTrain>false</isTrain>
        <technicalStop>
        </technicalStop>
     <fare>
           <returnBeforeFlight>
               <available>false</available>
           </returnBeforeFlight>
           <returnAfterFlight>
               <available>true</available>
               <currency>RUB</currency>
               <penalty>2940.00</penalty>
           </returnAfterFlight>
           <changeBeforeFlight>
               <available>false</available>
           </changeBeforeFlight>
           <changeAfterFlight>
               <available>true</available>
               <currency>RUB</currency>
               <penalty>0</penalty>
           </changeAfterFlight>
      </fare>
       </flight>
    </segment>
  </variant>
<variant>
...more variants...
</variants>

Empty response example (no proposals)

<?xml version='1.0' encoding='utf-8' ?>
<variants></variants>
  • Server should respond in 30 seconds or less.
  • All non HTTP 200 responses are errors. Response should contain text description of error.
  • All HTTP 200 responses are successful responses.
  • BOOKING_PAGE_DEEPLINK string is an URL to booking page. Booking page language and currency must match the language and currency provided in the request.

Response content

  • /variants - root element containing ticket variants.
  • //variant - full flight variant
  • price (mandatory) - total price for all the passengers.
  • currency (mandatory) - currency code used in price. For example RUB.
  • url (mandatory) - deeplink to variant page for booking.
  • seats (optional) – seats available for booking by current fare. 0..9 number. 0 for no tickets available and 9 for more than 9 tickets available.
  • commission (optional) - commission rate for a specific proposal
  • segment - 1 element for one way, 2 for roundtrip
  • segment/flight - 1..n, more than one if there're connecting points in the requested leg
  • //flight - one hop flight information
    • operatingCarrier (mandatory) - airline IATA code (2 latin letters) aircraft belongs to this airline
    • marketingCarrier (optional) - airline IATA code (2 latin letters) of code sharing airline. Should be specified if differs with operatingCarrier
    • number (mandatory) - 2..4 digits, full flight number is (operatingCarrier + number)
    • departure (mandatory) - departure airport IATA code (3 latin letters)
    • departureDate (mandatory) - departure date, 'YYYY-MM-DD', local
    • departureTime (mandatory) - departure time, 'HH:MM', local
    • arrival (mandatory) - arrival airport IATA code (3 latin letters)
    • arrivalDate (mandatory) - arrival date, 'YYYY-MM-DD', local
    • arrivalTime (mandatory) - arrival time, 'HH:MM', local
    • equipment (optional) - IATA (or russian domestic) aircraft/bus/train equipment type code. several letters/digits
    • cabin (optional) - cabin class. could be 'F' for 'first', 'C' for 'business', 'W' for comfort, 'Y' for 'economy/couch'
    • baggage (optional) — baggage string code in format {N}PC{WW} where N is a number of bags permitted by current fare and WW is a max weight of every bag. Please pass an empty string if no baggage information available, and 0PC value for hand baggage only fares.
    • handbags (optional) — handbags string code in format {N}PC{WW} where N is a number of bags permitted by current fare and WW is a max weight of every bag. Please pass an empty string if no handbags information available.
    • totalBaggageCount (optional) — total baggage count for all passengers for a specific flight. Please pass an empty value if no information available.
    • virtualInterline (optional) — the feature describing the passenger has to check in again between segment with the interline and next one true|false.
    • isCharter (optional) - qualifies segment as charter true|false
    • charterType (optional) - specify a charter type regular|block
    • fareCode (optional) – fare code or fare basis for current variant.
    • isBus (optional)/isTrain(optional) — qualifies segment as part of multimodal itinerary carried by bus/train true|false.
    • //technicalStop — List of Technical Stops
      • airportCode — IATA-code of the airport
    • //fare (optional) — extended information on the fare conditions for a specific flight
      • returnBeforeFlight — information about the possibility to return the ticket before departure
        • available — true if it's possible/false of it's impossibple
        • currency — surcharge currency
        • penalty — surcharge value. If the service is provided free of charge, we expect to receive 0
      • returnAfterFlight — information on the possibility of returning the ticket after departure. nesting tags are similar to the returnBeforeFlight tag
      • changeBeforeFlight — information on the possibility of exchanging a ticket before departure. nesting tags are similar to the returnBeforeFlight tag
      • changeAfterFlight — information on the possibility of exchanging a ticket after departure. nesting tags are similar to the returnBeforeFlight tag

Client redirects user browser to the url from variant/url tag. Client is also able to add tracking marker (also called sub-id) string to variant/url URL to track customers. Full deeplink booking URL built as follows:

  1. Parse Deeplink URL
  2. Add marker=<marker_value> to query params section (make sure the request parameters of the original deep link URL comply with the RFC 3986 standard)
  3. Encode query params section

marker_value - is a string containing 256 characters or less. Markers should be returned as a part of booking information in statistics.

Request multi city example

curl 'http://example.ru/api/search?from=MOW&to=LED&date1=2017-09-25&from2=LED&to2=IKT&date2=2017-10-01&from3=IKT&to3=VVO&date3=2017-10-03&adults=2&children=1&infants=1&cabin=Y&partner=avsl&password=pass&locale=ru&currency=rub'

Response multi city example

<?xml version='1.0' encoding='utf-8' ?>
<variants>
    <variant>
        <price>2664</price>
        <currency>rub</currency>
        <url>BOOKING_PAGE_DEEPLINK</url>
        <seats>3</seats>
        <commission>0.0493</commission>
        <segment>
            <flight>
                <operatingCarrier>UN</operatingCarrier>
                <marketingCarrier>SU</marketingCarrier>
                <number>3</number>
                <departure>DME</departure>
                <departureDate>2017-09-25</departureDate>
                <departureTime>09:55</departureTime>
                <arrival>LED</arrival>
                <arrivalDate>2017-09-25</arrivalDate>
                <arrivalTime>11:10</arrivalTime>
                <equipment>735</equipment>
                <cabin>Y</cabin>
                <baggage>1PC23</baggage>
                <handbags>1PC5</handbags>
                <virtualInterline>false</virtualInterline>
                <fareCode>WOW1</fareCode>
                <isBus>false</isBus>
                <isTrain>false</isTrain>
            </flight>
        </segment>
        <segment>
            <flight>
                <operatingCarrier>UN</operatingCarrier>
                <marketingCarrier>SU</marketingCarrier>
                <number>3</number>
                <departure>LED</departure>
                <departureDate>2017-10-01</departureDate>
                <departureTime>09:55</departureTime>
                <arrival>IKT</arrival>
                <arrivalDate>2017-10-01</arrivalDate>
                <arrivalTime>11:10</arrivalTime>
                <equipment>736</equipment>
                <cabin>Y</cabin>
                <baggage>1PC23</baggage>
                <handbags>1PC5</handbags>
                <virtualInterline>true</virtualInterline>
                <fareCode>WOW1</fareCode>
                <isBus>false</isBus>
                <isTrain>false</isTrain>
                <technicalStop>
                    <airportCode>AER</airportCode>
                </technicalStop>
                <technicalStop>
                    <airportCode>AAQ</airportCode>
                </technicalStop>
            </flight>
        </segment>
        <segment>
            <flight>
                <operatingCarrier>SU</operatingCarrier>
                <marketingCarrier>SU</marketingCarrier>
                <number>3</number>
                <departure>IKT</departure>
                <departureDate>2017-10-03</departureDate>
                <departureTime>10:55</departureTime>
                <arrival>VVO</arrival>
                <arrivalDate>2017-10-03</arrivalDate>
                <arrivalTime>15:00</arrivalTime>
                <equipment>736</equipment>
                <cabin>Y</cabin>
                <baggage>1PC23</baggage>
                <handbags>1PC5</handbags>
                <virtualInterline>false</virtualInterline>
                <fareCode>WOW1</fareCode>
                <isBus>false</isBus>
                <isTrain>false</isTrain>
            </flight>
        </segment>
    </variant>
    <variant>
    ...more variants...
    </variant>
</variants>

Sales reporting

Request example

curl 'http://example.com/api/statistics?date1=2016-05-01&date2=2016-06-01&partner=aviasales&password=secret'

Request parameters

  • date1 - YYYY-MM-DD date.
  • date2 - YYYY-MM-DD date.
  • partner - partner identifier.
  • password - password of current partner.

Response should contain all bookings created between date1 and date2.

Response example:

<bookings>
  <booking>
    <id>JHKHVR</id>
    <PNR>AEFE3S</PNR>
    <created_at>2012-05-02 00:02:01</created_at>
    <marker>1232:1222.t</marker>
    <price>1199</price>
    <profit>200</profit>
    <currency>RUB</currency>
    <state>PAID</state>
    <segment>
      <flight>
        <operatingCarrier>UN</operatingCarrier>
        <number>3</number>
        <departure>DME</departure>
        <departureDate>2012-09-25</departureDate>
        <departureTime>09:55</departureTime>
        <arrival>LED</arrival>
        <arrivalDate>2012-09-25</arrivalDate>
        <arrivalTime>11:10</arrivalTime>
        <equipment>735</equipment>
        <cabin>Y</cabin>
      </flight>
    </segment>
    <adults>1</adults>
    <children>0</children>
    <infants>0</infants>
  </booking>
  ...more bookings...
</bookings>

Response content

  • /bookings - root element containgin all bookings.
  • //booking - information on one booking.
  • id - unique identifier of booking.
  • PNR - PNR of booking.
  • created_at - YYYY-MM-DD HH:MM date and time of booking in UTC time.
  • marker - marker sent to booking deeplink in GET parameter marker.
  • from - origin IATA.
  • to - destination IATA.
  • price - prices of tickets.
  • profit - metasearch agency profit for this booking.
  • currency - currency for fields price and profit.
  • state - state of booking. Possible values PROCESSING/PAID/CANCELLED.
  • segment - same as in search results.
  • //flight - one hop flight information
    • operatingCarrier - airline IATA code (2 latin letters) aircraft belongs to this airline
    • number - 2..4 digits, full flight number is (operatingCarrier + number)
    • departure - departure airport IATA code (3 latin letters)
    • departureDate - departure date, 'YYYY-MM-DD', local
    • departureTime - departure time, 'HH:MM', local
    • arrival - arrival airport IATA code (3 latin letters)
    • arrivalDate - arrival date, 'YYYY-MM-DD', local
    • arrivalTime - arrival time, 'HH:MM', local
    • equipment - IATA (or russian domestic) aircraft/bus/train equipment type code. several letters/digits
    • cabin - cabin class. could be 'F' for 'first', 'C' for 'business', 'W' for comfort, 'Y' for 'economy/couch'
  • adults - Adults.
  • children - Children.
  • infants - Infants.

Please use Fast API tester located in Aviasales Backoffice in order to check the integration format. Contact Integrations Support for credentials

Valid state tag values

  • PROCESSING: temporary state. Payment/confirmation has not been received yet (pending). This state must change to either PAID or CANCELLED within 24 hours. The <price> and <profit> tags must contain the real amount of the order cost and profit and be positive values other than zero. Orders in the PROCESSING state are not included in the invoice, but since we expect the state to be finalized within 24 hours, situations where non-finalized reservations appear in the reconciliation at the end of the month should not occur.

  • PAID: the order is paid. If no changes are made to the order, the state PAID will remain until the end of the statistics life. In case of any changes, an order in the PAID state can take any state except PROCESSING. The <price> and <profit> tags must contain the real amount of the order cost and profit and be positive values other than zero. For orders in the PAID state, we expect to be paid a commission in the amount of the value in the <profit> tag.

  • CANCELLED: the order is cancelled. A reservation can take this state after the PROCESSING or PAID statees. The <price> and <profit> tags must contain the real amount of the failed order cost and profit and be positive values other than zero. Orders in the CANCELLED state are not included in the end-of-month invoice, as we do not expect to be paid any commission for them.

  • REFUND: refunds for which Aviasales will return a commission to the partner, as specified in the agreement. A transaction can only be converted to this state from the PAID state. The <price> and <profit> tags must contain positive values other than zero and should remain the same as the order changed from PAID to REFUND. If the purchase and refund occurred in the same month, orders that changed their state to REFUND are not included in the final invoice, and we do not expect to be paid any commission on them. If the purchase was made in previous months, and we have already get paid a commission for the order, then it must also be changed to the REFUND state in the API, and we will pay the commission for this order back. In order to recalculate the total amount of commission, you need to include a list of refunds into your monthly financial report.

  • PAID_REFUND: orders for which the commission is not returned to the partner, as specified in the agreement. A transaction can only acquire this state after the PAID state. The values in the <price> and <profit> tags must remain the same as the order moved from PAID to PAID_REFUND. For orders in the PAID_REFUND state, we expect to be paid a commission equal to the values in the <profit> tag.

  • PART_REFUND: a partial refund. A booking can switch from the PAID state to PART_REFUND only if part of the tickets/segments were returned, but at least one paid ticket/segment remains in the order. In this case, the order must acquire the PART_REFUND state. If the returned ticket/segment falls under the REFUND rules (i.e. Aviasales has to return the commission for this part according to the agreement), the price of the booking in the PART_REFUND state must be reduced by the refund amount. The value in <price> is equal to the cost of the remaining order price, the value in <profit> is reduced accordingly. If returned tickets/segments fall under the rules of PAID_REFUND, we expect to be paid a full commission on the entire order, including the returned part. Do not reduce <price> and <profit> values in this case.

Valid state transitions chart

Order lifecycle

Supported directions

Request example

curl 'http://example.ru/api/supported_directions?partner=aviasales&password=secret'

Response example:

LON,PAR

PAR,LON

...

NYC,MOW

MOW,NYC

Response content

We expect to receive in response a pair of IATA codes of departure and arrival cities.

Add a custom footer
Add a custom sidebar
Clone this wiki locally