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

Картата на дъската гласи „добави полети". Вече сте доставили интеграция с платежен доставчик, с куриерски тарифи, може би и с карти, и мисловният модел, който носите, е очевидният: търсене, показване на резултати, теглене от картата, готово. После първата истинска резервация се връща на различна цена от тази на страницата с резултати, втората изтича по timeout и никой не може да ви каже дали клиентът има място, а някой от оперативния екип пита защо има резервация, но няма билет. Една интеграция на API за резервация на полети отвън изглежда като checkout на онлайн магазин. Отдолу е разпределена транзакция към системи, проектирани дълго преди REST, и повечето изненади идват точно от тази пропаст.
Текстът е написан за разработчика, който никога не е виждал PNR. Не става дума за endpoint-ите на конкретен доставчик; имената се менят от доставчик на доставчик, формата — не.
Последователността от извиквания зад интеграция на API за резервация на полети
Почти всяко API за полети, както и да нарича методите си, минава през едни и същи четири стъпки. Правилното очертаване на границите между тях е по-голямата част от работата.
| Стъпка | Какво ви дава | Какво трябва да съхраните | Какво се обърква |
|---|---|---|---|
| Търсене | Маршрути с цена и непрозрачен ключ на оферта или тарифа | Нищо трайно — резултатите остаряват бързо | Приемате цената за окончателна; ключът изтича преди checkout |
| Остойностяване / проверка | Потвърдената цена, тарифните правила, багажа, понякога задължителни полета за пътника | Проверената оферта и срока ѝ | Цената се промени; класата се изчерпа; правилата се различават от показаното |
| Резервация | Резервация — PNR — с record locator и краен срок за издаване | Вашата собствена референция, locator-а, срока, точните данни на пътниците, които сте изпратили | Timeout без отговор; дублирани PNR; отхвърлени имена |
| Издаване | Издадени номера на е-билети; тук парите реално се ангажират | Всеки номер на билет, обвързан с пътника и сегмента, към които принадлежи | Частично издаване; резервацията е анулирана от авиокомпанията, защото срокът е изтекъл |
Редът, с който хората спорят, е третият, защото много API-та позволяват резервация и издаване в едно извикване. Използвайте го, ако искате. В света на авиокомпанията двете неща остават отделни: PNR може да съществува без билет, а издаването може да се провали, след като PNR е създаден. Комбинираният endpoint просто скрива момента, в който едното е успяло, а другото — не, така че в модела ви на данни трябва да има място за това състояние.
Забележете и какво търсенето не връща: обещание. То е реклама. Стъпката на остойностяване е офертата, и едва билетът е продажбата.
Защо цената, която сте намерили, не е цената, която резервирате
Уеб разработчиците очакват каталог. Инвентарът на авиокомпаниите не е такъв. Един полет се продава в класи на резервация, всяка от които е кофа места на дадена тарифа, и авиокомпанията отваря и затваря тези кофи непрекъснато, докато полетът се пълни. Резултатите от търсенето се сглобяват бързо от наличност, която вече може леко да изостава; докато потребителят въведе два паспорта, най-евтината кофа за този полет може да се е затворила. Когато стъпката на остойностяване се изпълни, тя пита отново и честният отговор понякога е по-висок.
Таксите добавят собственото си отклонение. Те се преизчисляват при остойностяването за конкретните пътници и маршрут, а дете или бебе се остойностява различно от възрастния, който търсенето е предположило. Валутното превалутиране, ако магазинът ви показва левове или евро, а доставчикът котира в друга валута, е още едно място, където числото се мести.
Последствието за дизайна е просто и често се пропуска: никога не таксувайте по цената от търсенето. Изпълнете стъпката на остойностяване преди плащане, сравнете и ако сумата се е променила, покажете новото число и попитайте. Каквато и надценка да прилагате, тя трябва да се преизчисли върху преостойностената тарифа, а не да се пренесе от страницата с резултати — логиката е същата, през която минава една агенция, когато определя стратегия за надценка онлайн, и се чупи по същия начин, когато основата се мести под нея.
Идемпотентност и какво означава timeout по време на резервация
Това е разделът, който да прочетете два пъти.
Когато извикване за резервация изтече по timeout, не знаете какво се е случило. Заявката може никога да не е пристигнала. Може да е пристигнала и да се е провалила. Или — случаят, който боли — пристигнала е, доставчикът е създал PNR при авиокомпанията и отговорът се е загубил по пътя обратно към вас. За вашия код трите изглеждат еднакво. За авиокомпанията третият е жива резервация, която държи места на името на вашия клиент.
Рефлексът от други интеграции е да опитате отново. Тук сляп повторен опит може да произведе втори PNR за същите пътници на същия полет. Авиокомпаниите третират дублираните резервации като нарушение на политиката; в зависимост от превозвача и споразуменията на агенцията последствието варира от автоматично анулиране на едната или двете резервации до дебитно известие — ADM — изпратено на този, който ги е издал. Агенцията, която го получи, ще иска да знае защо системата ви е резервирала два пъти.
Какво работи, приблизително в този ред:
- Създайте собствена референция на резервацията преди извикването навън, запазете я и я изпратете със заявката навсякъде, където API-то приема клиентска референция. Ако API-то поддържа idempotency key, използвайте го; ако не, референцията ви все пак е това, което ви позволява да намерите резервацията после.
- Моделирайте неизвестното състояние изрично. Чакаща, потвърдена, неуспешна — и неизвестна. Timeout премества резервацията в неизвестна, не в неуспешна.
- Разрешавайте неизвестното с питане, не с повтаряне. Извлечете по референцията си или изведете последните резервации за тези пътници, преди да решите дали да опитате отново.
- Пуснете задача за съгласуване, която обхожда всичко все още неизвестно, сравнява го с докладваното от доставчика и насочва това, което не може да уреди, към опашка за човек, вместо да гадае.
Timeout при издаване е същият проблем, но с пари отгоре. Ако изтеглите от картата преди издаването и издаването увисне, имате платил клиент и вероятно никакъв билет. Ако издадете преди тегленето и тегленето се провали, сте издали документ, който някой трябва да плати на авиокомпанията. Първо оторизация на картата, после издаване, после теглене при успех е обичайната форма — въпросът е да го решите съзнателно, а не да го откриете в продукция.
Понятията от туристическия бранш, които изненадват уеб разработчиците
Нито едно от тях не е трудно. Всяко е струвало на някого седмица, защото не е знаел, че съществува.
PNR не е билет
PNR е записът на резервацията: пътници, сегменти, контакти, краен срок. Билетът е платеният документ, който дава на пътника право да лети. Неиздаден PNR изтича на крайния си срок за издаване и местата се връщат в продажба, понякога безшумно от ваша гледна точка.
Имената са почти неизменими
След издаване повечето тарифи не позволяват промяна на името отвъд дребна корекция, а какво се брои за дребно, варира по авиокомпании. Името трябва да съвпада с документа за пътуване. Събирайте фамилия и собствени имена отделно, не оставяйте свободно въведена титла да изтече в поле за име и валидирайте преди извикването за резервация, не след него.
Типовете пътници се остойностяват, не са декорация
Възрастен, дете и бебе са тарифни типове, а възрастта, която решава кой важи, обикновено е възрастта на датата на пътуване, не на датата на резервация. Бебе в скута обикновено не заема място и често може да пътува само с възрастен. Грешен тип означава, че остойностяването или се проваля, или дава грешна тарифа.
Часовете са местни, а сегментите не са отсечки
Часовете на излитане и кацане се дават в местното време на всяко летище. Не ги конвертирайте в часовата зона на потребителя за показване и не изчислявайте продължителности, като ги изваждате без отместванията. Едно пътуване съдържа сегменти; сегмент с техническо кацане съдържа повече от една отсечка. Интерфейсът и данните ви трябва да са съгласни кое от двете е „престой".
След продажбата се случват неща
Авиокомпаниите променят разписанията след издаването на билетите. Резервация, която е била вярна при издаването, седмици по-късно може да показва нов час, нов номер на полет или прекъсната връзка, и в зависимост от доставчика научавате чрез известие, опашка или повторно извличане на резервацията. Планирайте резервацията да се променя, след като сте спрели да я гледате.
Void не е възстановяване
Малко след издаването обикновено има прозорец, в който билетът може да бъде анулиран (void), сякаш никога не е съществувал. След този прозорец е възможно само възстановяване по тарифните правила, което може да струва неустойка или да не върне нищо. Прозорецът и правилата му принадлежат на доставчика и на споразумението за издаване; прочетете ги, преди да построите бутон „отказ".
Какво струва грешката
Провалите в интеграция за полети са скъпи по специфичен начин: стоварват се върху хора, не върху логове. Дублирана резервация се превръща в обаждане до авиокомпанията и вероятно в известие срещу сметката на агенцията. Таксуван клиент без билет се превръща във възстановяване, оплакване и риск от chargeback. Билет, издаден без успешно плащане, се превръща в дълг към авиокомпанията, който някой трябва да уреди. Промяна в разписанието, която никой не е обработил, се превръща в пътник на летището за полет, който е излетял по-рано.
Нищо от това не се появява в тест на щастливия път. Напишете първо нещастните пътища: timeout при резервация, покачилата се цена, издаването, провалило се след PNR, void след успешно плащане. Ако те са обработени, щастливият път е лесната част.
Тестване срещу API за полети
Тестовите среди на доставчиците са полезни и непълни. Обикновено са по-тихи от продукцията, така че изчерпаните класи и промените в цената са по-редки, а някои изобщо не симулират timeout. Използвайте ги за формата на извикванията и грешките при валидация, после планирайте контролирано изпълнение в продукция с истински резервации, които анулирате в прозореца — като оперативният екип знае, че го правите.
Дали изобщо да интегрирате е отделен въпрос. Ако това, което реално ви трябва, е витрина, а не суров инвентар в собствената ви система, компромисът е описан в white label или своя резервационна система, и същото разсъждение важи за B2B портал за субагенти. Ако наистина искате инвентара в собствения си код, платформата предоставя API за полети и хотели, а достъпът започва с разговор за вашия случай на употреба, а не със самообслужващ се ключ — което е и правилният момент да зададете всеки от въпросите по-горе.