Přeskočit na obsah
Blog

Integrace API pro rezervaci letenek: co dokumentace zamlčí

Redakce Tekravel
Napsáno s pomocí AI

Na kartě v backlogu stojí „přidat letenky". Dodali jste už integraci plateb, dopravného, možná i map, a myšlenkový model, který si přinášíte, je ten nejzřejmější: vyhledat, zobrazit výsledky, strhnout kartu, hotovo. Pak se první skutečná rezervace vrátí za jinou cenu, než byla na stránce s výsledky, druhá spadne do timeoutu a nikdo vám nedokáže říct, jestli zákazník sedadlo má, a někdo z provozu se ptá, proč existuje rezervace, ale žádná letenka. Integrace API pro rezervaci letenek zvenku vypadá jako e-commerce checkout. Pod povrchem je to distribuovaná transakce proti systémům navrženým dávno před RESTem a většina překvapení pramení právě z této mezery.

Text je psán pro vývojáře, který nikdy neviděl PNR. Nejde o endpointy konkrétního dodavatele; názvy se mezi poskytovateli mění, tvar ne.

Posloupnost volání, která stojí za integrací API pro rezervaci letenek

Téměř každé letové API, ať už své metody pojmenovává jakkoli, prochází stejnými čtyřmi kroky. Správně mezi nimi narýsovat hranice je většina práce.

KrokCo vám dáCo musíte uložitCo se pokazí
VyhledáníItineráře s cenou a neprůhledným klíčem nabídky nebo tarifuNic trvalého — výsledky rychle zastarávajíBerete cenu jako konečnou; klíč vyprší před checkoutem
Nacenění / ověřeníPotvrzenou cenu, tarifní podmínky, zavazadla, někdy povinná pole cestujícíchOvěřenou nabídku a její expiraciCena se změnila; třída se vyprodala; podmínky se liší od toho, co jste zobrazili
RezervaceRezervaci — PNR — s record locatorem a lhůtou pro vystaveníVlastní referenci, locator, lhůtu, přesná data cestujících, která jste odeslaliTimeout bez odpovědi; duplicitní PNR; zamítnutá jména
VystaveníVystavená čísla e-ticketů; tady se peníze skutečně zavazujíKaždé číslo letenky, přiřazené k cestujícímu a segmentuČástečné vystavení; aerolinka zrušila rezervaci, protože lhůta vypršela

Řádek, se kterým se lidé přou, je ten třetí, protože mnohá API dovolují rezervovat a vystavit v jediném volání. Klidně to použijte. V očích aerolinky zůstávají obě věci oddělené: PNR může existovat bez letenky a vystavení může selhat poté, co PNR vzniklo. Kombinovaný endpoint jen skrývá okamžik, kdy jedno uspělo a druhé ne, takže váš datový model musí mít pro tento stav místo i tak.

Všimněte si také, co vyhledání nevrací: slib. Je to inzerát. Krok nacenění je nabídka a teprve letenka je prodej.

Proč cena, kterou jste vyhledali, není cena, kterou rezervujete

Weboví vývojáři očekávají katalog. Inventář aerolinek katalog není. Let se prodává v rezervačních třídách, každá je koš sedadel za určitý tarif, a aerolinka tyto koše průběžně otevírá a zavírá, jak se let plní. Výsledky vyhledávání se rychle sestavují z dostupnosti, která už může být trochu pozadu; než uživatel opíše dva pasy, nejlevnější koš na daném letu se mohl zavřít. Když proběhne krok nacenění, zeptá se znovu a upřímná odpověď je někdy vyšší.

Daně přidávají vlastní posun. Při nacenění se přepočítávají pro konkrétní cestující a trasu a dítě nebo kojenec se nacení jinak než dospělý, kterého vyhledání předpokládalo. Měnový přepočet, pokud váš e-shop zobrazuje koruny a dodavatel kótuje v eurech nebo dolarech, je další místo, kde se číslo pohne.

Důsledek pro návrh je prostý a často se přeskakuje: nikdy neúčtujte vyhledanou cenu. Před platbou spusťte krok nacenění, porovnejte, a pokud se částka změnila, ukažte nové číslo a zeptejte se. Jakoukoli přirážku, kterou uplatňujete, je třeba přepočítat z nově naceněného tarifu, ne přenést ze stránky s výsledky — logika je stejná, jakou cestovní kancelář řeší při nastavování strategie přirážky online, a láme se stejným způsobem, když se pod ní pohne základ.

Idempotence a co znamená timeout při rezervaci

Tuhle část si přečtěte dvakrát.

Když rezervační volání spadne do timeoutu, nevíte, co se stalo. Požadavek možná nikdy nedorazil. Možná dorazil a selhal. Nebo — a to je případ, který bolí — dorazil, dodavatel u aerolinky vytvořil PNR a odpověď se cestou zpět ztratila. Pro váš kód vypadají všechny tři případy totožně. Pro aerolinku je ten třetí živá rezervace, která drží sedadla na jméno vašeho zákazníka.

Reflex z jiných integrací je zkusit to znovu. Tady může slepý retry vytvořit druhé PNR pro stejné cestující na stejném letu. Aerolinky berou duplicitní rezervace jako porušení pravidel; podle dopravce a smluv agentury sahá následek od automatického zrušení jedné nebo obou rezervací až po debetní nótu — ADM — zaslanou tomu, kdo je vystavil. Agentura, které přijde, bude chtít vědět, proč váš systém rezervoval dvakrát.

