Руководство по использованию API

📖 Введение

Успешный ответ: status = success и данные в results. Кроме получения токена, каждый вызов передаёт заголовок Authorization: Bearer <токен>.

Токен живёт 90 минут. Просроченный или поддельный токен — это не AUTH_1005, а HTTP 401 с телом detail.error.code = UNAUTHORIZED.

1️⃣ Получение токена аутентификации

Это фундаментальный шаг, который инициирует сессию взаимодействия с API. Без валидного токена ни один другой защищенный эндпоинт не будет доступен.

📥 Ключевые поля запроса:

• username (string, обязательное) - Уникальный идентификатор партнера в нашей системе
• password (string, обязательное) - Секретный ключ, ассоциированный с вашим именем пользователя

📤 Ключевые поля ответа:

• status (string) - Индикатор успешности операции
• token (string) - JWT. Срок 90 минут, в ответе срока нет

2️⃣ Запрос коммерческого предложения (Air Shopping)

Это основной эндпоинт для поиска авиабилетов и формирования предложений.

📥 Ключевые поля запроса:

• itinerary (array) - Массив сегментов маршрута с полями:
  • origin - IATA-код города отправления
  • destination - IATA-код города прибытия
  • date_to - Дата вылета (YYYY-MM-DD)
• flight_class (string) - Класс обслуживания: Economy, Premium Economy, Business, First. Касса может не продавать выбранный класс и вернуть пустой список.
• adt (integer) - Количество взрослых пассажиров
• chd (integer, опц.) - Количество детей
• inf (integer, опц.) - Количество младенцев без места
• ins (integer, опц.) - Количество младенцев с местом
• currency (string) - Валюта цен в ответе. Набор валют задаётся для вашего пользователя.

📤 Ключевые поля ответа:

• results.Offer - массив предложений. Пустой массив значит, что рейсов нет, это не ошибка
• OfferID - идентификатор предложения. Для брони берите его заново из ответа уточнения цены
• TotalPrice - стоимость предложения
• OfferExpirationTimeLimitDateTime - до какого момента предложение ещё можно уточнить. Наивная строка без смещения, в зоне поля timezone. Если timezone не передан, берётся зона учётной записи, а если она не задана — UTC. Время вылета и прилёта этой зоной не переводится

3️⃣ Запрос правил применения тарифов

Предоставляет необходимую информацию для клиента перед покупкой билета.

📥 Ключевые поля запроса:

• offer_id (string) - OfferID из предыдущего запроса

📤 Ключевые поля ответа:

• Rules - массив. Текст правила в FareRuleText.Remark.RemarkText. DesigCode - код авиакомпании (IATA), один смысл на всех кассах. PaxType - тип пассажира, только если текст свой для этого типа. RuleKey - ключ тарифа поставщика, если он длиннее кода авиакомпании.

4️⃣ Уточнение цены

📥 Ключевые поля запроса:

• offer_id (string) - OfferID предложения
• currency (string) - Валюта для уточненной цены

📤 Ключевые поля ответа:

• Offer.OfferID - новый идентификатор. Дальше используйте его, а не OfferID из поиска
• Offer.TotalPrice - уточнённая стоимость
• Offer.BookingID - номер заказа для создания, выписки, просмотра и отмены
• Offer.OrderStatus - после уточнения цены это SELECTED. Создание заказа принимает только этот статус

5️⃣ Резервирование инвентаря

Отдельного резерва мест на этом шаге нет: место держится при создании заказа. Этот вызов можно пропустить. POST /api/inv-guarantee-release/ тоже не снимает место. Срок оплаты смотрите в PaymentTimeLimitDateTime ответа /api/create/.

📥 Ключевые поля запроса:

• offer_id (string) - Актуальный OfferID из /api/offerprice/

📤 Ключевые поля ответа:

• InventoryGuarantee.OfferID - тот же OfferID
• InventoryGuarantee.InventoryGuaranteeTimeLimitDateTime - срок удержания. Если место на этом шаге не держится, поле пустое

6️⃣ Создание заказа (Booking Creation)

Основной этап формирования бронирования с привязкой к конкретным пассажирам.

📥 Ключевые поля запроса:

• booking_id (integer) - BookingID из /api/offerprice/
• paxes (array) - Массив данных о пассажирах:
  • pax_id - ID пассажира
  • ptc - Тип пассажира: ADT, CHD, INF или INS
  • individual - Личные данные: given_name, surname, birthdate, gender. middle_name необязателен
  • doc - Документ: doc_id, type_code, expiry_date, issuing_country_code
  • phone и email - обязательны у каждого пассажира
