Prijeđi na sadržaj
Blog

API za dostupnost hotela: dizajn za spore dobavljače

Uredništvo Tekravel
Napisano uz pomoć umjetne inteligencije

Zadatak obično stigne bezazleno. „Dodajte pretragu hotela na stranicu za rezervacije — dobavljač nam je dao API za dostupnost hotela, postoji sandbox, bit će jedan sprint.“ Pročitate dokumentaciju, pošaljete zahtjev za dvije odrasle osobe u Zagrebu na tri noći i stigne odgovor. Zatim pošaljete isti zahtjev za grad s puno više smještaja i dugo, neugodno dugo ništa se ne događa. Kad odgovor napokon stigne, to je dokument toliko velik da vaš JSON parser počne preispitivati svoje životne izbore.

U tom trenutku posao mijenja oblik. Dostupnost hotela nije upit u tablicu. To je fan-out: jedno pitanje vašeg korisnika postaje mnogo pitanja prema mnogo dobavljača, a svaki od njih odgovara vlastitom brzinom, vlastitim rječnikom i s vlastitom predodžbom o tome što je „soba“. Klijent koji gradite mora ostati koristan dok se taj fan-out još odvija. Ovaj tekst govori o dizajnu takvog klijenta — napisan je za developera koji dobro poznaje REST i JSON, ali nikad nije morao objašnjavati hotelu zašto je gostova nepovratna cijena prikazana kao besplatno otkazivanje.

Zašto je API za dostupnost hotela sporiji od endpointa na koje ste navikli

Izvana, pretraga leta i pretraga hotela izgledaju slično: ode upit, vrate se ponude s cijenama. Ispod površine, to nije isti problem. Ako ste čitali naše bilješke o tome što integracija API-ja za rezervaciju letova zapravo podrazumijeva, već znate da cijena iz pretrage nije uvijek cijena po kojoj rezervirate. Hoteli tome dodaju još jednu poteškoću: obujam.

Jedan jedini grad može imati stotine smještajnih objekata. Svaki objekt prodaje nekoliko tipova soba. Svaki tip sobe prodaje se pod nekoliko rate plans — s doručkom, bez njega, povratno, nepovratno, cijena za članove, paketna cijena. A svaki rate plan može dolaziti od više dobavljača: od bedbanka, od channel managera, iz izravnog ugovora, od veletrgovca s kojim ste potpisali ugovor jer je njegov allotment u određenom hotelu bio bolji od svih ostalih. Pomnožite to i „jednostavna“ pretraga postaje veliko stablo, sastavljeno iz više izvora koji se ne slažu ni oko naziva ni oko identifikatora.

Dakle, spori dio rijetko je vaš kod. To je najsporiji dobavljač kojeg ste odlučili čekati.

Postupni rezultati ili cijeli odgovor: birajte svjesno

Postoje dva poštena načina da vratite rezultate pretrage hotela, a većina integracija završi negdje nesretno u sredini.

Čekate sve. Backend radi fan-out, čeka da svaki dobavljač odgovori ili da istekne timeout, spaja, uklanja duplikate, sortira i vraća jedan potpuni popis. Rezultat je čist: jedan zahtjev, jedan odgovor, cijene koje se mogu uspoređivati jer su sve na stolu. Cijena je to što korisnik gleda indikator učitavanja onoliko dugo koliko treba vašem najsporijem dobavljaču. Svaki put.

Šaljete ono što imate. Backend pokreće fan-out i odmah vraća search handle. Klijent povremeno provjerava handle ili drži otvoren stream i prima rezultate u paketima, kako dobavljači odgovaraju. Prvi hoteli pojave se brzo. Cijena je složenost svugdje drugdje: popis se preslaguje dok ga korisnik čita, oznaka „najjeftinije“ može se pomaknuti, a hotel koji je stigao od jednog dobavljača kasnije može dobiti nižu cijenu od drugog.

Ako je vaše sučelje stranica za pretragu pred čovjekom, postupni pristup je gotovo uvijek ispravan — čovjek pregledava, ne pokreće batch posao, a stranica koja vidljivo radi pobjeđuje stranicu koja tiho razmišlja. Ako je potrošač drugi stroj — posao usporedbe cijena, korporativni alat za rezervacije kojem treba jedan konačan odgovor — čekanje je često jednostavnije i ispravno.

