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

📖 Введение

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

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

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

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

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

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

• status (string) - Индикатор успешности операции
• token (string) - Ваш JWT токен для авторизации

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

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

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

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

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

• OfferID - ⚡ Уникальный идентификатор предложения (важно для последующих запросов!)
• Flights - Детали каждого перелета
• TotalPrice - Суммарная стоимость предложения
• OfferExpirationTimeLimitDateTime - Время действия предложения

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

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

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

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

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

• FareRuleText - Объект с текстом правил тарифа
• RemarkText - Сырой текст тарифных правил

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

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

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

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

• OfferID - Актуальный OfferID (может измениться!)
• TotalPrice - Уточненная полная стоимость
• BookingID - ⚡ Временный ID бронирования (сохраните для следующих шагов!)

5️⃣ Резервирование инвентаря (Inventory Guarantee)

Этот шаг является опциональным, но настоятельно рекомендуется для критически важных бронирований.

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

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

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

• InventoryGuaranteeID - ID резервации
• InventoryGuaranteeTimeLimitDateTime - Время действия резервации

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

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

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

• booking_id (integer) - BookingID из /api/offerprice/
• paxes (array) - Массив данных о пассажирах:
  • pax_id - ID пассажира
  • ptc - Тип пассажира (ADT, CHD, INF)
  • individual - Личные данные (имя, фамилия, дата рождения, пол)
  • doc - Документ (номер, тип, страна)
• currency (string) - Валюта заказа

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

• MixOrderID - Внутренний ID заказа
• PNRBookingID - ⚡ PNR-код бронирования
• AirlineBookingID - Код бронирования авиакомпании
• StatusCode - Текущий статус (обычно "OPENED")

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

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

• booking_id (integer) - BookingID заказа для одобрения
• currency (string) - Валюта заказа

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

• StatusCode - Новый статус (обычно "CLOSED")
• TicketNumber - ⚡ Номер электронного билета
• VoidTimelimitUtc - Время для аннулирования без штрафа

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

Независимо от статуса, вы всегда можете получить актуальные данные о заказе.

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

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

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

• Order - Полная информация о заказе
• Ticket - Массив выписанных билетов (если есть)

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

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

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

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

• status - Статус выполнения операции
• OperationStatus - Статус отмены (ожидается "Success")
• MixOrderID - ID отмененного заказа

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

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

📋 Общие положения

Под ошибками понимается:

• Ошибки (error) - означающие неуспешное выполнение той или иной операции. Ошибки носят глобальный контекст.
• Предупреждения (warning) - означающие либо частичное выполнение операции, либо сообщение о невозможности выполнения операции согласно установленным бизнес-процессам, что ошибкой не является.

Уровни ошибок:

AVS API предусматривает 2 уровня для передачи ошибок:

Структура ошибок:

Все ошибки возвращаются в следующем формате JSON:

{
  "detail": {
    "error": {
      "code": "ERROR_CODE",
      "message": "Описание ошибки"
    }
  }
}

{
  "detail": {
    "error": {
      "code": "ERROR_CODE",
      "message": "Описание ошибки",
      "details": [ /* дополнительная информация */ ]
    }
  }
}

✈️ Ошибки провайдера (MIX)

⚠️ Важные примечания к специфическим ошибкам