Naar inhoud springen
Blog

Hotelbeschikbaarheid via API: bouwen voor trage leveranciers

Tekravel Redactie
Geschreven met hulp van AI

Het ticket ziet er meestal onschuldig uit. “Hotels zoeken toevoegen aan de boekingspagina. De leverancier heeft ons een API voor hotelbeschikbaarheid gegeven, er is een sandbox, moet in één sprint kunnen.” Je leest de documentatie, stuurt een verzoek voor twee volwassenen in Dubai voor drie nachten en krijgt een antwoord terug. Dan stuur je hetzelfde verzoek voor een stad met meer accommodaties, en lange tijd gebeurt er helemaal niets. Als het antwoord eindelijk komt, is het een document waar je JSON-parser even stil van wordt.

Op dat moment verandert de opdracht van karakter. Hotelbeschikbaarheid is geen opzoekactie. Het is een fan-out: één vraag van je gebruiker wordt een reeks vragen aan een reeks leveranciers, en elk van hen antwoordt in zijn eigen tempo, in zijn eigen vocabulaire, met zijn eigen idee van wat een ‘kamer’ is. De client die je bouwt moet bruikbaar blijven terwijl die fan-out nog loopt. Dit stuk gaat over het ontwerp van zo’n client, geschreven voor een developer die REST en JSON door en door kent, maar nog nooit aan een hotel heeft hoeven uitleggen waarom een niet-restitueerbaar tarief bij een gast als gratis annuleerbaar werd getoond.

Waarom een API voor hotelbeschikbaarheid trager is dan de endpoints die je kent

Van buitenaf lijken zoeken naar vluchten en zoeken naar hotels op elkaar: er gaat een vraag uit, er komen geprijsde opties terug. Onder de motorkap is het een ander probleem. Wie onze notities over wat een API-integratie voor vluchtboekingen werkelijk inhoudt heeft gelezen, weet al dat de prijs die je vindt niet altijd de prijs is die je boekt. Hotels leggen daar nog een tweede moeilijkheid bovenop: volume.

Eén stad kan honderden accommodaties tellen. Elke accommodatie verkoopt meerdere kamertypes. Elk kamertype wordt onder meerdere rate plans verkocht: met ontbijt, zonder ontbijt, restitueerbaar, niet-restitueerbaar, een ledentarief, een pakkettarief. En elk rate plan kan van meer dan één leverancier komen: een bedbank, een channel manager, een direct contract, een wholesaler waarmee je tekende omdat hun allotment in één bepaald hotel beter was dan dat van wie dan ook. Vermenigvuldig dat en een ‘simpele’ zoekopdracht blijkt een grote boom, samengesteld uit bronnen die het niet eens zijn over namen of ID’s.

Het trage deel is dus zelden je eigen code. Het is de traagste leverancier op wie je besloot te wachten.

Progressieve resultaten of het volledige antwoord: kies bewust

Er zijn twee eerlijke manieren om hotelresultaten terug te geven, en de meeste integraties belanden ergens ongelukkig in het midden.

Op alles wachten. Je backend vraagt alle leveranciers tegelijk, wacht tot iedereen heeft geantwoord of in een time-out is gelopen, voegt samen, ontdubbelt, sorteert en geeft één complete lijst terug. Het resultaat is netjes: één request, één response, en prijzen die je kunt vergelijken omdat ze allemaal op tafel liggen. De prijs daarvoor is dat je gebruiker naar een spinner kijkt zolang je traagste leverancier erover doet. Elke keer opnieuw.

Laten zien wat je hebt. Je backend start de fan-out en geeft meteen een zoekhandle terug. De client pollt die handle, of houdt een stream open, en ontvangt resultaten in batches zodra leveranciers antwoorden. De eerste hotels verschijnen snel. De prijs zit in de complexiteit overal elders: de lijst verspringt terwijl de gebruiker leest, een ‘goedkoopst’-label kan verschuiven, en een hotel dat via de ene leverancier binnenkwam, kan later via een andere een lager tarief krijgen.

Staat er een mens achter je zoekpagina, dan is progressief bijna altijd de juiste keuze. Die persoon is aan het rondkijken, geen batchjob aan het draaien, en een pagina die zichtbaar werkt wint het van een pagina die stil nadenkt. Is je afnemer een andere machine, zoals een job die tarieven vergelijkt of een zakelijke boekingstool die één definitief antwoord nodig heeft, dan is wachten vaak eenvoudiger en ook gewoon correct.

