Prijeđi na sadržaj
Blog

Integracija API-ja za rezervaciju letova: što dokumentacija prešućuje

Uredništvo Tekravel
Napisano uz pomoć umjetne inteligencije

Na kartici na ploči piše „dodaj letove". Već ste isporučili integraciju plaćanja, integraciju cijena dostave, možda i karata, a mentalni model koji donosite onaj je očiti: pretraži, prikaži rezultate, naplati karticu, gotovo. Onda se prva prava rezervacija vrati po drugačijoj cijeni od one na stranici s rezultatima, druga padne u timeout i nitko vam ne može reći ima li klijent sjedalo, a netko iz operative pita zašto postoji rezervacija, ali ne i karta. Integracija API-ja za rezervaciju letova izvana izgleda kao checkout web-trgovine. Ispod je distribuirana transakcija prema sustavima projektiranim davno prije REST-a, a većina iznenađenja dolazi upravo iz tog procjepa.

Tekst je pisan za developera koji nikad nije vidio PNR. Ne bavi se endpointima jednog konkretnog dobavljača; imena se mijenjaju od pružatelja do pružatelja, oblik ne.

Slijed poziva iza integracije API-ja za rezervaciju letova

Gotovo svaki API za letove, kako god zvao svoje metode, prolazi kroz ista četiri koraka. Ispravno povlačenje granica među njima najveći je dio posla.

KorakŠto vam dajeŠto morate pohranitiŠto pođe po zlu
PretragaItinerere s cijenom i neprozirnim ključem ponude ili tarifeNišta trajno — rezultati brzo zastarijevajuTretirate cijenu kao konačnu; ključ istječe prije checkouta
Obračun / provjeraPotvrđenu cijenu, tarifna pravila, prtljagu, ponekad obvezna polja putnikaProvjerenu ponudu i njezin rokCijena se promijenila; klasa je rasprodana; pravila se razlikuju od prikazanih
RezervacijaRezervaciju — PNR — s record locatorom i rokom za izdavanjeVlastitu referencu, locator, rok, točne podatke putnika koje ste poslaliTimeout bez odgovora; dupli PNR-ovi; odbijena imena
IzdavanjeIzdane brojeve e-karata; ovdje se novac stvarno angažiraSvaki broj karte, vezan uz putnika i segment kojima pripadaDjelomično izdavanje; zrakoplovna kompanija otkazala rezervaciju jer je rok istekao

Redak oko kojeg se ljudi spore treći je, jer mnogi API-ji dopuštaju rezervaciju i izdavanje u jednom pozivu. Koristite ga ako želite. Te su dvije stvari i dalje odvojene u svijetu zrakoplovne kompanije: PNR može postojati bez karte, a izdavanje može propasti nakon što je PNR kreiran. Kombinirani endpoint samo skriva trenutak u kojem je jedno uspjelo, a drugo nije, pa vaš model podataka ipak mora imati mjesto za to stanje.

Primijetite i što pretraga ne vraća: obećanje. Ona je oglas. Korak obračuna je ponuda, a tek karta je prodaja.

Zašto cijena koju ste pretražili nije cijena koju rezervirate

Web developeri očekuju katalog. Inventar zrakoplovnih kompanija to nije. Let se prodaje u klasama rezervacije, svaka je kanta sjedala po određenoj tarifi, a kompanija neprestano otvara i zatvara te kante kako se let puni. Rezultati pretrage brzo se sastavljaju iz raspoloživosti koja možda već malo kasni; dok korisnik utipka dvije putovnice, najjeftinija kanta na tom letu može se zatvoriti. Kad se pokrene korak obračuna, on pita ponovno, a iskren odgovor ponekad je viši.

Pristojbe dodaju vlastito odstupanje. Ponovno se računaju pri obračunu za točne putnike i rutu, a dijete ili beba obračunavaju se drugačije od odrasle osobe koju je pretraga pretpostavila. Konverzija valute, ako vaša trgovina prikazuje eure, a dobavljač kotira u drugoj valuti, još je jedno mjesto gdje se broj pomiče.

