Ugrás a tartalomra
Blog

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

Tekravel Szerkesztőség
Mesterséges intelligencia segítségével írva

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ésMit adMit kell tárolniMi romlik el
KeresésÚtvonalak árral és egy átlátszatlan ajánlat- vagy viteldíjkulccsalSemmi tartósat — a találatok gyorsan elavulnakVéglegesnek veszitek az árat; a kulcs a pénztár előtt lejár
Árazás / ellenőrzésA megerősített árat, a viteldíjszabályokat, a poggyászt, néha a kötelező utasmezőketAz ellenőrzött ajánlatot és annak lejáratátVáltozott az ár; elfogyott az osztály; a szabályok eltérnek attól, amit mutattatok
FoglalásEgy foglalást — a PNR-t — record locatorral és jegykiállítási határidővelA saját hivatkozásotokat, a locatort, a határidőt, a pontosan elküldött utasadatokatTimeout válasz nélkül; dupla PNR-ek; elutasított nevek
JegykiállításKiállított e-jegy számokat; itt kötődik le ténylegesen a pénzMinden jegyszámot, az utashoz és a szegmenshez rendelve, amelyhez tartozikRé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.

Tekravel Szerkesztőség

Utazástechnológiai rovat

A Tekravel utazástechnológiai rovata a szakmának ír: irodatulajdonosoknak, konszolidátoroknak és az őket integráló fejlesztőknek. Minden cikket a leírt platformon ellenőrzünk a megjelenés előtt.