Перейти к содержимому
Блог

Интеграция API бронирования авиабилетов: о чём молчит документация

Редакция Tekravel
Написано с помощью ИИ

В задаче на доске написано коротко: «добавить авиабилеты». Вы уже подключали платёжный шлюз, расчёт доставки, может быть, карты, и модель в голове очевидная: поиск, выдача, списание с карты, готово. Потом первое настоящее бронирование возвращается с ценой, отличной от цены на странице выдачи, второе падает по таймауту, и никто не может сказать, есть ли у клиента место, а кто-то из операционного отдела спрашивает, почему есть бронь, но нет билета. Интеграция API бронирования авиабилетов снаружи похожа на обычный чекаут интернет-магазина. Внутри это распределённая транзакция с системами, спроектированными задолго до REST, и большинство сюрпризов рождается именно в этом зазоре.

Текст написан для разработчика, который ни разу не видел PNR. Он не про эндпоинты конкретного поставщика: названия меняются от провайдера к провайдеру, форма — нет.

Последовательность вызовов при интеграции API бронирования авиабилетов

Почти любой авиационный API, как бы он ни называл свои методы, проходит одни и те же четыре шага. Правильно провести границы между ними — это бóльшая часть работы.

ШагЧто возвращаетЧто нужно сохранитьЧто ломается
ПоискМаршруты с ценой и непрозрачным ключом предложения или тарифаНичего долговременного — выдача быстро устареваетЦену считают окончательной; ключ истекает до оплаты
Прайсинг / проверкаПодтверждённую цену, правила тарифа, багаж, иногда обязательные поля пассажировПроверенное предложение и срок его жизниЦена изменилась; класс распродан; правила не совпадают с показанными
БронированиеБронь — PNR — с кодом бронирования и тайм-лимитом на выпискуСвой собственный идентификатор, код брони, тайм-лимит, данные пассажиров ровно в том виде, в каком отправленыТаймаут без ответа; дублирующиеся PNR; отклонённые имена
ВыпискаНомера электронных билетов; именно здесь деньги реально фиксируютсяКаждый номер билета с привязкой к пассажиру и сегментуЧастичная выписка; авиакомпания сняла бронь, потому что тайм-лимит прошёл

Спорят обычно о третьей строке: многие API позволяют забронировать и выписать одним вызовом. Пользуйтесь, если удобно. Но в мире авиакомпаний это всё равно две разные вещи: PNR может существовать без билета, а выписка может упасть уже после создания PNR. Объединённый эндпоинт лишь прячет момент, когда одно удалось, а другое нет, — и в модели данных для этого состояния всё равно должно быть место.

Заметьте, чего поиск не возвращает: обещания. Поиск — это объявление. Прайсинг — это котировка, а продажа — только билет.

Почему найденная цена — не цена брони

Веб-разработчик ждёт каталог. Авиационный инвентарь каталогом не является. Рейс продаётся по классам бронирования, каждый из которых — корзина мест по определённому тарифу, и авиакомпания постоянно открывает и закрывает эти корзины по мере заполнения самолёта. Выдача собирается быстро из данных о наличии мест, которые уже могут немного отставать; пока пользователь вводит два паспорта, самая дешёвая корзина на рейсе может закрыться. Прайсинг спрашивает заново, и честный ответ иногда выше.

У таксов свой дрейф. Они пересчитываются при прайсинге для конкретных пассажиров и маршрута, а ребёнок или младенец тарифицируются иначе, чем взрослый, которого предполагал поиск. Если витрина показывает валюту, отличную от валюты поставщика — скажем, рубли на сайте при котировке в долларах, — конвертация становится ещё одним местом, где число сдвигается.

Вывод для дизайна простой и часто пропускается: никогда не списывайте деньги по цене из поиска. Запускайте прайсинг до оплаты, сравнивайте, и если сумма изменилась — показывайте новую и спрашивайте. Наценку нужно пересчитывать от перецененного тарифа, а не переносить со страницы выдачи — это та же логика, через которую проходит агентство, выстраивая наценку для онлайн-продаж, и ломается она так же, когда база под ней сдвигается.

Идемпотентность и что значит таймаут при бронировании

Этот раздел стоит прочитать дважды.

Когда вызов бронирования падает по таймауту, вы не знаете, что произошло. Возможно, запрос не дошёл. Возможно, дошёл и завершился ошибкой. Или — болезненный случай — дошёл, поставщик создал PNR в авиакомпании, а ответ потерялся на обратном пути. Для вашего кода все три случая выглядят одинаково. Для авиакомпании третий — живая бронь, держащая места на имя вашего клиента.

Рефлекс из других интеграций — повторить запрос. Здесь слепой повтор может создать второй PNR на тех же пассажиров на том же рейсе. Авиакомпании считают дублирующие бронирования нарушением правил; в зависимости от перевозчика и договоров агентства последствия — от автоматической отмены одной или обеих броней до дебет-ноты, ADM, выставленной тому, кто их оформил. Агентство, получившее её, захочет узнать, почему ваша система бронировала дважды.

