Přeskočit na obsah
Blog

API dostupnosti hotelů: návrh pro pomalé dodavatele

Redakce Tekravel
Napsáno s pomocí AI

Úkol obvykle přijde nenápadně. „Přidejte na rezervační stránku hledání hotelů — dodavatel nám dal API dostupnosti hotelů, je tam sandbox, mělo by to být na jeden sprint.“ Přečtete dokumentaci, pošlete požadavek pro dva dospělé v Praze na tři noci a odpověď přijde. Pak pošlete stejný požadavek pro město s mnohem víc ubytováními a dlouho, nepříjemně dlouho se nic neděje. Když odpověď konečně dorazí, je to dokument tak velký, že váš JSON parser začne přehodnocovat své životní volby.

V tu chvíli se práce změní. Dostupnost hotelů není dotaz do tabulky. Je to fan-out: jedna otázka vašeho uživatele se změní v mnoho otázek mnoha dodavatelům a každý z nich odpovídá svou rychlostí, svým slovníkem a se svou představou o tom, co je to „pokoj“. Klient, kterého stavíte, musí zůstat užitečný, dokud se ten fan-out ještě rozbaluje. Tento text je o návrhu takového klienta — a je psaný pro vývojáře, který dobře zná REST a JSON, ale nikdy nemusel hotelu vysvětlovat, proč se hostovi nevratná sazba zobrazila jako zrušení zdarma.

Proč je API dostupnosti hotelů pomalejší než endpointy, na které jste zvyklí

Zvenku vypadá hledání letu a hledání hotelu podobně: odejde dotaz, vrátí se nabídky s cenou. Pod povrchem to ale není stejný problém. Pokud jste četli naše poznámky o tom, co integrace API pro rezervaci letenek opravdu obnáší, už víte, že cena z vyhledávání není vždy cena, za kterou rezervujete. Hotely k tomu přidávají druhou potíž: objem.

Jediné město může mít stovky ubytování. Každé ubytování prodává několik typů pokojů. Každý typ pokoje se prodává v několika rate plánech — se snídaní, bez ní, vratný, nevratný, členská cena, cena v balíčku. A každý rate plán může přicházet od více než jednoho dodavatele: z bedbanky, z channel manageru, z přímého kontraktu, od velkoobchodníka, se kterým jste podepsali smlouvu, protože měl v jednom hotelu lepší allotment než kdokoli jiný. Vynásobte to a z „jednoduchého“ hledání je velký strom poskládaný z několika zdrojů, které se neshodnou na názvech ani na ID.

Pomalou částí tedy jen zřídka bývá váš kód. Je to nejpomalejší dodavatel, na kterého jste se rozhodli čekat.

Průběžné výsledky, nebo kompletní odpověď: vyberte si vědomě

Existují dva poctivé způsoby, jak vracet výsledky hledání hotelů, a většina integrací skončí někde nešťastně uprostřed.

Počkat na všechno. Backend udělá fan-out, počká, až každý dodavatel odpoví nebo vyprší timeout, výsledky sloučí, odstraní duplicity, seřadí a vrátí jeden kompletní seznam. Výsledek je čistý: jeden požadavek, jedna odpověď, ceny, které se dají porovnat, protože jsou všechny na stole. Cena za to je, že se uživatel dívá na spinner tak dlouho, jak dlouho trvá váš nejpomalejší dodavatel. Pokaždé.

Posílat, co máte. Backend spustí fan-out a okamžitě vrátí search handle. Klient se na handle průběžně dotazuje, nebo drží otevřený stream, a dostává výsledky po dávkách, jak dodavatelé odpovídají. První hotely se objeví rychle. Cenou je složitost všude jinde: seznam se přeuspořádává, zatímco ho uživatel čte, štítek „nejlevnější“ se může přesunout a hotel, který přišel od jednoho dodavatele, může později dostat levnější sazbu od jiného.

Pokud je vaše rozhraní vyhledávací stránka před člověkem, je průběžný přístup téměř vždy správně — člověk prohlíží, nespouští dávkovou úlohu, a stránka, která viditelně pracuje, vyhraje nad stránkou, která potichu přemýšlí. Pokud je spotřebitelem jiný stroj — úloha na porovnání cen, firemní rezervační nástroj, který potřebuje jednu definitivní odpověď — bývá čekání jednodušší a správné.

