Параметры запроса#

Детальное описание параметров для запроса /api/avia/ticket_exchange.

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

Параметр	Тип	Описание
`exchangeId`	string	Идентификатор обмена из `/api/avia/ticket_exchange_calculation`
`offerItemId`	string	ID выбранного варианта обмена
`bookingId`	guid	Идентификатор бронирования (формат UUID)
`ticketNumber`	string	Номер билета для обмена, не более 14 символов (может включать префикс vendor)
`forExchange`	MonetaryAmount	Сумма к оплате за обмен
`legs`	Leg[]	Массив новых маршрутов
`passengers`	Passenger[]	Массив пассажиров

Структуры данных#

MonetaryAmount#

Параметр	Тип	Обязательно	Описание
`currencyCode`	string	Да	Код валюты (ISO 4217, например: RUB, USD); формат `^[A-Z]{3}$`
`value`	decimal	Да	Сумма к оплате за обмен; должна быть больше 0

Leg (маршрут)#

Параметр	Тип	Обязательно	Описание
`segments`	Segment[]	Да	Массив сегментов маршрута

Segment (сегмент)#

Параметр	Тип	Обязательно	Описание
`id`	string	Да	ID сегмента из варианта обмена; не более 50 символов
`class`	string	Да	Класс бронирования (буква, например: Y, C, F)
`destination`	BoardOffPoint	Да	Пункт назначения с датой/временем
`flight`	FlightDesignator	Да	Информация о рейсе
`origin`	BoardOffPoint	Да	Пункт отправления с датой/временем

BoardOffPoint#

Параметр	Тип	Обязательно	Описание
`airport`	string	Да	IATA код аэропорта (3 символа)
`dateTime`	datetime	Да	Дата и время (ISO 8601); должна быть строго в будущем

FlightDesignator#

Параметр	Тип	Обязательно	Описание
`carrierCode`	string	Да	IATA код авиакомпании (2 символа)
`flightNumber`	string	Да	Номер рейса

Passenger (пассажир)#

Параметр	Тип	Обязательно	Описание
`lastName`	string	Да	Фамилия (латиница, как в документе); не более 50 символов
`firstName`	string	Да	Имя (латиница, как в документе); не более 50 символов
`type`	PassengerType	Нет	Тип пассажира (`adt`, `chd`, `inf`)
`documents`	Document[]	Да	Массив документов пассажира; не менее одного документа

Document (документ)#

Параметр	Тип	Обязательно	Описание
`type`	DocumentType	Нет	Тип документа (`internationalPassport`, `nationalPassport`, `birthCertificate`, `identityCard`, `notSet`)
`number`	string	Да	Номер документа; не более 50 символов
`lastName`	string	Да	Фамилия в документе (латиницей)
`firstName`	string	Да	Имя в документе (латиницей)
`middleName`	string	Нет	Отчество в документе
`series`	string	Нет	Серия документа (если применимо)
`birthDate`	date	Нет	Дата рождения (формат: YYYY-MM-DD)
`issueDate`	date	Нет	Дата выдачи (формат: YYYY-MM-DD)
`expireDate`	date	Нет	Срок действия (формат: YYYY-MM-DD); если указан — должен быть в будущем
`country`	string	Да	Страна выдачи (ISO 3166-1 alpha-2)

Пример запроса#

JSON

 1{
 2  "exchangeId": "DC0BED1AEF4D9CE789DDBBA384A9593C",
 3  "offerItemId": "fa94ea6a-ac07-49d7-a810-a4640f2774fd",
 4  "bookingId": "019a0ce7-b2b1-7670-9bb0-0823c0853344",
 5  "ticketNumber": "425-6170037301",
 6  "forExchange": {
 7    "currencyCode": "RUB",
 8    "value": 5000
 9  },
10  "legs": [
11    {
12      "segments": [
13        {
14          "id": "NLc0EJEsw0GJer9QRFb4Sg",
15          "class": "P",
16          "destination": {
17            "airport": "KZN",
18            "dateTime": "2025-11-29T09:20:00"
19          },
20          "flight": {
21            "carrierCode": "DP",
22            "flightNumber": "6841"
23          },
24          "origin": {
25            "airport": "SVO",
26            "dateTime": "2025-11-29T07:40:00"
27          }
28        }
29      ]
30    }
31  ],
32  "passengers": [
33    {
34      "lastName": "KOZLOV",
35      "firstName": "IVAN",
36      "type": "adt",
37      "documents": [
38        {
39          "type": "internationalPassport",
40          "number": "1234567890",
41          "lastName": "KOZLOV",
42          "firstName": "IVAN",
43          "birthDate": "1980-05-15",
44          "issueDate": "2015-06-20",
45          "expireDate": "2030-12-31",
46          "country": "RU"
47        }
48      ]
49    }
50  ]
51}

Обработка ошибок#

При обмене билета могут возникнуть следующие ошибки:

Код ошибки	Причина	Решение
`BOOKING_NOT_FOUND`	Бронирование не найдено или не принадлежит клиенту	Проверьте `bookingId`
`EXCHANGE_NOT_FOUND`	Данные расчёта обмена не найдены или срок их действия истёк	Выполните `ticket_exchange_calculation` заново
`VALIDATION_ERROR`	Ошибка валидации запроса (HTTP 400)	Проверьте обязательные поля и форматы значений
`NO_TARGETS`	Под запрос не нашлось ни одного поставщика: ни один не настроен либо все отсеяны на этапе подготовки запроса	Проверьте настройки офисов и пресетов в личном кабинете; при сохранении ошибки обратитесь в поддержку
`SUPPLIER_ERROR`	Поставщик вернул ошибку. Причина — текстом поставщика в поле `message`	Разберите `message`; при необходимости повторите запрос позже
`SYSTEM_ERROR`	Внутренняя ошибка Travel API	Повторите запрос позже; при повторении обратитесь в поддержку с `errorId`

Ошибки, пришедшие от GDS/NDC-поставщика, возвращаются под кодом SUPPLIER_ERROR: отдельного кода на каждую причину отказа Travel API не формирует, причина передаётся текстом поставщика в поле message. Не завязывайте логику на разбор message — его формат зависит от поставщика и не фиксирован.

Связанные операции#

Расчёт обмена - получение вариантов и стоимости обмена
Информация о билете - проверка статуса билета
Расчёт возврата - альтернатива обмену