API dostępności hoteli: klient odporny na wolnych dostawców

Zgłoszenie zwykle wygląda niewinnie. „Dodać wyszukiwarkę hoteli do strony rezerwacji. Dostawca dał nam API dostępności hoteli, jest sandbox, powinno się zmieścić w jednym sprincie”. Czytasz dokumentację, wysyłasz zapytanie dla dwóch dorosłych w Dubaju na trzy noce i dostajesz odpowiedź. Potem wysyłasz to samo zapytanie dla miasta z większą liczbą obiektów i przez długą, niezręczną chwilę nie wraca nic. Kiedy w końcu wraca, jest to dokument tak duży, że twój parser JSON zaczyna się zastanawiać nad sensem życia.
W tym momencie zadanie zmienia charakter. Dostępność hoteli to nie jest proste wyszukanie rekordu. To fan-out: jedno pytanie użytkownika staje się wieloma pytaniami do wielu dostawców, a każdy z nich odpowiada we własnym tempie, własnym słownictwem i z własnym pojęciem o tym, czym jest „pokój”. Klient, którego budujesz, musi pozostać użyteczny, zanim ten fan-out się zakończy. Ten tekst dotyczy projektowania takiego klienta. Piszę go dla developera, który dobrze zna REST i JSON, ale nigdy nie musiał tłumaczyć hotelowi, dlaczego bezzwrotna stawka gościa była pokazana jako z darmową anulacją.
Dlaczego API dostępności hoteli jest wolniejsze niż endpointy, które znasz
Z zewnątrz wyszukiwanie lotów i hoteli wygląda podobnie: wychodzi zapytanie, wracają wycenione opcje. Pod spodem to jednak dwa różne problemy. Jeśli czytałeś nasze uwagi o tym, co naprawdę oznacza integracja API rezerwacji lotów, wiesz już, że cena znaleziona w wyszukiwaniu nie zawsze jest ceną, którą zarezerwujesz. Hotele dokładają do tego drugą trudność: skalę.
Jedno miasto może mieć setki obiektów. Każdy obiekt sprzedaje kilka typów pokoi. Każdy typ pokoju jest sprzedawany w kilku planach taryfowych: ze śniadaniem, bez śniadania, zwrotny, bezzwrotny, stawka dla członków, stawka pakietowa. A każdy plan taryfowy może pochodzić od więcej niż jednego dostawcy: z bedbanku, z channel managera, z bezpośredniego kontraktu, od hurtownika, z którym podpisałeś umowę, bo jego allotment w jednym konkretnym hotelu był lepszy niż u kogokolwiek innego. Pomnóż to wszystko, a „proste” wyszukiwanie okaże się dużym drzewem, złożonym z kilku źródeł, które nie zgadzają się co do nazw ani identyfikatorów.
Wolną częścią rzadko jest więc twój kod. Jest nią najwolniejszy dostawca, na którego postanowiłeś czekać.
Wyniki progresywne czy pełna odpowiedź: wybierz świadomie
Są dwa uczciwe sposoby zwracania wyników wyszukiwania hoteli, a większość integracji ląduje gdzieś pomiędzy nimi, i nikt nie jest z tego zadowolony.
Czekać na wszystko. Backend rozsyła zapytania, czeka, aż każdy dostawca odpowie albo przekroczy limit czasu, scala wyniki, usuwa duplikaty, sortuje i zwraca jedną kompletną listę. Wynik jest czysty: jedno żądanie, jedna odpowiedź, ceny, które da się porównać, bo wszystkie leżą na stole. Kosztem jest to, że użytkownik patrzy na kręcące się kółko tak długo, jak długo odpowiada twój najwolniejszy dostawca. Za każdym razem.
Pokazywać to, co już masz. Backend uruchamia fan-out i od razu zwraca uchwyt wyszukiwania. Klient odpytuje ten uchwyt albo trzyma otwarty strumień i odbiera wyniki partiami, w miarę jak dostawcy odpowiadają. Pierwsze hotele pojawiają się szybko. Kosztem jest złożoność we wszystkich pozostałych miejscach: lista zmienia kolejność, gdy użytkownik ją czyta, etykieta „najtaniej” może się przesunąć, a hotel, który przyszedł od jednego dostawcy, może później dostać niższą stawkę od innego.
Jeśli po drugiej stronie wyszukiwarki siedzi człowiek, podejście progresywne jest niemal zawsze właściwe. Ta osoba przegląda oferty, a nie uruchamia zadanie wsadowe, a strona, która widocznie pracuje, wygrywa ze stroną, która w ciszy myśli. Jeśli twoim odbiorcą jest inna maszyna, na przykład zadanie porównujące stawki albo firmowe narzędzie rezerwacyjne, które potrzebuje jednej ostatecznej odpowiedzi, czekanie bywa prostsze i po prostu poprawne.
Cokolwiek wybierzesz, trzy zasady pozwalają utrzymać progresywnego klienta w ryzach:
- Każda partia niesie stan ukończenia całego wyszukiwania, żeby klient odróżniał „na razie nie ma więcej wyników” od „więcej wyników już nie będzie”.
- Wyniki są scalane po stabilnym kluczu hotelu po stronie serwera, a nie dopisywane na końcu. Klient nigdy nie powinien sam dochodzić do tego, że dwie karty to ten sam budynek.
- Sortowanie po cenie jest tymczasowe, dopóki wyszukiwanie się nie zakończy, i interfejs mówi o tym wprost. Użytkownicy wybaczą listę, która się jeszcze układa; nie wybaczą etykiety „najniższa cena”, która okazała się nieprawdziwa.
Jak modelować pokoje i plany taryfowe, żeby się nie posypały
Tu właśnie większość integracji hotelowych po cichu zawodzi, a ta porażka wychodzi na jaw po kilku miesiącach jako zgłoszenie do supportu, a nie jako raport o błędzie.
Kuszący model jest płaski: hotel ma listę ofert, każda oferta ma nazwę pokoju i cenę. Ładnie się renderuje. Potem jeden dostawca zwraca „Deluxe King” i „Deluxe Room, 1 King Bed” dla czegoś, co jest oczywiście tym samym pokojem, drugi używa tej samej nazwy dla dwóch naprawdę różnych pokoi (jeden z widokiem na miasto, drugi bez), a trzeci podaje stawkę za noc, podczas gdy wszyscy inni podają cenę za cały pobyt. Płaska lista nie powie ci, z którym z tych przypadków masz do czynienia. Po prostu je wyświetli.
Model, który przetrwa zderzenie z prawdziwymi dostawcami, ma co najmniej cztery poziomy i trzyma je osobno:
| Poziom | Co przechowuje | Błąd, którego trzeba unikać |
|---|---|---|
| Hotel | Twój własny stabilny identyfikator, zmapowany na kod każdego dostawcy | Używanie identyfikatora hotelu od dostawcy jako klucza głównego |
| Pokój | Obłożenie, układ łóżek, oryginalny opis pokoju od dostawcy zachowany dosłownie | „Porządkowanie” nazw pokoi tak długo, aż dwa różne pokoje zleją się w jeden |
| Plan taryfowy | Rodzaj wyżywienia, zwrotność, sposób płatności, dostawca, od którego pochodzi | Traktowanie śniadania albo zwrotności jako części nazwy pokoju |
| Cena | Suma za pobyt, waluta, które podatki i opłaty są w niej zawarte, a które płaci się w hotelu | Pokazywanie kwoty za noc obok kwot za pobyt albo ukrywanie opłat płatnych przy przyjeździe |
Możesz się nie zgadzać z tym, gdzie przebiegają granice. Niektóre zespoły wydzielają obłożenie jako osobny poziom i to rozsądne, gdy tylko zaczynasz sprzedawać rezerwacje wielopokojowe. Nie możesz natomiast scalać poziomów tylko dlatego, że interfejs pokazuje dwa z nich. Interfejs może spłaszczać dane przy renderowaniu. Same dane nie.
Jeden szczegół zasługuje na osobne zdanie: przechowuj surowy opis pokoju od dostawcy obok wszystkiego, co normalizujesz. Kiedy gość przyjedzie i dostanie inny pokój niż ten na voucherze, pierwsze pytanie, jakie wszyscy zadadzą, będzie brzmiało: co właściwie przysłał dostawca?
Warunki anulacji to dane, a nie akapit
Wielu dostawców zwraca warunki anulacji jako wolny tekst: „Bezpłatna anulacja do 3 dni przed przyjazdem, później opłata za 1 noc”. Bardzo kusi, żeby wyświetlić ten napis i pójść dalej.
Nie rób tego. Tekstu nie da się porównać, posortować, przefiltrować ani egzekwować. Użytkownik chce przefiltrować wyniki do stawek zwrotnych. Dział finansów chce wiedzieć, które rezerwacje jutro staną się bezzwrotne, żeby biuro podróży zdążyło skontaktować się z klientem przed upływem terminu. Proces po rezerwacji musi powiedzieć klientowi, w chwili gdy naciska „anuluj”, dokładnie ile zapłaci. Nic z tego nie zadziała na podstawie zdania.
Modeluj każde warunki jako uporządkowaną listę okien karnych: od tej chwili do tamtej chwili opłata wynosi tyle (albo taki udział w cenie pobytu, albo tyle nocy). Granice to znaczniki czasu ze strefą czasową, i to strefą hotelu, nie twojego serwera ani użytkownika, bo „3 dni przed przyjazdem” to inny moment w zależności od tego, czyją północ liczysz. Przechowuj oryginalny tekst dostawcy obok wersji ustrukturyzowanej, pokazuj wersję ustrukturyzowaną, a rozbieżność między nimi traktuj jako coś do zbadania, a nie do ukrycia.
I sprawdzaj warunki ponownie w momencie rezerwacji, nie tylko przy wyszukiwaniu. Zmieniają się między tymi dwoma wywołaniami częściej, niż ktokolwiek się spodziewa.
Ile naprawdę kosztuje zrobienie tego źle
Wolne wyszukiwanie kosztuje cię konwersje. To źle, ale przynajmniej widać: ktoś się poskarży. Drogie porażki to te ciche.
Stawka pokazana jako zwrotna, którą dostawca traktuje jako bezzwrotną, oznacza spór z klientem, który ma zrzut ekranu, a karę zwykle w końcu płaci samo biuro podróży. Cena za noc wyświetlona jako suma za pobyt sprzedaje pokoje poniżej kosztów, dopóki ktoś w księgowości tego nie zauważy. Pokój scalony z innym pokojem wysyła czteroosobową rodzinę do pokoju dla dwojga. Opłaty płatne w hotelu, których nigdy nie pokazano, zamieniają pięciogwiazdkową opinię w chargeback. Każdy z tych przypadków to decyzja modelowa podjęta w pierwszym sprincie, zwykle pod hasłem „posprzątamy to później”.
Cache: co możesz trzymać, a czego nie wolno
Każdy zespół, który integruje hotelowe API, prędzej czy później pyta, czy może cache’ować wyniki, żeby wyszukiwanie było szybsze i tańsze. Odpowiedź brzmi: tak, ale tylko dla części danych, a granica między nimi ma większe znaczenie niż jakiekolwiek liczby o wydajności.
Treści statyczne, czyli nazwy hoteli, adresy, współrzędne, zdjęcia, listy udogodnień i opisy pokoi, zmieniają się rzadko i to właśnie je warto agresywnie cache’ować we własnym magazynie. Sprawdź jednak w warunkach dostawcy, jak wolno ci je przechowywać i wyświetlać; niektóre licencje to ograniczają. Pobieranie ich na żywo przy każdym wyszukiwaniu jest wolne i nic nie daje.
Stawki i dostępność na żywo to zupełnie inna sprawa. Cena z cache to zgadywanie, ile policzy dostawca, a dostawcy nie honorują twoich zgadywań. Krótkotrwałe cache’owanie wyników wyszukiwania bywa akceptowalne do wyświetlenia strony, pod warunkiem że każda ścieżka rezerwacji ponownie wycenia ofertę u dostawcy, zanim pobierze pieniądze, a interfejs traktuje zmienioną cenę jako normalny wynik, a nie błąd. Niektórzy dostawcy ograniczają też, jak często możesz wyszukiwać w stosunku do tego, jak często rezerwujesz; agresywny cache, który ukrywa przed nimi twój prawdziwy ruch, nie jest furtką, na której warto polegać.
Czego nigdy nie wolno cache’ować, to wszystko, co oznacza zobowiązanie: zablokowany token ceny, numer rezerwacji, wycena anulacji. Te rzeczy należą do jednego użytkownika i jednej chwili.
Zanim uznasz, że gotowe
Krótka lista kontrolna, którą warto przejść na własnej integracji, zanim zacznie obsługiwać prawdziwe rezerwacje:
- Wyszukiwanie zwraca stan ukończenia, a klient zachowuje się inaczej przed nim i po nim.
- Hotele są kluczowane twoim własnym identyfikatorem, a kod każdego dostawcy jest na niego zmapowany.
- Pokój, plan taryfowy i cena to w twoich danych osobne obiekty, niezależnie od tego, co pokazuje ekran.
- Każda cena mówi, czy jest za noc, czy za pobyt, i co trzeba zapłacić przy przyjeździe.
- Warunki anulacji są zapisane jako czasowe okna karne w strefie czasowej hotelu, razem z oryginalnym tekstem.
- Ścieżka rezerwacji ponownie wycenia ofertę i ponownie odczytuje warunki, zanim komukolwiek coś pobierze.
- Nic, co oznacza zobowiązanie, nie jest nigdy serwowane z cache.
Jeśli zastanawiasz się, czy budować to wszystko osobno dla każdego dostawcy, czy zacząć od platformy, która te problemy już przerobiła, strona kontraktowa liczy się tak samo jak kod. Nasz tekst o kontraktach z konsolidatorami hotelowymi i stawkach z bedbanku opisuje, o co warto zapytać. Nasze własne API lotnicze i hotelowe udostępniamy po rozmowie, a nie przez samoobsługowy klucz; jeśli chcesz sprawdzić tę drogę, zacznij tę rozmowę na stronie o travel API.
Fan-out nigdy nie zniknie. Dobry klient po prostu przestaje udawać, że go nie ma.