Repülőjegy-foglalási API-integráció: amit a dokumentáció elhallgat

A táblán lévő kártyán ez áll: „repülőjegyek hozzáadása". Szállítottatok már fizetési integrációt, szállítási díjakat, talán térképet is, és a magatokkal hozott gondolati modell a kézenfekvő: keresés, találatok megjelenítése, kártya terhelése, kész. Aztán az első valódi foglalás más áron jön vissza, mint ami a találati oldalon volt, a második timeoutba fut, és senki nem tudja megmondani, van-e az ügyfélnek ülése, az üzemeltetésről pedig valaki megkérdezi, miért van foglalás, de nincs jegy. A repülőjegy-foglalási API-integráció kívülről webshop-pénztárnak látszik. Alatta elosztott tranzakció zajlik olyan rendszerek felé, amelyeket jóval a REST előtt terveztek, és a meglepetések többsége pontosan ebből a résből fakad.
Ez a szöveg annak a fejlesztőnek szól, aki még sosem látott PNR-t. Nem egy konkrét szolgáltató végpontjairól szól; a nevek szolgáltatónként változnak, a forma nem.
A hívási sorrend egy repülőjegy-foglalási API-integráció mögött
Szinte minden repülőjegy-API, bárhogy nevezi is a metódusait, ugyanazon a négy lépésen megy végig. A köztük lévő határok helyes meghúzása a munka nagyobbik része.
| Lépés | Mit ad | Mit kell tárolni | Mi romlik el |
|---|---|---|---|
| Keresés | Útvonalak árral és egy átlátszatlan ajánlat- vagy viteldíjkulccsal | Semmi tartósat — a találatok gyorsan elavulnak | Véglegesnek veszitek az árat; a kulcs a pénztár előtt lejár |
| Árazás / ellenőrzés | A megerősített árat, a viteldíjszabályokat, a poggyászt, néha a kötelező utasmezőket | Az ellenőrzött ajánlatot és annak lejáratát | Változott az ár; elfogyott az osztály; a szabályok eltérnek attól, amit mutattatok |
| Foglalás | Egy foglalást — a PNR-t — record locatorral és jegykiállítási határidővel | A saját hivatkozásotokat, a locatort, a határidőt, a pontosan elküldött utasadatokat | Timeout válasz nélkül; dupla PNR-ek; elutasított nevek |
| Jegykiállítás | Kiállított e-jegy számokat; itt kötődik le ténylegesen a pénz | Minden jegyszámot, az utashoz és a szegmenshez rendelve, amelyhez tartozik | Részleges kiállítás; a légitársaság törli a foglalást, mert lejárt a határidő |
A sor, amivel vitatkozni szoktak, a harmadik, mert sok API egyetlen hívásban enged foglalni és jegyet kiállítani. Használjátok, ha akarjátok. A két dolog a légitársaság világában továbbra is külön áll: PNR létezhet jegy nélkül, és a jegykiállítás elbukhat azután, hogy a PNR létrejött. A kombinált végpont csak elrejti azt a pillanatot, amikor az egyik sikerült, a másik nem, úgyhogy az adatmodelletekben akkor is kell hely ennek az állapotnak.
Figyeljétek meg azt is, mit nem ad vissza a keresés: ígéretet. A keresés hirdetés. Az árazási lépés az ajánlat, és csak a jegy az eladás.
Miért nem a keresett ár az, amit lefoglaltok
A webfejlesztő katalógust vár. A légitársasági készlet nem az. Egy járatot foglalási osztályokban adnak el, mindegyik egy vödörnyi ülés egy adott viteldíjon, és a légitársaság folyamatosan nyitja és zárja ezeket a vödröket, ahogy a járat telik. A keresési találatok gyorsan állnak össze olyan elérhetőségből, amely már eleve kissé elmaradhat; mire a felhasználó begépel két útlevelet, az adott járat legolcsóbb vödre bezárulhatott. Amikor az árazási lépés fut, újra megkérdezi, és az őszinte válasz néha magasabb.
Az adók hozzáadják a saját elcsúszásukat. Árazáskor újraszámolják őket a pontos utasokra és útvonalra, és egy gyermek vagy csecsemő másképp árazódik, mint a felnőtt, akit a keresés feltételezett. A devizaváltás, ha a webshop forintban mutat, miközben a szolgáltató euróban vagy dollárban áraz, még egy hely, ahol a szám elmozdul.
A tervezési következmény egyszerű és gyakran kimarad: soha ne terheljétek a keresési árat. Futtassátok az árazási lépést fizetés előtt, hasonlítsátok össze, és ha változott az összeg, mutassátok az újat és kérdezzetek. Bármilyen árrést is alkalmaztok, azt az újraárazott viteldíjon kell újraszámolni, nem a találati oldalról átvinni — ugyanaz a logika, amit egy utazási iroda végiggondol, amikor online árrésstratégiát állít fel, és ugyanúgy törik el, amikor az alap elmozdul alatta.
Idempotencia, és mit jelent egy timeout foglalás közben
Ezt a részt kétszer érdemes elolvasni.
Amikor egy foglalási hívás timeoutba fut, nem tudjátok, mi történt. Lehet, hogy a kérés sosem ért oda. Lehet, hogy odaért és elbukott. Vagy — és ez a fájó eset — odaért, a szolgáltató létrehozta a PNR-t a légitársaságnál, és a válasz veszett el visszafelé. A kódotok számára mindhárom pontosan ugyanúgy néz ki. A légitársaság számára a harmadik egy élő foglalás, amely üléseket tart fenn az ügyfeletek nevén.
A más integrációkból hozott reflex az újrapróbálás. Itt egy vak újrapróbálás második PNR-t hozhat létre ugyanazoknak az utasoknak ugyanarra a járatra. A légitársaságok a dupla foglalást szabályszegésként kezelik; a légitársaságtól és az iroda megállapodásaitól függően a következmény az egyik vagy mindkét foglalás automatikus törlésétől a terhelési értesítőig — ADM-ig — terjed, amelyet annak küldenek, aki kiállította őket. Az iroda, amely megkapja, tudni akarja majd, miért foglalt a rendszeretek kétszer.
Ami működik, nagyjából ebben a sorrendben:
- Hozzátok létre a saját foglalási hivatkozásotokat a kifelé hívás előtt, mentsétek el, és küldjétek a kéréssel mindenhol, ahol az API elfogad ügyfélhivatkozást. Ha az API támogat idempotency key-t, használjátok; ha nem, a hivatkozásotok akkor is az, amivel utólag megkereshetitek a foglalást.
- Modellezzétek az ismeretlen állapotot explicit módon. Függő, megerősített, sikertelen — és ismeretlen. A timeout a foglalást ismeretlenbe viszi, nem sikertelenbe.
- Az ismeretlent kérdezéssel oldjátok fel, ne ismétléssel. Kérdezzétek le a saját hivatkozásotokkal, vagy listázzátok a friss foglalásokat ezekre az utasokra, mielőtt eldöntitek, próbáljátok-e újra.
- Futtassatok egyeztető feladatot, amely végigsöpri mindazt, ami még ismeretlen, összeveti a szolgáltató jelentésével, és amit nem tud eldönteni, emberi sorba teszi találgatás helyett.
A jegykiállítási timeout ugyanez a probléma pénzzel megfejelve. Ha a kártyát a kiállítás előtt terhelitek, és a kiállítás beragad, van egy fizetett ügyfeletek és esetleg nincs jegy. Ha a terhelés előtt állítotok ki jegyet, és a terhelés elbukik, kiállítottatok egy okmányt, amelyet valakinek ki kell fizetnie a légitársaságnak. Előbb kártya-előengedélyezés, aztán kiállítás, majd siker esetén terhelés a szokásos forma — a lényeg, hogy tudatosan döntsétek el, ne a termelésben fedezzétek fel.
Az utazási szakma fogalmai, amelyek meglepik a webfejlesztőket
Egyik sem nehéz. Mindegyik került már valakinek egy hétbe, mert nem tudta, hogy létezik.
A PNR nem jegy
A PNR a foglalási rekord: utasok, szegmensek, elérhetőségek, egy határidő. A jegy a kifizetett okmány, amely feljogosítja az utast a repülésre. A jegy nélküli PNR a jegykiállítási határidőn lejár, és az ülések visszakerülnek az értékesítésbe, a ti szemszögetekből néha teljesen csendben.
A nevek szinte megváltoztathatatlanok
Jegykiállítás után a legtöbb viteldíj nem enged névmódosítást kisebb javításon túl, és hogy mi számít kisebbnek, légitársaságonként eltér. A névnek egyeznie kell az úti okmánnyal. A vezetéknevet és a keresztneveket külön gyűjtsétek, ne engedjétek, hogy szabad szöveges megszólítás szivárogjon a névmezőbe, és a foglalási hívás előtt validáljatok, ne utána.
Az utastípusok árazódnak, nem dekorációk
Felnőtt, gyermek és csecsemő viteldíjtípusok, és az életkor, amely eldönti, melyik érvényes, általában az utazás napján betöltött kor, nem a foglalás napján. Az ölben utazó csecsemő jellemzően nem foglal ülést, és gyakran csak felnőttel utazhat. Rossz típus esetén az árazás vagy elbukik, vagy rossz viteldíjat ad.
Az idők helyiek, és a szegmens nem szakasz
Az indulási és érkezési időket minden repülőtér saját helyi idejében adják meg. Ne váltsátok át őket megjelenítéshez a felhasználó időzónájára, és ne számoljatok időtartamot úgy, hogy eltolás nélkül kivonjátok őket egymásból. Egy utazás szegmenseket tartalmaz; egy technikai leszállást tartalmazó szegmens több szakaszból áll. A felületnek és az adatoknak egyet kell érteniük abban, melyik számít „megállónak".
Az eladás után is történnek dolgok
A légitársaságok a jegyek kiállítása után is módosítják a menetrendet. Egy kiállításkor helyes foglalás hetekkel később új időpontot, új járatszámot vagy megszakadt átszállást mutathat, és szolgáltatótól függően értesítésből, sorból vagy a foglalás újbóli lekérdezéséből tudjátok meg. Tervezzetek arra, hogy a foglalás azután is változik, hogy már nem nézitek.
A void nem visszatérítés
Röviddel a kiállítás után általában van egy ablak, amelyben a jegy semmissé tehető (void), mintha sosem létezett volna. Ezen ablak után csak a viteldíjszabályok szerinti visszatérítés lehetséges, amely kötbérbe kerülhet vagy semmit nem ad vissza. Az ablak és szabályai a szolgáltatóhoz és a kiállítási megállapodáshoz tartoznak; olvassátok el őket, mielőtt „lemondás" gombot építetek.
Mibe kerül, ha elrontjátok
A repülőjegy-integráció hibái sajátosan drágák: embereken csattannak, nem logokban. A dupla foglalásból telefon lesz a légitársasághoz és esetleg terhelés az iroda számlájára. A megterhelt, de jegy nélküli ügyfélből visszatérítés, panasz és chargeback-kockázat. A sikeres fizetés nélkül kiállított jegyből tartozás a légitársaság felé, amelyet valakinek rendeznie kell. A senki által nem kezelt menetrendváltozásból utas a repülőtéren egy korábban elindult járathoz.
Ezek egyike sem jelenik meg boldog úton végzett tesztben. Előbb a boldogtalan utakat írjátok meg: a foglalás közbeni timeoutot, az emelkedett árat, a PNR után elbukó jegykiállítást, a sikeres fizetés utáni voidot. Ha ezek kezelve vannak, a boldog út a könnyű rész.
Tesztelés repülőjegy-API ellen
A szolgáltatói tesztkörnyezetek hasznosak és hiányosak. Általában csendesebbek a termelésnél, így az elfogyott osztályok és árváltozások ritkábbak, és némelyik egyáltalán nem szimulál timeoutot. Használjátok őket a hívások formájához és a validációs hibákhoz, aztán tervezzetek egy kontrollált futtatást a termelésben valódi foglalásokkal, amelyeket az ablakon belül semmissé tesztek — úgy, hogy az üzemeltetés tudja, hogy ezt teszitek.
Az, hogy egyáltalán integráljatok-e, külön kérdés. Ha valójában értékesítési felületre van szükségetek, nem nyers készletre a saját rendszeretekben, a kompromisszumot a white label vagy saját foglalási rendszer cikk fejti ki, és ugyanez az érvelés érvényes egy alügynököknek szóló B2B portálra is. Ha tényleg a saját kódotokban akarjátok a készletet, a platform repülőjegy- és szálloda-API-kat tesz elérhetővé, és a hozzáférés a használati esetetekről szóló beszélgetéssel kezdődik, nem önkiszolgáló kulccsal — ami egyben a megfelelő pillanat a fenti kérdések mindegyikének feltevésére.