Что работает, примерно в таком порядке:

  • Создайте собственный идентификатор брони до внешнего вызова, сохраните его и передавайте с запросом везде, где API принимает клиентскую ссылку. Если API поддерживает ключ идемпотентности — используйте его; если нет, ваш идентификатор всё равно позволит найти бронь потом.
  • Явно смоделируйте неизвестное состояние. В ожидании, подтверждено, ошибка — и неизвестно. Таймаут переводит бронь в «неизвестно», а не в «ошибку».
  • Разрешайте неизвестное вопросом, а не повтором. Прежде чем решать, пробовать ли снова, получите бронь по своему идентификатору или запросите последние бронирования этих пассажиров.
  • Запустите задачу сверки, которая проходит по всему, что осталось неизвестным, сравнивает с данными поставщика и отправляет то, что не может разрешить, в очередь к человеку, а не угадывает.

Таймауты при выписке — та же проблема, только с деньгами. Если списать с карты до выписки, а выписка зависнет, у вас клиент, который заплатил, и, возможно, без билета. Если выписать до списания, а списание не пройдёт, вы оформили документ, за который кто-то должен заплатить авиакомпании. Типичная схема — сначала авторизация (холд) на карте, затем выписка, затем списание при успехе. Главное — решить это осознанно, а не обнаружить в продакшене.

Понятия из туризма, которые удивляют веб-разработчиков

Ни одно из них не сложное. Каждое стоило кому-то недели, потому что он не знал о его существовании.

PNR — это не билет

PNR — запись о бронировании: пассажиры, сегменты, контакты, тайм-лимит. Билет — оплаченный документ, дающий право на перелёт. Невыписанный PNR снимается по истечении тайм-лимита, и места возвращаются в продажу — иногда так, что с вашей стороны это незаметно.

Имена почти неизменяемы

После выписки большинство тарифов не разрешают менять имя, кроме мелкой корректировки, а что считается мелким, зависит от авиакомпании. Имя должно совпадать с документом. Собирайте фамилию и имя раздельно, не позволяйте свободно введённому обращению попасть в поле имени и проверяйте данные до вызова бронирования, а не после.

Типы пассажиров — это цена, а не украшение

Взрослый, ребёнок и младенец — тарифные типы, и решающим обычно является возраст на дату перелёта, а не на дату бронирования. Младенец на руках, как правило, не занимает места и летит только со взрослым. Ошибётесь с типом — прайсинг либо упадёт, либо вернёт не тот тариф.

Время местное, а сегмент — не плечо

Время вылета и прилёта указывается по местному времени каждого аэропорта. Не переводите его в часовой пояс пользователя при показе и не считайте длительность простым вычитанием без учёта смещений. Путешествие состоит из сегментов; сегмент с технической посадкой состоит из нескольких плеч. Интерфейс и данные должны договориться, что из этого считается «пересадкой».

После продажи всё продолжается

Авиакомпании меняют расписание после выписки билетов. Бронь, корректная на момент выписки, через несколько недель может показать новое время, новый номер рейса или разорванную стыковку, и в зависимости от поставщика вы узнаете об этом через уведомление, очередь или повторный запрос брони. Закладывайте, что бронь изменится уже после того, как вы перестали на неё смотреть.

Войд — это не возврат

Вскоре после выписки обычно есть окно, когда билет можно аннулировать (void), как будто его не было. После этого окна возможен только возврат по правилам тарифа — со штрафом или вовсе без возврата денег. Окно и его правила определяет поставщик и договор на выписку; прочитайте их, прежде чем делать кнопку «отменить».

Во что обходится ошибка

Сбои в авиационной интеграции дороги особым образом: они падают на людей, а не в логи. Дублирующая бронь превращается в звонок в авиакомпанию и, возможно, в дебет-ноту на счёт агентства. Клиент, с которого списали деньги без билета, превращается в возврат, жалобу и риск чарджбэка. Билет, выписанный без успешной оплаты, превращается в долг перед авиакомпанией, который кому-то придётся закрыть. Изменение расписания, которое никто не обработал, превращается в пассажира в аэропорту на рейс, улетевший раньше.

Ничего из этого не видно в тесте «счастливого пути». Сначала напишите неудачные сценарии: таймаут при бронировании, выросшая цена, билет, упавший после PNR, войд после успешной оплаты. Если они обработаны, счастливый путь — самая простая часть.

Тестирование на авиационном API

Тестовые среды поставщиков полезны, но неполны. Обычно они спокойнее продакшена: распроданные классы и изменения цен там реже, а некоторые вообще не имитируют таймауты. Используйте их для формы вызовов и ошибок валидации, а затем спланируйте контролируемый прогон в продакшене с настоящими бронями, которые вы аннулируете в окне войда, — предупредив операционный отдел.

Интегрироваться ли вообще — отдельный вопрос. Если на самом деле вам нужна витрина, а не сырой инвентарь в собственной системе, компромисс разобран в статье своя платформа или white label, и та же логика применима к B2B-порталу для субагентов. Если же инвентарь нужен в вашем коде, эта платформа предоставляет API для авиабилетов и отелей, и доступ начинается с разговора о вашем сценарии, а не с ключа в самообслуживании — это же и подходящий момент задать каждый из вопросов выше.

Редакция Tekravel

Отдел travel-технологий

Отдел travel-технологий Tekravel пишет для профессионалов рынка: владельцев агентств, консолидаторов и разработчиков, которые их интегрируют. Каждая статья проверяется на той самой платформе, которую описывает, до публикации.