Što god odabrali, tri pravila drže postupni klijent pri zdravoj pameti:

  • Svaki paket nosi stanje dovršenosti pretrage u cjelini, kako bi klijent razlikovao „još nema novih rezultata“ od „više rezultata neće biti“.
  • Rezultati se spajaju po stabilnom ključu hotela na poslužitelju, a ne samo dodaju na kraj. Klijent nikad ne bi trebao sam zaključivati da su dvije kartice ista zgrada.
  • Sortiranje po cijeni je privremeno dok pretraga ne završi, i sučelje to kaže. Korisnici opraštaju popisu koji se smiri; ne opraštaju oznaku „najniža cijena“ koja se pokaže pogrešnom.

Modeliranje soba i rate plans tako da se ne uruše

Ovdje većina hotelskih integracija tiho propada, a neuspjeh se pojavi mjesecima kasnije kao zahtjev podršci, a ne kao prijava greške.

Primamljiv model je ravan: hotel ima popis ponuda, svaka ponuda ima naziv sobe i cijenu. Lijepo izgleda na ekranu. Zatim jedan dobavljač vrati „Deluxe King“ i „Deluxe Room, 1 King Bed“ za očito istu sobu, drugi vrati isti naziv za dvije stvarno različite sobe (jedna s pogledom na grad, druga bez), a treći vrati cijenu po noći dok svi ostali daju cijenu za cijeli boravak. Ravan popis ne može vam reći što od toga gledate. On ih samo prikazuje.

Model koji preživi susret sa stvarnim dobavljačima ima barem četiri razine i drži ih odvojeno:

RazinaŠto sadržiPogreška koju treba izbjeći
HotelVaš vlastiti stabilni ID, povezan s kodom svakog dobavljačaKorištenje hotel ID-ja dobavljača kao primarnog ključa
SobaPopunjenost, raspored kreveta, izvorni tekst sobe od dobavljača bez izmjena„Čišćenje“ naziva soba dok se dvije različite sobe ne stope u jednu
Rate planUsluga prehrane, povratnost, način plaćanja, dobavljač od kojeg je stigaoTretiranje doručka ili povratnosti kao dijela naziva sobe
CijenaUkupno za boravak, valuta, koji porezi i naknade su uključeni a koji se plaćaju u hoteluPrikazivanje cijene po noći pored cijena za boravak, ili skrivanje naknada koje se plaćaju po dolasku

Možete se ne slagati oko toga gdje idu granice — neki timovi izdvajaju popunjenost u zasebnu razinu, što ima smisla čim prodajete rezervacije za više soba. Ono što ne možete jest spajati razine zato što sučelje prikazuje samo dvije od njih. Sučelje smije spljoštiti podatke pri prikazu. Podaci ne smiju.

Jedan detalj zaslužuje vlastitu rečenicu: čuvajte izvorni opis sobe od dobavljača uz sve što normalizirate. Kad gost stigne i dobije drugu sobu od one na vaučeru, prvo što će netko pitati jest što je dobavljač zapravo poslao.

Uvjeti otkazivanja su podaci, a ne odlomak

Mnogi dobavljači vraćaju uvjete otkazivanja kao slobodan tekst: „Besplatno otkazivanje do 3 dana prije dolaska, nakon toga naplata 1 noći.“ Vrlo je primamljivo prikazati taj niz i krenuti dalje.

Nemojte. Tekst se ne može uspoređivati, sortirati, filtrirati ni provoditi. Vaš korisnik želi filtrirati samo povratne cijene. Financije žele znati koje rezervacije sutra postaju nepovratne, kako bi agencija stigla kontaktirati klijenta prije isteka roka. Tijek nakon rezervacije mora reći kupcu, u trenutku kad pritisne „otkaži“, točno koliko će platiti. Ništa od toga ne radi nad rečenicom.

Modelirajte svaki uvjet kao uređeni popis kaznenih prozora: od ovog trenutka do onog naplata je tolika (ili takav udio boravka, ili toliko noći). Granice su vremenske oznake s vremenskom zonom — vremenskom zonom hotela, ne vašeg poslužitelja i ne korisnika — jer „3 dana prije dolaska“ znači različit trenutak ovisno o tome čiju ponoć računate. Čuvajte izvorni tekst dobavljača uz strukturiranu verziju, prikazujte strukturiranu, a neslaganje između njih tretirajte kao nešto što treba istražiti, a ne sakriti.