Posljedica za dizajn jednostavna je i često se preskače: nikad ne naplaćujte po cijeni iz pretrage. Pokrenite korak obračuna prije plaćanja, usporedite, i ako se iznos promijenio, prikažite novi broj i pitajte. Koju god maržu primjenjujete, mora se ponovno izračunati na obračunatoj tarifi, a ne prenijeti sa stranice s rezultatima — logika je ista kao ona koju agencija prolazi kad postavlja strategiju marže online, i lomi se na isti način kad se osnova pomakne ispod nje.

Idempotentnost i što znači timeout tijekom rezervacije

Ovo je odjeljak koji treba pročitati dvaput.

Kad poziv za rezervaciju padne u timeout, ne znate što se dogodilo. Zahtjev možda nikad nije stigao. Možda je stigao i propao. Ili — slučaj koji boli — stigao je, dobavljač je kreirao PNR kod zrakoplovne kompanije, a odgovor se izgubio na putu natrag do vas. Za vaš kod sva tri izgledaju identično. Za kompaniju, treći je živa rezervacija koja drži sjedala na ime vašeg klijenta.

Refleks iz drugih integracija jest pokušati ponovno. Ovdje slijepo ponavljanje može proizvesti drugi PNR za iste putnike na istom letu. Zrakoplovne kompanije tretiraju duple rezervacije kao kršenje politike; ovisno o prijevozniku i ugovorima agencije, posljedica ide od automatskog otkazivanja jedne ili obiju rezervacija do terećenja — ADM-a — poslanog onome tko ih je izdao. Agencija koja ga primi htjet će znati zašto je vaš sustav rezervirao dvaput.

Što funkcionira, otprilike ovim redom:

  • Kreirajte vlastitu referencu rezervacije prije poziva prema van, pohranite je i pošaljite uz zahtjev svugdje gdje API prihvaća klijentsku referencu. Ako API podržava idempotency key, koristite ga; ako ne, vaša je referenca i dalje ono što vam omogućuje da rezervaciju poslije pronađete.
  • Eksplicitno modelirajte nepoznato stanje. Na čekanju, potvrđeno, neuspješno — i nepoznato. Timeout prebacuje rezervaciju u nepoznato, ne u neuspješno.
  • Nepoznato rješavajte pitanjem, ne ponavljanjem. Dohvatite po svojoj referenci ili izlistajte nedavne rezervacije za te putnike prije nego odlučite hoćete li pokušati ponovno.
  • Pokrenite posao usklađivanja koji prolazi sve što je još nepoznato, uspoređuje s onim što dobavljač prijavljuje i ono što ne može riješiti šalje u red za čovjeka umjesto da nagađa.

Timeout pri izdavanju isti je problem, samo s novcem. Ako naplatite karticu prije izdavanja, a izdavanje zapne, imate klijenta koji je platio i možda nema kartu. Ako izdate prije naplate, a naplata propadne, izdali ste dokument koji netko mora platiti zrakoplovnoj kompaniji. Prvo autorizacija kartice, zatim izdavanje, pa naplata pri uspjehu uobičajen je oblik — poanta je da to odlučite svjesno, a ne da otkrijete u produkciji.

Pojmovi iz turističke struke koji iznenade web developere

Nijedan od njih nije težak. Svaki je nekoga koštao tjedan dana jer nije znao da postoji.

PNR nije karta

PNR je zapis rezervacije: putnici, segmenti, kontakti, rok. Karta je plaćeni dokument koji putniku daje pravo na let. Neizdan PNR istječe na svoj rok za izdavanje i sjedala se vraćaju u prodaju, ponekad nečujno iz vašeg kuta.

Imena su gotovo nepromjenjiva

Nakon izdavanja većina tarifa ne dopušta promjenu imena izvan sitnog ispravka, a što se računa kao sitno razlikuje se po kompaniji. Ime mora odgovarati putnoj ispravi. Prikupljajte prezime i imena odvojeno, ne dopustite da slobodno unesena titula procuri u polje za ime i validirajte prije poziva za rezervaciju, ne poslije.