Wat je ook kiest, met drie regels blijft een progressieve client beheersbaar:

  • Elke batch bevat een voltooiingsstatus voor de zoekopdracht als geheel, zodat de client het verschil kent tussen ‘nog geen nieuwe resultaten’ en ‘nooit meer nieuwe resultaten’.
  • Resultaten worden op de server samengevoegd op een stabiele hotelsleutel, niet achter elkaar geplakt. De client hoort nooit zelf te hoeven uitzoeken dat twee kaarten over hetzelfde gebouw gaan.
  • Sorteren op prijs is voorlopig tot de zoekopdracht klaar is, en de interface zegt dat ook. Gebruikers vergeven een lijst die nog even schuift; een ‘laagste prijs’-label dat achteraf niet klopt, vergeven ze niet.

Kamers en rate plans zo modelleren dat ze niet in elkaar klappen

Hier gaan de meeste hotelintegraties stilletjes onderuit, en die mislukking meldt zich maanden later als supportticket, niet als bugrapport.

Het verleidelijke model is plat: een hotel heeft een lijst aanbiedingen, elke aanbieding heeft een kamernaam en een prijs. Ziet er prima uit. Tot de ene leverancier ‘Deluxe King’ en ‘Deluxe Room, 1 King Bed’ terugstuurt voor wat overduidelijk dezelfde kamer is, een tweede leverancier dezelfde naam gebruikt voor twee echt verschillende kamers (één met uitzicht op de stad, één zonder), en een derde een tarief levert dat per nacht is terwijl de rest per verblijf rekent. Een platte lijst kan je niet vertellen naar welk van deze gevallen je kijkt. Hij toont ze gewoon.

Een model dat het contact met echte leveranciers overleeft, heeft minstens vier niveaus en houdt die strikt gescheiden:

NiveauWat het bevatDe fout die je moet vermijden
HotelJe eigen stabiele ID, gekoppeld aan de code van elke leverancierDe hotel-ID van een leverancier als primaire sleutel gebruiken
KamerBezetting, bedindeling, de eigen kamertekst van de leverancier letterlijk bewaardKamernamen zo lang ‘opschonen’ tot twee verschillende kamers er één worden
Rate planVerzorgingsbasis, restitueerbaarheid, betaalwijze, de leverancier waar het vandaan komtOntbijt of restitueerbaarheid behandelen als onderdeel van de kamernaam
PrijsTotaal voor het verblijf, valuta, welke belastingen en toeslagen erin zitten en welke in het hotel betaald wordenEen bedrag per nacht naast bedragen per verblijf tonen, of toeslagen bij aankomst verbergen

Je mag het oneens zijn met waar de grenzen liggen. Sommige teams maken van bezetting een eigen niveau, en dat is redelijk zodra je boekingen met meerdere kamers verkoopt. Wat je niet mag doen, is niveaus samenvoegen omdat de interface er maar twee laat zien. De interface mag bij het renderen platslaan. De data niet.

Eén detail verdient een eigen zin: bewaar de ruwe kamerbeschrijving van de leverancier naast alles wat je normaliseert. Als een gast aankomt en een andere kamer krijgt dan op zijn voucher staat, is de eerste vraag van iedereen wat de leverancier nu precies heeft gestuurd.

Annuleringsvoorwaarden zijn data, geen alinea

Veel leveranciers sturen annuleringsvoorwaarden mee als vrije tekst: “Gratis annuleren tot 3 dagen voor aankomst, daarna 1 nacht boete.” De verleiding is groot om die zin gewoon te tonen en door te gaan.

Doe het niet. Tekst kun je niet vergelijken, sorteren, filteren of afdwingen. Je gebruiker wil filteren op restitueerbare tarieven. Je financiële afdeling wil weten welke boekingen morgen niet-restitueerbaar worden, zodat het reisbureau de klant nog kan benaderen voordat de deadline verstrijkt. Je flow na de boeking moet de klant op het moment dat die op annuleren drukt precies vertellen wat er in rekening wordt gebracht. Met een zin werkt geen van die dingen.

Modelleer elke voorwaarde als een geordende lijst boetevensters: vanaf dit moment, tot dat moment, kost het dit bedrag (of dit deel van het verblijf, of zoveel nachten). De grenzen zijn tijdstempels met een tijdzone, en wel die van het hotel, niet die van je server en niet die van de gebruiker. ‘3 dagen voor aankomst’ is namelijk een ander moment, afhankelijk van wiens middernacht je aanhoudt. Sla de originele tekst van de leverancier op naast de gestructureerde versie, toon de gestructureerde versie, en behandel een verschil tussen de twee als iets om uit te zoeken, niet als iets om weg te stoppen.