Ať zvolíte cokoli, tři pravidla udrží průběžného klienta při smyslech:

  • Každá dávka nese stav dokončení celého hledání, aby klient rozlišil „zatím žádné další výsledky“ od „žádné další výsledky už nebudou“.
  • Výsledky se na serveru slučují podle stabilního klíče hotelu, ne že se jen přidávají na konec. Klient by nikdy neměl sám zjišťovat, že dvě karty jsou stejná budova.
  • Řazení podle ceny je prozatímní, dokud hledání neskončí, a rozhraní to říká. Uživatelé odpustí seznam, který se usadí; neodpustí štítek „nejnižší cena“, který se ukáže jako chybný.

Modelování pokojů a rate plánů tak, aby se nezhroutily

Tady většina hotelových integrací tiše selže a selhání se ukáže až po měsících — jako požadavek na podporu, ne jako hlášení chyby.

Lákavý model je plochý: hotel má seznam nabídek, každá nabídka má název pokoje a cenu. Pěkně se vykreslí. Pak jeden dodavatel vrátí „Deluxe King“ a „Deluxe Room, 1 King Bed“ pro zjevně stejný pokoj, jiný vrátí stejný název pro dva skutečně odlišné pokoje (jeden s výhledem na město, druhý bez) a třetí vrátí sazbu s cenou za noc, zatímco všichni ostatní uvádějí cenu za celý pobyt. Plochý seznam vám neřekne, na co z toho se díváte. Prostě to zobrazí.

Model, který přežije setkání se skutečnými dodavateli, má nejméně čtyři úrovně a drží je oddělené:

ÚroveňCo obsahujeChyba, které se vyhnout
HotelVaše vlastní stabilní ID, namapované na kód každého dodavatelePoužít ID hotelu od dodavatele jako primární klíč
PokojObsazenost, uspořádání lůžek, původní text pokoje od dodavatele beze změny„Uklízet“ názvy pokojů, dokud se dva různé pokoje nesloučí v jeden
Rate plánStrava, vratnost, způsob platby, dodavatel, od kterého přišelBrát snídani nebo vratnost jako součást názvu pokoje
CenaCelkem za pobyt, měna, které daně a poplatky jsou v ní a které se platí v hoteluUkazovat cenu za noc vedle cen za pobyt, nebo skrývat poplatky splatné při příjezdu

O tom, kde přesně vedou hranice, se dá diskutovat — některé týmy vyčleňují obsazenost do samostatné úrovně, což dává smysl, jakmile prodáváte rezervace více pokojů. Co udělat nemůžete, je slučovat úrovně jen proto, že rozhraní ukazuje dvě z nich. Rozhraní může data zploštit při vykreslení. Data samotná nesmí.

Jeden detail si zaslouží vlastní větu: původní popis pokoje od dodavatele uchovávejte vedle všeho, co normalizujete. Když host přijede a dostane jiný pokoj, než má na voucheru, první otázka bude, co dodavatel ve skutečnosti poslal.

Storno podmínky jsou data, ne odstavec

Mnoho dodavatelů vrací storno podmínky jako volný text: „Zrušení zdarma do 3 dnů před příjezdem, poté poplatek za 1 noc.“ Je velmi lákavé ten řetězec zobrazit a jít dál.

Nedělejte to. Text nejde porovnat, seřadit, filtrovat ani vynutit. Váš uživatel chce filtrovat jen vratné sazby. Finanční oddělení chce vědět, které rezervace se zítra stanou nevratnými, aby agentura stihla klienta kontaktovat, než lhůta vyprší. Proces po rezervaci musí zákazníkovi ve chvíli, kdy klikne na zrušit, říct přesně, kolik zaplatí. Nic z toho nad větou nefunguje.

Modelujte každou podmínku jako seřazený seznam sankčních oken: od tohoto okamžiku do tamtoho je poplatek tolik (nebo takový podíl z pobytu, nebo tolik nocí). Hranice jsou časová razítka s časovým pásmem — časovým pásmem hotelu, ne vašeho serveru a ne uživatele — protože „3 dny před příjezdem“ znamená jiný okamžik podle toho, čí půlnoc počítáte. Původní text dodavatele uložte vedle strukturované verze, zobrazujte strukturovanou a nesoulad mezi nimi berte jako něco k prošetření, ne ke skrytí.