Tipovi putnika se obračunavaju, nisu dekoracija

Odrasli, dijete i beba tarifni su tipovi, a dob koja odlučuje koji vrijedi obično je dob na dan putovanja, a ne na dan rezervacije. Beba u krilu u pravilu ne zauzima sjedalo i često može putovati samo uz odraslu osobu. Pogrešan tip znači da obračun ili propadne ili ponudi pogrešnu tarifu.

Vremena su lokalna, a segmenti nisu etape

Vremena polijetanja i slijetanja daju se u lokalnom vremenu svake zračne luke. Ne pretvarajte ih u korisnikovu vremensku zonu radi prikaza i ne računajte trajanje oduzimanjem bez pomaka. Putovanje sadrži segmente; segment s tehničkim slijetanjem sadrži više od jedne etape. Vaše sučelje i vaši podaci moraju se složiti što je od toga „stajanje".

Stvari se događaju i nakon prodaje

Zrakoplovne kompanije mijenjaju redove letenja nakon što su karte izdane. Rezervacija koja je bila ispravna pri izdavanju može tjednima kasnije pokazivati novo vrijeme, novi broj leta ili prekinutu vezu, a ovisno o dobavljaču doznajete to kroz obavijest, red ili ponovnim dohvaćanjem rezervacije. Planirajte da će se rezervacija promijeniti nakon što ste je prestali gledati.

Void nije povrat

Ubrzo nakon izdavanja obično postoji prozor u kojem se karta može poništiti (void) kao da nikad nije postojala. Nakon tog prozora moguć je samo povrat po tarifnim pravilima, koji može koštati penal ili ne vratiti ništa. Prozor i njegova pravila pripadaju dobavljaču i ugovoru o izdavanju; pročitajte ih prije nego napravite gumb „otkaži".

Koliko košta pogreška

Neuspjesi u integraciji letova skupi su na specifičan način: padaju na ljude, ne u logove. Dupla rezervacija postaje telefonski poziv kompaniji i moguće terećenje računa agencije. Naplaćeni klijent bez karte postaje povrat, pritužba i rizik od chargebacka. Karta izdana bez uspješne naplate postaje dug prema kompaniji koji netko mora podmiriti. Promjena reda letenja koju nitko nije obradio postaje putnik u zračnoj luci za let koji je otišao ranije.

Ništa od toga ne pojavljuje se u testu sretnog puta. Prvo napišite nesretne putove: timeout tijekom rezervacije, cijenu koja je porasla, izdavanje koje je propalo nakon PNR-a, void nakon uspješne naplate. Ako su oni obrađeni, sretan put lakši je dio.

Testiranje prema API-ju za letove

Testna okruženja dobavljača korisna su i nepotpuna. Obično su mirnija od produkcije, pa su rasprodane klase i promjene cijena rjeđe, a neka uopće ne simuliraju timeout. Koristite ih za oblik poziva i greške validacije, a zatim planirajte kontrolirano izvođenje u produkciji s pravim rezervacijama koje poništavate unutar prozora — uz operativu koja zna da to radite.

Hoćete li uopće integrirati zasebno je pitanje. Ako vam zapravo treba prodajno mjesto, a ne sirovi inventar u vlastitom sustavu, kompromis je opisan u tekstu white label ili vlastiti rezervacijski sustav, a isto rezoniranje vrijedi i za B2B portal za subagente. Ako doista želite inventar u vlastitom kodu, platforma izlaže API-je za letove i hotele, a pristup počinje razgovorom o vašem slučaju uporabe, a ne samoposlužnim ključem — što je ujedno i pravi trenutak da postavite svako od gornjih pitanja.

Uredništvo Tekravel

Desk za putničke tehnologije

Desk za putničke tehnologije Tekravela piše za struku: vlasnike agencija, konsolidatore i programere koji ih integriraju. Svaki se članak prije objave provjerava na platformi koju opisuje.