Co funguje, zhruba v tomto pořadí:

  • Vytvořte vlastní referenci rezervace ještě před voláním ven, uložte ji a pošlete s požadavkem všude, kde API přijímá klientskou referenci. Pokud API podporuje idempotency key, použijte ho; pokud ne, vaše reference je stále to, co vám dovolí rezervaci později dohledat.
  • Modelujte neznámý stav explicitně. Čekající, potvrzená, neúspěšná — a neznámá. Timeout přesouvá rezervaci do stavu neznámá, ne neúspěšná.
  • Neznámý stav řešte dotazem, ne opakováním. Dohledejte podle své reference nebo vypište nedávné rezervace pro dané cestující, než se rozhodnete, zda to zkusit znovu.
  • Spusťte úlohu rekonciliace, která projde vše, co je stále neznámé, porovná to s tím, co hlásí dodavatel, a co nedokáže vyřešit, pošle do fronty pro člověka, místo aby hádala.

Timeouty při vystavení jsou stejný problém s penězi navrch. Pokud strhnete kartu před vystavením a vystavení se zasekne, máte zaplaceného zákazníka a možná žádnou letenku. Pokud vystavíte před stržením a stržení selže, vystavili jste doklad, který někdo musí aerolince zaplatit. Nejprve autorizovat kartu, pak vystavit, pak při úspěchu strhnout je obvyklý tvar — jde o to rozhodnout to vědomě, ne to objevit v produkci.

Pojmy z cestovní branže, které zaskočí webové vývojáře

Žádný z nich není těžký. Každý už někoho stál týden, protože nevěděl, že existuje.

PNR není letenka

PNR je rezervační záznam: cestující, segmenty, kontakty, lhůta. Letenka je zaplacený doklad, který cestujícího opravňuje letět. Nevystavené PNR vyprší ve lhůtě pro vystavení a sedadla se vrátí do prodeje, z vašeho pohledu někdy úplně potichu.

Jména jsou prakticky neměnná

Po vystavení většina tarifů nedovoluje změnu jména nad rámec drobné opravy a co se počítá za drobnou, se liší podle aerolinky. Jméno musí odpovídat cestovnímu dokladu. Sbírejte příjmení a křestní jména zvlášť, nenechte volně psaný titul proniknout do pole se jménem a validujte před rezervačním voláním, ne po něm.

Typy cestujících se naceňují, nejsou dekorace

Dospělý, dítě a kojenec jsou tarifní typy a věk, který rozhoduje o tom, který platí, je obvykle věk v den cesty, ne v den rezervace. Kojenec na klíně zpravidla nezabírá sedadlo a smí cestovat jen s dospělým. Špatný typ znamená, že nacenění buď selže, nebo vrátí špatný tarif.

Časy jsou místní a segmenty nejsou úseky

Časy odletu a příletu se uvádějí v místním čase každého letiště. Nepřevádějte je pro zobrazení do časového pásma uživatele a nepočítejte délku letu jejich odečtením bez posunů. Cesta obsahuje segmenty; segment s technickým mezipřistáním obsahuje více než jeden úsek. Vaše UI a vaše data se musí shodnout na tom, co z toho je „mezipřistání".

Po prodeji se věci dějí dál

Aerolinky mění letové řády i po vystavení letenek. Rezervace, která byla při vystavení správná, může o několik týdnů později ukazovat nový čas, nové číslo letu nebo rozpadlý přestup, a podle dodavatele se to dozvíte notifikací, přes frontu nebo opětovným načtením rezervace. Počítejte s tím, že se rezervace změní poté, co jste se na ni přestali dívat.

Void není refundace

Krátce po vystavení obvykle existuje okno, ve kterém lze letenku stornovat (void), jako by nikdy neexistovala. Po tomto okně je možná jen refundace podle tarifních podmínek, která může stát penále nebo nevrátit vůbec nic. Okno i jeho pravidla patří dodavateli a smlouvě o vystavování; přečtěte si je, než postavíte tlačítko „zrušit".

Co vás chyba stojí

Selhání v letové integraci jsou drahá specifickým způsobem: dopadají na lidi, ne do logů. Duplicitní rezervace se mění v telefonát aerolince a možná v nótu na vrub účtu agentury. Zákazník s odečtenou platbou a bez letenky se mění v refundaci, stížnost a riziko chargebacku. Letenka vystavená bez úspěšné platby se mění v dluh vůči aerolince, který musí někdo vyrovnat. Změna letového řádu, kterou nikdo nezpracoval, se mění v cestujícího na letišti u letu, který odletěl dřív.

Nic z toho se neukáže v testu šťastné cesty. Napište nejdřív ty nešťastné: timeout při rezervaci, cenu, která vzrostla, vystavení, které selhalo po vzniku PNR, void po úspěšné platbě. Pokud jsou ošetřené, šťastná cesta je ta snadná část.

Testování proti letovému API

Testovací prostředí dodavatelů jsou užitečná a neúplná. Bývají klidnější než produkce, takže vyprodané třídy a změny cen jsou vzácnější, a některá vůbec nesimulují timeouty. Použijte je pro tvar volání a validační chyby a pak naplánujte kontrolovaný běh v produkci se skutečnými rezervacemi, které v daném okně stornujete — s vědomím provozu, že to děláte.

Zda vůbec integrovat, je samostatná otázka. Pokud ve skutečnosti potřebujete prodejní web, a ne surový inventář ve vlastním systému, kompromis popisuje článek white label, nebo vlastní rezervační systém a stejná úvaha platí pro B2B portál pro subagenty. Pokud inventář ve vlastním kódu opravdu chcete, platforma nabízí API pro lety a hotely a přístup začíná rozhovorem o vašem případu použití, ne samoobslužným klíčem — což je zároveň ta správná chvíle položit každou z otázek výše.

Redakce Tekravel

Rubrika cestovních technologií

Rubrika cestovních technologií Tekravel píše pro obor: majitele agentur, konsolidátory a vývojáře, kteří je integrují. Každý článek je před vydáním ověřen na platformě, kterou popisuje.