I ponovno provjerite uvjete pri rezervaciji, ne samo pri pretrazi. Mijenjaju se između ta dva poziva češće nego što itko očekuje.

Koliko pogreška zapravo košta

Spora pretraga košta vas konverzija — loše, ali vidljivo; netko će se žaliti. Skupi neuspjesi su oni tihi.

Cijena prikazana kao povratna, koju dobavljač tretira kao nepovratnu, znači spor s kupcem koji ima snimku zaslona, a kaznu obično na kraju plati sama agencija. Cijena po noći prikazana kao ukupna cijena boravka prodaje sobe ispod troška dok netko u računovodstvu ne primijeti. Soba spojena s drugom sobom šalje četveročlanu obitelj u sobu za dvoje. Naknade koje se plaćaju u hotelu, a nikad nisu prikazane, pretvaraju recenziju s pet zvjezdica u chargeback. Svaka od ovih stvari je odluka o modelu donesena u prvom sprintu, obično pod etiketom „sredit ćemo kasnije“.

Cacheiranje: što smijete zadržati, a što ne

Svaki tim koji integrira hotelski API prije ili kasnije pita može li cacheirati rezultate kako bi pretraga bila brža i jeftinija. Odgovor je da, za neke stvari — a granica između njih važnija je od bilo kojeg broja o performansama.

Statički sadržaj — nazivi hotela, adrese, koordinate, fotografije, popisi sadržaja, opisi soba — rijetko se mijenja i upravo je ono što trebate cacheirati, agresivno, u vlastitom spremištu. Provjerite uvjete dobavljača o tome kako ga smijete pohranjivati i prikazivati; neke licence to ograničavaju. Dohvaćati ga uživo pri svakoj pretrazi sporo je i bez koristi.

Cijene i dostupnost uživo su druga priča. Cacheirana cijena je nagađanje o tome što će dobavljač naplatiti, a dobavljači ne poštuju vaša nagađanja. Kratkotrajno cacheiranje rezultata pretrage može biti prihvatljivo za prikaz stranice — pod uvjetom da svaki put prema rezervaciji ponovno provjeri cijenu kod dobavljača prije nego što uzme novac, i da sučelje tretira promijenjenu cijenu kao normalan ishod, a ne kao pogrešku. Neki dobavljači također ograničavaju koliko često smijete pretraživati u odnosu na to koliko često rezervirate; agresivno cacheiranje koje od njih skriva vaš stvarni promet nije rupa u pravilima na koju se vrijedi osloniti.

Ono što nikad ne smijete cacheirati jest sve što predstavlja obvezu: zadržani cjenovni token, broj rezervacije, ponudu za otkazivanje. Oni pripadaju jednom korisniku i jednom trenutku.

Prije nego što kažete da je gotovo

Kratka provjera koju vrijedi pokrenuti nad vlastitom integracijom prije nego što počne nositi prave rezervacije:

  • Pretraga vraća stanje dovršenosti, a klijent se ponaša različito prije i poslije njega.
  • Hoteli imaju kao ključ vaš vlastiti ID, s kodom svakog dobavljača povezanim s njim.
  • Soba, rate plan i cijena zasebni su objekti u vašim podacima, što god ekran prikazivao.
  • Svaka cijena kaže je li po noći ili za boravak, i što se plaća po dolasku.
  • Uvjeti otkazivanja pohranjuju se kao vremenski kazneni prozori u vremenskoj zoni hotela, uz sačuvan izvorni tekst.
  • Put prema rezervaciji ponovno provjerava cijenu i ponovno čita uvjete prije nego što ikoga tereti.
  • Ništa što predstavlja obvezu nikad se ne poslužuje iz cachea.

Ako odvagujete hoćete li sve ovo graditi prema pojedinačnim dobavljačima ili krenuti od platforme koja se s ovim problemima već susrela, ugovorna strana važna je koliko i kod — naš tekst o ugovorima s hotelskim konsolidatorima i bedbank cijenama objašnjava što tražiti. Naši vlastiti API-ji za letove i hotele otvaraju se kroz razgovor, a ne samoposlužnim ključem; ako je to put koji želite istražiti, započnite razgovor na stranici travel APIs.

Fan-out nikad ne nestaje. Dobar klijent samo se prestane pretvarati da ga nema.

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.