A podmínky ověřte znovu při rezervaci, nejen při hledání. Mezi těmi dvěma voláními se mění častěji, než kdokoli čeká.

Kolik chyba ve skutečnosti stojí

Pomalé hledání vás stojí konverze — špatné, ale viditelné; někdo si stěžovat bude. Drahá selhání jsou ta tichá.

Sazba zobrazená jako vratná, kterou dodavatel považuje za nevratnou, znamená spor se zákazníkem, který má screenshot, a pokutu nakonec obvykle zaplatí agentura sama. Cena za noc zobrazená jako celková cena pobytu prodává pokoje pod nákladovou cenou, dokud si toho nevšimne účetní. Pokoj sloučený s jiným pokojem pošle čtyřčlennou rodinu do pokoje pro dva. Poplatky splatné v hotelu, které nikdy nebyly zobrazeny, promění pětihvězdičkovou recenzi v chargeback. Každá z těchto věcí je rozhodnutí o modelu přijaté v prvním sprintu, obvykle pod heslem „uklidíme to později“.

Cachování: co si smíte nechat a co ne

Každý tým, který integruje hotelové API, se dřív nebo později zeptá, jestli může výsledky cachovat, aby bylo hledání rychlejší a levnější. Odpověď zní ano, pro některé věci — a hranice mezi nimi je důležitější než jakékoli číslo o výkonu.

Statický obsah — názvy hotelů, adresy, souřadnice, fotografie, seznamy vybavení, popisy pokojů — se mění zřídka a je to přesně to, co byste měli agresivně cachovat ve vlastním úložišti. Zkontrolujte podmínky dodavatele, jak smíte obsah ukládat a zobrazovat; některé licence to omezují. Stahovat ho živě při každém hledání je pomalé a bez užitku.

Živé ceny a dostupnost jsou jiná věc. Cena z cache je odhad toho, co si dodavatel naúčtuje, a dodavatelé vaše odhady nerespektují. Krátkodobé cachování výsledků hledání může být přijatelné pro zobrazení stránky — pokud každá cesta k rezervaci před převzetím peněz cenu u dodavatele znovu ověří a rozhraní bere změněnou cenu jako běžný výsledek, ne jako chybu. Někteří dodavatelé navíc omezují, jak často smíte hledat v poměru k tomu, jak často rezervujete; agresivní cachování, které před nimi skrývá váš skutečný provoz, není kličkou, na kterou se vyplatí spoléhat.

Co nikdy cachovat nesmíte, je cokoli, co představuje závazek: držený cenový token, rezervační číslo, kalkulaci storna. Ty patří jednomu uživateli a jednomu okamžiku.

Než řeknete, že je hotovo

Krátká kontrola, kterou stojí za to projít na vlastní integraci, než začne nést skutečné rezervace:

  • Hledání vrací stav dokončení a klient se před ním a po něm chová jinak.
  • Hotely mají jako klíč vaše vlastní ID a kód každého dodavatele je na něj namapovaný.
  • Pokoj, rate plán a cena jsou ve vašich datech samostatné objekty, ať obrazovka ukazuje cokoli.
  • Každá cena říká, jestli je za noc, nebo za pobyt, a co se platí při příjezdu.
  • Storno podmínky jsou uložené jako časová sankční okna v časovém pásmu hotelu, s ponechaným původním textem.
  • Cesta k rezervaci cenu znovu ověří a podmínky znovu načte, než komukoli něco strhne.
  • Nic, co představuje závazek, se nikdy neservíruje z cache.

Pokud zvažujete, jestli tohle všechno stavět proti jednotlivým dodavatelům, nebo začít od platformy, která na tyto problémy už narazila, smluvní stránka je stejně důležitá jako kód — náš článek o smlouvách s hotelovými konsolidátory a bedbank cenách rozebírá, co si vyžádat. Naše vlastní API pro lety a hotely se otevírají rozhovorem, ne samoobslužným klíčem; pokud je to cesta, kterou chcete prozkoumat, začněte rozhovor na stránce travel APIs.

Fan-out nikdy nezmizí. Dobrý klient jen přestane předstírat, že tam není.

Redakce Tekravel

Rubrika cestovních technologií

Rubrika cestovních technologií Tekravel píše pro obor: majitele agentur, konsolidátory a vývojáře, kteří je integrují. Každý článek je před vydáním ověřen na platformě, kterou popisuje.