Обробка помилок API системи бронювання: три збої, що коштують грошей

Тікет у підтримку приходить у четвер увечері. Клієнт заплатив, сторінка крутилася, а потім показала загальну помилку. Картку списано. У ваших логах є POST до постачальника, який так і не отримав відповіді. Чи утримала авіакомпанія місце? Ніхто не може сказати, а клієнт чекає. Добра обробка помилок API системи бронювання здебільшого полягає в тому, щоб ніколи не опинятися в такому становищі, або принаймні точно знати, що робити, коли опинився.
Більшість посібників з інтеграції розглядають помилки як каталог кодів статусу. У бронюванні коди — найлегша частина. Грошей коштує невелика група ситуацій, коли запит виглядає невдалим, але світ усе одно змінився, або виглядає вдалим, а світ не змінився. Три з них важать більше за решту.
Збій перший: ціна змінилася між пошуком і бронюванням
Результати пошуку — це пропозиція, а не договір. Тарифи кешуються, наявність місць спільна для всіх каналів, якими торгує постачальник, і сума, яку ви показали о 14:02, за кілька хвилин може застаріти. Постачальник повідомляє про це на кроці створення бронювання: іноді чіткою відповіддю «тариф змінено», іноді тихо повертаючи іншу підсумкову суму всередині загалом успішної відповіді.
Небезпечний другий варіант. Якщо ваш код читає підтвердження, зберігає бронювання і списує з клієнта суму, яку той бачив, різниця йде з вашої маржі або пізніше з ADM. Правило просте: порівнюйте підсумок, підтверджений постачальником, із підсумком, який прийняв клієнт, щоразу, у коді, до списання оплати.
Що робити за розбіжності, залежить від розміру різниці та від того, хто її несе. Кілька копійок округлення між валютами — допуск, який ви задаєте один раз. Усе більше повертається клієнтові як нова ціна з явною кнопкою згоди. Ніколи не поглинайте це автоматично й ніколи не списуйте автоматично.
Збій другий: заброньовано, але квиток не виписано
Існування PNR — це не те саме, що існування квитка. Багато сценаріїв спершу створюють бронювання, а е-квиток виписують окремим кроком, між якими є ліміт часу. Якщо оплата пройшла, а виписка не вдалася, ви тримаєте гроші клієнта і бронювання, яке спливе за власним годинником.
Збій рідко буває гучним. Виклик виписки повертає помилку чи таймаут, а бронювання лишається в стані, який ваша база називає «сплачено», тоді як постачальник досі каже «утримується». Тим часом ліміт на виписку спливає, і на відміну від вашої черги підтримки авіакомпанія не чекає.
Розглядайте це як окремий стан, а не варіант успіху чи невдачі. Бронювання потребує щонайменше таких станів: створено, утримується, оплату знято, виписується, виписано, невдало-й-підлягає-поверненню. «Оплату знято, виписується» — стан, якому потрібен таймер: коли бронювання сидить там надто довго, завдання має заново прочитати бронювання в постачальника й ухвалити рішення, не чекаючи, поки людина помітить. Рішення дешеве, коли ви знаєте ліміт часу постачальника, бо він підказує, як довго можна безпечно повторювати спроби, перш ніж повертати гроші.
Збій третій: таймаут із невідомим результатом
Це той самий тікет четверга ввечері. Запит пішов; відповіді не було; з'єднання обірвалося або шлюз здався. Постачальник міг обробити його повністю, частково або зовсім ні.
Спокуса — повторити. Не повторюйте наосліп виклик створення бронювання, бо друга спроба може створити друге бронювання, а дублікат — це реальні витрати: два утримані місця, можливо два виписані квитки, суперечка про повернення за одним із них.
Безпечний порядок: зупинитися, прочитати, тоді вирішувати. Зупиніть клієнтський сценарій чесним станом «підтверджуємо ваше бронювання». Прочитайте бік постачальника, знайшовши бронювання за референсом, який ви згенерували до виклику (тому ви спершу створюєте власний клієнтський референс і надсилаєте його, якщо постачальник це дозволяє). Лише тоді вирішуйте: знайдено — продовжуйте з реального стану; не знайдено після власного вікна обробки постачальника — можна безпечно повторити один раз.
Якщо постачальник не дає шукати за вашим референсом, шукайте за прізвищем пасажира, маршрутом і датою у вузькому вікні та вважайте збіг знайденим. Негарно, але набагато дешевше за дублікат.
Таблиця рішень, із якою можна не погодитися
| Що ви бачите | Що ви знаєте | Що робити | Чого не робити |
|---|---|---|---|
| Постачальник повертає «тариф змінено» | Нічого не заброньовано | Показати нову суму, попросити згоду, повторити створення | Повторювати зі старою ціною в надії, що пройде |
| Успіх, але сума відрізняється від прийнятої клієнтом | Існує бронювання за новою ціною | Утримати оплату, запитати клієнта, скасувати бронювання, якщо він відмовиться | Зняти стару суму й проковтнути різницю |
| Оплату знято, виклик виписки повертає помилку | PNR існує, статус квитка невідомий | Перечитати бронювання, повторити виписку в межах ліміту, після нього повернути гроші | Позначити бронювання як невдале й забути про PNR |
| Таймаут під час створення | Результат невідомий | Шукати за власним референсом, потім продовжити або повторити раз | Негайно повторювати наосліп |
| Таймаут під час скасування | Ви можете ще відповідати за сегмент | Перечитати статус, перш ніж щось казати клієнтові | Показати «скасовано», бо клік відбувся |
Один рядок, із яким можна сперечатися: деякі команди повертають гроші після першої помилки виписки, щоб заспокоїти клієнта. Для дешевих квитків це виправдано, для дорогих — погана звичка, бо можна втратити тариф, який за хвилину ще вдалося б урятувати.
Скільки коштує помилка
Кожен збій має свій рахунок. Пропущена зміна ціни — втрачена маржа на кожному зачепленому бронюванні, яку часто помічають лише під час звірки. Випадок «заброньовано, не виписано» — клієнт, що приходить в аеропорт із простроченим бронюванням і списанням на картці: чарджбек і репутаційна проблема водночас. Сліпий повтор після таймауту — дубль бронювання, а авіакомпанії перевіряють дублі; їхня серія — те, що потрапляє в ADM.
Нічого з цього не екзотика. Це непоказна сантехніка, що відділяє демо від того, що можна залишити працювати на вихідні.
Побудуйте звірочне завдання, поки воно не знадобилося
Усі три збої закінчуються однаково: ваша база й база постачальника розходяться. Тож напишіть завдання, що їх порівнює, до першого інциденту, а не після. Нічний запуск — мінімум; кожні кілька хвилин для всього в перехідному стані — краще. Воно виводить бронювання, що застрягли в утриманні, виписці чи невідомому стані, питає постачальника, що той думає, і або виправляє запис, або створює тікет із доданими доказами.
Зберігайте кожен запит і відповідь викликів бронювання, зокрема таймаути, разом з надісланим референсом. Коли клієнт оскаржує списання, цей лог — ваш аргумент. Він також робить чесною розмову про затримки: див. що можна й чого не можна виправити в затримках API, щоб зрозуміти, чому таймаути — це реальність, а не помилка, яку треба викорінити.
Якщо ви ще вирішуєте, як підключати саме з'єднання з постачальником, огляд у інтеграції API бронювання авіаквитків описує порядок викликів, який передбачає ця стаття. А якщо хочете обговорити, як ці стани відповідають нашим API авіаквитків і готелів, доступ починається з розмови: дивіться сторінку API для подорожей.