En controleer de voorwaarden opnieuw op het moment van boeken, niet alleen bij het zoeken. Tussen die twee aanroepen veranderen ze vaker dan iemand verwacht.

Wat het je werkelijk kost als je dit verkeerd doet

Een trage zoekopdracht kost je conversies. Vervelend, maar zichtbaar: iemand gaat erover klagen. De dure fouten zijn de stille.

Een tarief dat als restitueerbaar wordt getoond terwijl de leverancier het als niet-restitueerbaar behandelt, levert een geschil op met een klant die een screenshot heeft, en meestal betaalt het reisbureau de boete uiteindelijk zelf. Een prijs per nacht die als totaal voor het verblijf wordt getoond, verkoopt kamers onder de kostprijs tot iemand op de boekhouding het opmerkt. Een kamer die met een andere kamer is samengevoegd, stuurt een gezin van vier naar een kamer voor twee. Toeslagen die in het hotel betaald moeten worden maar nooit zijn getoond, maken van een vijfsterrenreview een chargeback. Elk van deze gevallen is een modelleerkeuze uit de eerste sprint, meestal gemaakt onder het motto ‘dat ruimen we later wel op’.

Caching: wat je mag bewaren en wat absoluut niet

Elk team dat een hotel-API integreert, vraagt zich vroeg of laat af of het resultaten kan cachen om zoeken sneller en goedkoper te maken. Het antwoord is ja, voor sommige dingen, en de grens daartussen is belangrijker dan welk prestatiecijfer ook.

Statische content, zoals hotelnamen, adressen, coördinaten, foto’s, lijsten met voorzieningen en kamerbeschrijvingen, verandert zelden en is precies wat je ruim en agressief in je eigen opslag moet cachen. Kijk wel in de voorwaarden van de leverancier hoe je het mag opslaan en tonen; sommige licenties beperken dat. Het bij elke zoekopdracht live ophalen is traag zonder dat het iets oplevert.

Live tarieven en beschikbaarheid zijn een ander verhaal. Een gecachete prijs is een gok naar wat de leverancier gaat rekenen, en leveranciers houden zich niet aan jouw gokken. Kortstondig cachen van zoekresultaten kan acceptabel zijn om een pagina te tonen, zolang elk boekingspad de prijs opnieuw bij de leverancier opvraagt voordat er geld wordt afgeschreven, en de interface een gewijzigde prijs behandelt als normale uitkomst in plaats van als fout. Sommige leveranciers beperken ook hoe vaak je mag zoeken in verhouding tot hoe vaak je boekt; agressief cachen dat je werkelijke verkeer voor hen verbergt, is geen maas in de wet om op te bouwen.

Wat je nooit mag cachen, is alles wat een verplichting vertegenwoordigt: een vastgehouden prijstoken, een boekingsreferentie, een annuleringsofferte. Die horen bij één gebruiker en één moment.

Voordat je het af noemt

Een korte check, de moeite waard om op je eigen integratie los te laten voordat die echte boekingen verwerkt:

  • De zoekopdracht geeft een voltooiingsstatus terug, en de client gedraagt zich ervoor en erna anders.
  • Hotels zijn gesleuteld op je eigen ID, met de code van elke leverancier daaraan gekoppeld.
  • Kamer, rate plan en prijs zijn aparte objecten in je data, wat het scherm ook laat zien.
  • Elke prijs vermeldt of die per nacht of per verblijf is, en wat er bij aankomst betaald moet worden.
  • Annuleringsvoorwaarden zijn opgeslagen als boetevensters in de tijdzone van het hotel, met de originele tekst erbij.
  • Het boekingspad vraagt de prijs opnieuw op en leest de voorwaarden opnieuw voordat er iemand iets betaalt.
  • Niets wat een verplichting vertegenwoordigt, komt ooit uit een cache.

Twijfel je of je dit allemaal per leverancier zelf moet bouwen of beter kunt starten vanaf een platform dat deze problemen al is tegengekomen, dan telt de contractkant net zo zwaar als de code. Ons stuk over contracten met hotelconsolidators en bedbank-tarieven beschrijft waar je naar moet vragen. Onze eigen API’s voor vluchten en hotels gaan open via een gesprek, niet via een selfservice-key; wil je die route verkennen, begin dat gesprek dan op de pagina over travel API’s.

De fan-out gaat nooit weg. Een goede client doet gewoon niet langer alsof hij er niet is.

Tekravel Redactie

Desk reistechnologie

De reistechnologie-desk van Tekravel schrijft voor de branche: eigenaren van reisbureaus, consolidators en de ontwikkelaars die hen koppelen. Elk artikel wordt vóór publicatie getoetst aan het platform dat het beschrijft.