Інтеграція API бронювання авіаквитків: чого не пишуть

У тікеті на дошці написано «додати авіаперельоти». Ви вже робили інтеграцію платежів, розрахунок вартості доставки, можливо, карти — і приходите з очевидною моделлю: пошук, результати, списання з картки, готово. А потім перше справжнє бронювання повертається з іншою ціною, ніж на сторінці результатів, друге падає по тайм-ауту, і ніхто не може сказати, чи має клієнт місце, а з операційного відділу питають, чому бронь є, а квитка немає. Ззовні інтеграція API бронювання авіаквитків схожа на звичайний чекаут інтернет-магазину. Насправді це розподілена транзакція із системами, створеними задовго до REST, і більшість сюрпризів народжується саме в цьому розриві.
Текст написано для розробника, який ще ніколи не бачив PNR. Він не про ендпоінти конкретного постачальника: назви в різних провайдерів різні, а форма однакова.
Інтеграція API бронювання авіаквитків: послідовність викликів
Майже кожен авіа-API, хоч як він називає свої методи, проходить ті самі чотири кроки. Правильно провести межі між ними — це більша частина роботи.
| Крок | Що ви отримуєте | Що треба зберегти | Що йде не так |
|---|---|---|---|
| Пошук | Маршрути з ціною та непрозорим ключем пропозиції або тарифу | Нічого довготривалого — результати швидко застарівають | Ціну сприймають як остаточну; ключ спливає раніше, ніж клієнт доходить до оплати |
| Ціноутворення / перевірка | Підтверджена ціна, правила тарифу, багаж, іноді обов'язкові поля пасажира | Перевірену пропозицію та термін її дії | Ціна змінилася; клас розпродано; правила відрізняються від показаних |
| Бронювання | Бронь — PNR — із record locator і дедлайном виписки | Власний номер бронювання, локатор, дедлайн, точні надіслані дані пасажирів | Тайм-аут без відповіді; дубльовані PNR; імена відхилено |
| Виписка | Номери виписаних електронних квитків; саме тут гроші справді зобов'язуються | Кожен номер квитка — з прив'язкою до пасажира й сегмента | Часткова виписка; авіакомпанія скасувала бронь, бо минув дедлайн |
Найбільше суперечок викликає третій рядок, бо багато API дозволяють забронювати й виписати квиток одним викликом. Користуйтеся, якщо хочете. Але у світі авіакомпанії це досі дві окремі речі: PNR може існувати без квитка, а виписка може зірватися вже після створення PNR. Об'єднаний ендпоінт лише ховає момент, коли одне вдалося, а друге ні, тож у вашій моделі даних для цього стану все одно має бути місце.
Зверніть увагу й на те, чого пошук не повертає: обіцянки. Це реклама. Крок ціноутворення — це комерційна пропозиція, і лише квиток є продажем.
Чому ціна в пошуку — не ціна в бронюванні
Веброзробники очікують каталог. Запаси авіакомпанії — не каталог. Рейс продається за класами бронювання, кожен із яких — кошик місць за певним тарифом, і авіакомпанія безперервно відкриває та закриває ці кошики, поки рейс заповнюється. Результати пошуку швидко збираються з даних про наявність, які вже можуть трохи відставати; поки користувач вводить два паспорти, найдешевший кошик на рейсі може закритися. Коли запускається крок ціноутворення, він питає знову, і чесна відповідь іноді виявляється вищою.
Податки додають власний дрейф. Їх перераховують під час ціноутворення для конкретних пасажирів і маршруту, а дитина чи немовля тарифікуються інакше, ніж дорослий, якого припускав пошук. Конвертація валют, якщо ваша вітрина показує не ту валюту, в якій котирує постачальник, — ще одне місце, де число зсувається.
Висновок для архітектури простий, і його часто пропускають: ніколи не списуйте гроші за ціною з пошуку. Запустіть крок ціноутворення до оплати, порівняйте, і якщо сума змінилася — покажіть нову й запитайте клієнта. Будь-яку націнку треба перерахувати на оновленому тарифі, а не переносити зі сторінки результатів. Це та сама логіка, яку агенція проходить, коли вибудовує стратегію націнки онлайн, і ламається вона так само, коли база під нею зсувається.
Ідемпотентність і що означає тайм-аут під час бронювання
Цей розділ варто прочитати двічі.
Коли виклик бронювання закінчується тайм-аутом, ви не знаєте, що сталося. Запит міг узагалі не дійти. Міг дійти й завершитися помилкою. Або — найболючіший випадок — дійшов, постачальник створив PNR в авіакомпанії, а відповідь загубилася дорогою назад. Для вашого коду всі три варіанти виглядають однаково. Для авіакомпанії третій — це жива бронь, яка тримає місця на ім'я вашого клієнта.
Рефлекс з інших інтеграцій — повторити запит. Тут сліпий повтор може створити другий PNR на тих самих пасажирів на тому самому рейсі. Авіакомпанії вважають дубльовані бронювання порушенням правил; залежно від перевізника та угод агенції наслідки бувають різні — від автоматичного скасування однієї чи обох броней до дебетового мемо, ADM, виставленого тому, хто їх оформив. Агенція, яка його отримає, захоче знати, чому ваша система забронювала двічі.
Що працює — приблизно в такому порядку:
- Створіть власний номер бронювання ще до зовнішнього виклику, збережіть його й передавайте із запитом скрізь, де API приймає клієнтський референс. Якщо API підтримує ключ ідемпотентності (idempotency key), використовуйте його; якщо ні — саме ваш номер дозволить потім знайти бронювання.
- Явно змоделюйте невідомий стан. Очікує, підтверджено, помилка — і невідомо. Тайм-аут переводить бронювання в «невідомо», а не в «помилку».
- З'ясовуйте невідоме запитом, а не повтором. Отримайте бронювання за вашим номером або перегляньте останні бронювання на цих пасажирів, перш ніж вирішувати, чи пробувати знову.
- Запустіть задачу звірки, яка проходить по всьому, що досі в стані «невідомо», порівнює це з даними постачальника, а те, що не вдається розв'язати, відправляє в чергу людині, замість того щоб вгадувати.
Тайм-аути під час виписки — та сама проблема, тільки з грошима. Якщо списати кошти з картки до виписки, а виписка зависне, у вас клієнт, який заплатив, і, можливо, жодного квитка. Якщо виписати до списання, а списання не пройде, ви оформили документ, за який комусь доведеться заплатити авіакомпанії. Типова схема — спершу авторизувати картку, потім виписати квиток, а в разі успіху списати кошти. Суть у тому, щоб ухвалити це рішення свідомо, а не виявити його в продакшені.
Поняття авіабізнесу, які дивують веброзробників
Жодне з них не складне. Кожне коштувало комусь тижня роботи просто тому, що людина не знала про його існування.
PNR — це не квиток
PNR — це запис бронювання: пасажири, сегменти, контакти, дедлайн. Квиток — оплачений документ, який дає пасажирові право летіти. Невиписаний PNR спливає в дедлайн виписки, і місця повертаються в продаж — іноді так, що ви цього навіть не помічаєте.
Імена майже не змінюються
Після виписки більшість тарифів не дозволяють змінити ім'я, окрім дрібного виправлення, а що вважається дрібним, кожна авіакомпанія визначає по-своєму. Ім'я має збігатися з документом для подорожі. Збирайте прізвище та ім'я окремо, не допускайте, щоб звертання з вільного тексту потрапило в поле імені, і перевіряйте дані до виклику бронювання, а не після.
Типи пасажирів впливають на ціну, а не прикрашають форму
Дорослий, дитина й немовля — це типи тарифу, і вік, який визначає тип, зазвичай рахується на дату подорожі, а не на дату бронювання. Немовля на руках, як правило, не займає місця й може летіти лише з дорослим. Помилитеся з типом — і крок ціноутворення або впаде, або назве не той тариф.
Час місцевий, а сегменти — не плечі
Час вильоту й прильоту вказується за місцевим часом кожного аеропорту. Не конвертуйте його в часовий пояс користувача для показу й не рахуйте тривалість простим відніманням без урахування зміщень. Подорож складається із сегментів; сегмент із технічною посадкою містить більше одного плеча (leg). Ваш інтерфейс і ваші дані мають однаково розуміти, що саме з цього вважається «зупинкою».
Після продажу теж усе змінюється
Авіакомпанії змінюють розклад уже після виписки квитків. Бронювання, яке було правильним у момент виписки, за кілька тижнів може показати новий час, новий номер рейсу чи розірвану стиковку, і залежно від постачальника ви дізнаєтеся про це через сповіщення, чергу або повторно отримавши бронювання. Закладайте, що бронювання зміниться вже після того, як ви перестали на нього дивитися.
Void — це не повернення
Невдовзі після виписки зазвичай є вікно, у яке квиток можна анулювати (void) так, ніби його ніколи не існувало. Після цього вікна можливе лише повернення за правилами тарифу, і воно може коштувати штрафу або не повернути нічого. Вікно та його правила визначають постачальник і угода, за якою виписано квиток; прочитайте їх, перш ніж робити кнопку «Скасувати».
Скільки коштує помилка
Збої в авіаінтеграції дорогі в особливий спосіб: вони падають на людей, а не в логи. Дубльоване бронювання перетворюється на дзвінок в авіакомпанію і, можливо, мемо на рахунок агенції. Клієнт, з якого списали гроші, але який лишився без квитка, — це повернення коштів, скарга й ризик чарджбеку. Квиток, виписаний без успішної оплати, — борг перед авіакомпанією, який хтось мусить закрити. Зміна розкладу, яку ніхто не опрацював, — мандрівник в аеропорту на рейс, що вилетів раніше.
Нічого з цього не видно в тесті «щасливого шляху». Спершу напишіть нещасливі сценарії: тайм-аут під час бронювання, ціну, що зросла, квиток, який не виписався після створення PNR, анулювання після успішної оплати. Якщо вони оброблені, щасливий шлях — найлегша частина.
Тестування з авіа-API
Тестові середовища постачальників корисні, але неповні. Зазвичай вони спокійніші за продакшен, тож розпродані класи й зміни цін трапляються рідше, а деякі взагалі не імітують тайм-аути. Використовуйте їх, щоб відпрацювати форму викликів і помилки валідації, а потім сплануйте контрольований прогін у продакшені зі справжніми бронюваннями, які ви анулюєте в межах вікна, — попередивши операційний відділ.
Чи інтегруватися взагалі — окреме питання. Якщо насправді вам потрібна вітрина, а не сирі запаси у власній системі, компроміс розібрано в матеріалі white label чи власна система бронювання, і та сама логіка стосується B2B-порталу для субагентів. Якщо ж ви хочете мати запаси у власному коді, ця платформа надає API для авіаквитків і готелів, а доступ починається з розмови про ваш сценарій, а не з ключа в режимі самообслуговування, — і це якраз слушний момент, щоб поставити кожне з питань вище.