• currency (string) - Валюта заказа
• Idempotency-Key (заголовок, необязательный) - 8–80 символов: буквы, цифры, точка, подчёркивание, двоеточие, дефис. Один ключ на один заказ. Повтор того же ключа возвращает только номер и статус, без нового бронирования. Тот же ключ на другой заказ даёт ERR_1023

📤 Ключевые поля ответа:

• Order.OrderStatus - после создания BOOKED. Это бронь, не билет. Повтор создания из другого статуса отвечает ERR_1013
• Order.PaymentTimeLimitDateTime - срок оплаты. Наивная строка без смещения, в зоне поля timezone. Если timezone не передан, берётся зона учётной записи, а если она не задана — UTC. После срока место снимается, повторная оплата эту бронь не вернёт
• Order.PNRBookingID - код брони у нас
• Order.AirlineBookingID - код брони авиакомпании, если он уже есть

7️⃣ Одобрение заказа (Order Approval)

📥 Ключевые поля запроса:

• booking_id (integer) - BookingID заказа для одобрения
• currency (string) - Валюта заказа
• Idempotency-Key (заголовок, необязательный) - тот же формат, что при создании. Один ключ на один заказ. Тот же ключ на другой заказ даёт ERR_1023

📤 Ключевые поля ответа:

• Order.OrderStatus - При успехе ISSUED. В обычном ответе поля StatusCode нет. Повтор уже оплаченной выписки возвращает ISSUED и StatusCode = CLOSED
• Ticket - Массив билетов. Номер билета в TicketNumber
• Order.VoidTimelimitUtc - до какого времени билет можно аннулировать. Наивная строка без смещения, в зоне поля timezone, а не метка UTC. Если timezone не передан, берётся зона учётной записи, а если она не задана — UTC. Поля нет, если срок не прислали

8️⃣ Просмотр состояния заказа

Order.OrderStatus в ответе — статус, записанный у нас: BOOKED, PROCESSING, ISSUED, FAILED или CANCELED. Если сохранённая карточка есть, ответ берётся из неё. Иначе заказ читается заново, но статус в ответе всё равно наш.

📥 Ключевые поля запроса:

• booking_id (integer) - BookingID для просмотра
• currency (string) - Валюта для ценовых компонентов

📤 Ключевые поля ответа:

• Order.OrderStatus - Статус, записанный у нас: BOOKED, PROCESSING, ISSUED, FAILED или CANCELED. PROCESSING значит, что выписка ещё не закончена, это не билет
• Ticket - Массив выписанных билетов. Пусто, пока статус не ISSUED

9️⃣ Отмена заказа

📥 Ключевые поля запроса:

• booking_id (integer) - BookingID заказа для отмены

📤 Ключевые поля ответа:

• Canceled - true, если отмена принята
• MixOrderRef.Order.OperationStatus - Success при принятой отмене. Отдельного MixOrderID в этом ответе нет

⚠️ Коды ошибок веб-сервиса

Справочник кодов ошибок, которые могут возникнуть при работе с API. Ошибки разделены на категории для упрощения диагностики проблем.

📋 Как читать ошибку

Неуспешный вызов бизнес-логики возвращает тело без обёртки detail:

{
    "error": {
    "code": "AGR_PROVIDER_ERROR",
    "message": "CAN'T MAKE AUTOPRICING",
    "avs_code": "BOOKING_PRICE_UNAVAILABLE"
  }
}

У одного кода бывает несколько фраз. Код не меняется, читайте message. Например ERR_1013 — «Создание возможно только из статуса SELECTED» или «Для создания заказа нужен хотя бы один пассажир». ERR_1020 — «Доступ запрещен» либо «Заказ привязан к другому реквизиту». ERR_1023 — выписка или создание уже идут, либо ключ идемпотентности занят другим заказом. Это не билет. ERR_1026 при пустом сроке аннулирования говорит: нет срока, отмена билета недоступна.

Общие имена

У одной и той же ситуации одно имя в avs_code, откуда бы ни пришла ошибка. Полный список имён: GET /error-codes/ с тем же токеном. Если отдельного имени нет, приходит PROVIDER_ERROR. Старые значения в поле code при этом не меняются.

Фразы авиакомпании