Hotellien saatavuus-API: suunniteltu hitaille toimittajille

Tehtävä näyttää yleensä viattomalta, kun se saapuu. ”Lisätkää hotellihaku varaussivulle — toimittaja antoi meille hotellien saatavuus-API:n, siinä on sandbox, pitäisi hoitua yhdessä sprintissä.” Luet dokumentaation, lähetät pyynnön kahdelle aikuiselle Helsinkiin kolmeksi yöksi, ja vastaus tulee. Sitten lähetät saman pyynnön kaupunkiin, jossa majoituksia on paljon enemmän, eikä mitään tapahdu pitkään, kiusallisen pitkään. Kun vastaus lopulta tulee, se on niin suuri dokumentti, että JSON-jäsentimesi alkaa pohtia elämänvalintojaan.
Siinä kohdassa työ muuttaa muotoaan. Hotellien saatavuus ei ole haku taulukosta. Se on fan-out: yksi käyttäjäsi kysymys muuttuu moneksi kysymykseksi monelle toimittajalle, ja jokainen vastaa omalla nopeudellaan, omalla sanastollaan ja omalla käsityksellään siitä, mikä ”huone” on. Rakentamasi asiakasohjelman on pysyttävä hyödyllisenä, kun fan-out on vielä kesken. Tämä kirjoitus käsittelee sellaisen asiakasohjelman suunnittelua — ja se on kirjoitettu kehittäjälle, joka tuntee RESTin ja JSONin hyvin mutta ei ole koskaan joutunut selittämään hotellille, miksi asiakkaan palautuskelvoton hinta näytettiin maksuttomana peruutuksena.
Miksi hotellien saatavuus-API on hitaampi kuin tottumasi endpointit
Ulkoapäin lentohaku ja hotellihaku näyttävät samalta: kysely lähtee, hinnoitellut vaihtoehdot palaavat. Pinnan alla ne eivät ole sama ongelma. Jos olet lukenut muistiinpanomme siitä, mitä lentovarausten API-integraatio todella vaatii, tiedät jo, ettei haussa näkyvä hinta ole aina se hinta, jolla varaat. Hotellit lisäävät tähän toisen vaikeuden: volyymin.
Yhdessä kaupungissa voi olla satoja majoituksia. Jokainen majoitus myy useita huonetyyppejä. Jokaista huonetyyppiä myydään useilla rate planeilla — aamiaisella, ilman, palautettavana, palautuskelvottomana, jäsenhintana, pakettihintana. Ja jokainen rate plan voi tulla useammalta kuin yhdeltä toimittajalta: bedbankilta, channel managerilta, suorasta sopimuksesta, tukkurilta, jonka kanssa teit sopimuksen, koska sen allotment tietyssä hotellissa oli kaikkia muita parempi. Kerro nämä keskenään, niin ”yksinkertainen” haku on iso puu, joka kootaan useasta lähteestä, jotka eivät ole samaa mieltä nimistä eivätkä tunnisteista.
Hidas osa on siis harvoin oma koodisi. Se on hitain toimittaja, jota päätit odottaa.
Vaiheittaiset tulokset vai koko vastaus: valitse tietoisesti
Hotellihaun tulokset voi palauttaa kahdella rehellisellä tavalla, ja useimmat integraatiot päätyvät onnettomasti jonnekin niiden väliin.
Odota kaikkea. Backend tekee fan-outin, odottaa kunnes jokainen toimittaja vastaa tai aikakatkaisu laukeaa, yhdistää, poistaa kaksoiskappaleet, lajittelee ja palauttaa yhden täydellisen listan. Tulos on siisti: yksi pyyntö, yksi vastaus, hinnat joita voi verrata, koska ne ovat kaikki pöydällä. Hintana on, että käyttäjä tuijottaa latauskuvaketta niin kauan kuin hitain toimittajasi tarvitsee. Joka kerta.
Lähetä mitä sinulla on. Backend käynnistää fan-outin ja palauttaa heti hakukahvan. Asiakasohjelma kyselee kahvaa tai pitää streamin auki ja saa tuloksia erissä sitä mukaa kuin toimittajat vastaavat. Ensimmäiset hotellit näkyvät nopeasti. Hintana on monimutkaisuus kaikkialla muualla: lista järjestyy uudelleen, kun käyttäjä lukee sitä, ”halvin”-merkintä voi siirtyä, ja yhdeltä toimittajalta tullut hotelli voi myöhemmin saada halvemman hinnan toiselta.
Jos käyttöliittymäsi on hakusivu ihmisen edessä, vaiheittainen malli on lähes aina oikea — ihminen selaa, hän ei aja eräajoa, ja sivu, joka näkyvästi tekee työtä, voittaa sivun, joka ajattelee hiljaa. Jos kuluttaja on toinen kone — hintavertailuajo, yrityksen varaustyökalu, joka tarvitsee yhden lopullisen vastauksen — odottaminen on usein yksinkertaisempaa ja oikein.
Valitsitpa kumman tahansa, kolme sääntöä pitää vaiheittaisen asiakasohjelman järjissään:
- Jokainen erä kantaa koko haun valmistumistilan, jotta asiakasohjelma erottaa tilanteet ”ei vielä lisää tuloksia” ja ”lisää tuloksia ei tule”.
- Tulokset yhdistetään vakaalla hotelliavaimella palvelimella, niitä ei vain lisätä perään. Asiakasohjelman ei pitäisi koskaan joutua itse päättelemään, että kaksi korttia ovat sama rakennus.
- Hintajärjestys on alustava, kunnes haku on valmis, ja käyttöliittymä kertoo sen. Käyttäjät antavat anteeksi listan, joka asettuu paikalleen; he eivät anna anteeksi ”edullisin hinta” -merkintää, joka osoittautuu vääräksi.
Huoneiden ja rate planien mallinnus niin, etteivät ne romahda
Tässä useimmat hotelli-integraatiot epäonnistuvat hiljaa, ja epäonnistuminen näkyy kuukausia myöhemmin tukipyyntönä eikä virheraporttina.
Houkutteleva malli on litteä: hotellilla on lista tarjouksia, jokaisella tarjouksella on huoneen nimi ja hinta. Se näyttää ruudulla hyvältä. Sitten yksi toimittaja palauttaa ”Deluxe King” ja ”Deluxe Room, 1 King Bed” selvästi samasta huoneesta, toinen palauttaa saman nimen kahdelle aidosti eri huoneelle (toisessa kaupunkinäkymä, toisessa ei), ja kolmas palauttaa hinnan per yö, kun kaikki muut antavat hinnan koko oleskelulta. Litteä lista ei kerro, mitä näistä katsot. Se vain näyttää ne.
Malli, joka kestää kohtaamisen oikeiden toimittajien kanssa, sisältää vähintään neljä tasoa ja pitää ne erillään:
| Taso | Mitä se sisältää | Vältettävä virhe |
|---|---|---|
| Hotelli | Oma vakaa tunnisteesi, kohdistettuna jokaisen toimittajan koodiin | Toimittajan hotellitunnisteen käyttäminen pääavaimena |
| Huone | Henkilömäärä, vuodejärjestely, toimittajan oma huoneteksti sellaisenaan | Huonenimien ”siivoaminen”, kunnes kaksi eri huonetta sulautuu yhdeksi |
| Rate plan | Ateriat, palautettavuus, maksutapa, toimittaja josta se tuli | Aamiaisen tai palautettavuuden käsittely osana huoneen nimeä |
| Hinta | Koko oleskelun summa, valuutta, mitkä verot ja maksut sisältyvät ja mitkä maksetaan hotellissa | Yöhinnan näyttäminen oleskeluhintojen vieressä tai saapuessa maksettavien maksujen piilottaminen |
Rajojen paikoista voi olla eri mieltä — jotkin tiimit erottavat henkilömäärän omaksi tasokseen, mikä on järkevää heti, kun myyt usean huoneen varauksia. Et kuitenkaan voi yhdistää tasoja siksi, että käyttöliittymä näyttää niistä vain kaksi. Käyttöliittymä saa litistää tiedot näytettäessä. Data ei saa.
Yksi yksityiskohta ansaitsee oman lauseensa: säilytä toimittajan alkuperäinen huonekuvaus kaiken normalisoimasi rinnalla. Kun asiakas saapuu ja saa eri huoneen kuin voucherissa lukee, ensimmäinen kysymys on, mitä toimittaja oikeasti lähetti.
Peruutusehdot ovat dataa, eivät kappale tekstiä
Monet toimittajat palauttavat peruutusehdot vapaana tekstinä: ”Maksuton peruutus 3 päivää ennen saapumista, sen jälkeen 1 yön maksu.” On hyvin houkuttelevaa näyttää tuo merkkijono ja siirtyä eteenpäin.
Älä tee niin. Tekstiä ei voi verrata, lajitella, suodattaa eikä toimeenpanna. Käyttäjäsi haluaa suodattaa palautettavat hinnat. Taloushallinto haluaa tietää, mitkä varaukset muuttuvat huomenna palautuskelvottomiksi, jotta toimisto ehtii tavoittaa asiakkaan ennen määräajan umpeutumista. Varauksen jälkeisen prosessin on kerrottava asiakkaalle peruutusnapin painalluksen hetkellä tarkalleen, paljonko häneltä veloitetaan. Mikään näistä ei toimi lauseen päällä.
Mallinna jokainen ehto järjestettynä listana sakkoikkunoita: tästä hetkestä tuohon hetkeen maksu on näin paljon (tai tämä osuus oleskelusta, tai näin monta yötä). Rajat ovat aikaleimoja aikavyöhykkeineen — hotellin aikavyöhykkeellä, ei palvelimesi eikä käyttäjän — koska ”3 päivää ennen saapumista” tarkoittaa eri hetkeä sen mukaan, kenen keskiyöstä lasket. Tallenna toimittajan alkuperäinen teksti rakenteisen version viereen, näytä rakenteinen versio, ja käsittele niiden ristiriita tutkittavana asiana, ei piilotettavana.
Tarkista ehdot uudelleen varaushetkellä, ei vain haussa. Ne muuttuvat kahden kutsun välillä useammin kuin kukaan odottaa.
Mitä virheet oikeasti maksavat
Hidas haku maksaa konversioita, mikä on huono asia mutta näkyvä — joku valittaa. Kalliit virheet ovat hiljaisia.
Palautettavana näytetty hinta, jota toimittaja pitää palautuskelvottomana, on riita asiakkaan kanssa, jolla on kuvakaappaus, ja yleensä toimisto maksaa sakon itse. Yöhinta, joka näytetään koko oleskelun hintana, myy huoneita alle omakustannushinnan, kunnes joku kirjanpidossa huomaa. Toiseen huoneeseen yhdistetty huone lähettää nelihenkisen perheen kahdelle tarkoitettuun huoneeseen. Hotellissa maksettavat maksut, joita ei koskaan näytetty, muuttavat viiden tähden arvion chargebackiksi. Jokainen näistä on ensimmäisessä sprintissä tehty mallinnuspäätös, yleensä otsikolla ”siivotaan myöhemmin”.
Välimuisti: mitä saat säilyttää ja mitä et
Jokainen hotelli-API:a integroiva tiimi kysyy jossain vaiheessa, voiko tuloksia tallentaa välimuistiin, jotta haku olisi nopeampi ja halvempi. Vastaus on kyllä, joidenkin asioiden osalta — ja niiden välinen raja merkitsee enemmän kuin mikään suorituskykyluku.
Staattinen sisältö — hotellien nimet, osoitteet, koordinaatit, kuvat, palveluluettelot, huonekuvaukset — muuttuu harvoin ja on juuri sitä, mitä kannattaa välimuistittaa, aggressiivisesti, omaan varastoon. Tarkista toimittajan ehdoista, miten sitä saa tallentaa ja näyttää; jotkin lisenssit rajoittavat sitä. Sen hakeminen livenä joka haussa on hidasta ilman mitään hyötyä.
Live-hinnat ja saatavuus ovat eri asia. Välimuistissa oleva hinta on arvaus siitä, mitä toimittaja veloittaa, eivätkä toimittajat kunnioita arvauksiasi. Lyhytikäinen hakutulosten välimuisti voi olla hyväksyttävä sivun näyttämiseen — kunhan jokainen varauspolku hinnoittelee uudelleen toimittajaa vasten ennen rahan ottamista ja käyttöliittymä käsittelee muuttunutta hintaa normaalina lopputuloksena eikä virheenä. Jotkin toimittajat myös rajoittavat, kuinka usein saat hakea suhteessa siihen, kuinka usein varaat; aggressiivinen välimuisti, joka piilottaa todellisen liikenteesi heiltä, ei ole porsaanreikä, johon kannattaa luottaa.
Välimuistiin ei saa koskaan päätyä mikään, mikä edustaa sitoumusta: pidätetty hintatoken, varausviite, peruutustarjous. Ne kuuluvat yhdelle käyttäjälle ja yhdelle hetkelle.
Ennen kuin sanot sen olevan valmis
Lyhyt tarkistus, joka kannattaa ajaa oman integraation läpi ennen kuin se kantaa oikeita varauksia:
- Haku palauttaa valmistumistilan, ja asiakasohjelma käyttäytyy eri tavalla ennen sitä ja sen jälkeen.
- Hotellien avaimena on oma tunnisteesi, ja jokaisen toimittajan koodi on kohdistettu siihen.
- Huone, rate plan ja hinta ovat datassasi erillisiä olioita, näyttipä ruutu mitä tahansa.
- Jokainen hinta kertoo, onko se per yö vai per oleskelu, ja mitä maksetaan saavuttaessa.
- Peruutusehdot tallennetaan ajastettuina sakkoikkunoina hotellin aikavyöhykkeellä, alkuperäinen teksti säilytettynä.
- Varauspolku hinnoittelee uudelleen ja lukee ehdot uudelleen ennen kuin veloittaa ketään.
- Mitään sitoumusta edustavaa ei koskaan tarjoilla välimuistista.
Jos punnitset, rakennatko tämän kaiken yksittäisiä toimittajia vasten vai aloitatko alustalta, joka on jo kohdannut nämä ongelmat, sopimuspuoli merkitsee yhtä paljon kuin koodi — kirjoituksemme hotellikonsolidaattorien sopimuksista ja bedbank-hinnoista käy läpi, mitä pyytää. Omat lento- ja hotelli-API:mme avataan keskustelun kautta, ei itsepalveluavaimella; jos se on reitti, jota haluat tutkia, aloita keskustelu travel APIs -sivulla.
Fan-out ei koskaan katoa. Hyvä asiakasohjelma vain lakkaa teeskentelemästä, ettei sitä ole.