Pređi na sadržaj
Blog

API за доступност хотела: дизајн за споре добављаче

Редакција Tekravel
Napisano uz pomoć veštačke inteligencije

Задатак обично стигне безазлен. „Додајте претрагу хотела на страницу за резервације — добављач нам је дао API за доступност хотела, постоји sandbox, биће један спринт.“ Прочитате документацију, пошаљете захтев за двоје одраслих у Београду на три ноћи и стигне одговор. Онда пошаљете исти захтев за град са много више смештаја и дуго, непријатно дуго се ништа не дешава. Када одговор најзад стигне, то је документ толико велик да ваш JSON парсер почиње да преиспитује своје животне изборе.

У том тренутку посао мења облик. Доступност хотела није упит у табелу. То је fan-out: једно питање вашег корисника постаје много питања ка много добављача, а сваки од њих одговара сопственом брзином, сопственим речником и са сопственом представом о томе шта је „соба“. Клијент који правите мора остати користан док се тај fan-out још одвија. Овај текст говори о пројектовању таквог клијента — написан је за програмера који добро познаје REST и JSON, али никада није морао да објашњава хотелу зашто је гостова неповратна цена приказана као бесплатно отказивање.

Зашто је API за доступност хотела спорији од endpoint-а на које сте навикли

Споља, претрага лета и претрага хотела изгледају слично: оде упит, врате се понуде са ценама. Испод површине, то није исти проблем. Ако сте читали наше белешке о томе шта интеграција API за резервацију летова заиста подразумева, већ знате да цена из претраге није увек цена по којој резервишете. Хотели томе додају још једну тешкоћу: обим.

Један једини град може имати стотине смештајних објеката. Сваки објекат продаје неколико типова соба. Сваки тип собе продаје се под неколико rate plans — са доручком, без њега, повратно, неповратно, цена за чланове, пакет цена. А сваки rate plan може долазити од више од једног добављача: од bedbank-а, од channel manager-а, из директног уговора, од велетрговца с којим сте потписали уговор зато што је његов allotment у одређеном хотелу био бољи од свих осталих. Помножите то и „једноставна“ претрага постаје велико стабло, састављено из више извора који се не слажу ни око назива ни око идентификатора.

Дакле, спори део ретко је ваш код. То је најспорији добављач кога сте одлучили да чекате.

Постепени резултати или цео одговор: бирајте свесно

Постоје два поштена начина да вратите резултате претраге хотела, а већина интеграција заврши негде несрећно у средини.

Чекате све. Бекенд ради fan-out, чека да сваки добављач одговори или да истекне тајмаут, спаја, уклања дупликате, сортира и враћа једну комплетну листу. Резултат је чист: један захтев, један одговор, цене које се могу поредити јер су све на столу. Цена је то што корисник гледа индикатор учитавања онолико дуго колико треба вашем најспоријем добављачу. Сваки пут.

Шаљете оно што имате. Бекенд покреће fan-out и одмах враћа search handle. Клијент периодично проверава handle или држи отворен stream и прима резултате у пакетима, како добављачи одговарају. Први хотели се појављују брзо. Цена је сложеност свуда другде: листа се преуређује док је корисник чита, ознака „најјефтиније“ може да се помери, а хотел који је стигао од једног добављача касније може добити нижу цену од другог.

Ако је ваш интерфејс страница за претрагу пред човеком, постепени приступ је скоро увек исправан — човек прегледа, не покреће batch посао, а страница која видљиво ради побеђује страницу која тихо размишља. Ако је потрошач друга машина — посао поређења цена, корпоративни алат за резервације коме треба један коначан одговор — чекање је често једноставније и исправно.

Шта год да изаберете, три правила држе постепеног клијента при здравој памети:

  • Сваки пакет носи стање завршености претраге у целини, да би клијент разликовао „још нема нових резултата“ од „неће више бити резултата“.
  • Резултати се спајају по стабилном кључу хотела на серверу, а не само додају на крај. Клијент никада не би требало сам да закључује да су две картице иста зграда.
  • Сортирање по цени је привремено док се претрага не заврши, и интерфејс то каже. Корисници опраштају листи која се смири; не опраштају ознаку „најнижа цена“ која се испостави као погрешна.

Моделовање соба и rate plans тако да се не уруше

Овде већина хотелских интеграција тихо пропада, а неуспех се појављује месецима касније као захтев подршци, а не као пријава грешке.

Примамљив модел је раван: хотел има листу понуда, свака понуда има назив собе и цену. Лепо изгледа на екрану. Онда један добављач врати „Deluxe King“ и „Deluxe Room, 1 King Bed“ за очигледно исту собу, други врати исти назив за две заиста различите собе (једна са погледом на град, друга без), а трећи врати цену по ноћи док сви остали дају цену за цео боравак. Равна листа не може да вам каже шта од тога гледате. Она их само приказује.

Модел који преживи сусрет са стварним добављачима има бар четири нивоа и држи их одвојено:

НивоШта садржиГрешка коју треба избећи
ХотелВаш сопствени стабилан ID, повезан са кодом сваког добављачаКоришћење hotel ID-а добављача као примарног кључа
СобаПопуњеност, распоред кревета, оригинални текст собе од добављача без измена„Чишћење“ назива соба док се две различите собе не стопе у једну
Rate planУслуга исхране, повратност, начин плаћања, добављач од кога је стигаоТретирање доручка или повратности као дела назива собе
ЦенаУкупно за боравак, валута, који порези и таксе су укључени а који се плаћају у хотелуПриказивање цене по ноћи поред цена за боравак, или скривање такси које се плаћају по доласку

Можете се не сложити око тога где иду границе — неки тимови издвајају попуњеност у засебан ниво, што има смисла чим продајете резервације за више соба. Оно што не можете јесте да спајате нивое зато што интерфејс приказује само два од њих. Интерфејс може да споји податке приликом приказа. Подаци не смеју.

Један детаљ заслужује сопствену реченицу: чувајте оригинални опис собе од добављача поред свега што нормализујете. Када гост стигне и добије другу собу од оне на ваучеру, прво што ће неко питати јесте шта је добављач заправо послао.

Услови отказивања су подаци, а не пасус

Многи добављачи враћају услове отказивања као слободан текст: „Бесплатно отказивање до 3 дана пре доласка, након тога наплата 1 ноћи.“ Веома је примамљиво приказати тај низ и кренути даље.

Немојте. Текст се не може поредити, сортирати, филтрирати ни спроводити. Ваш корисник жели да филтрира само повратне цене. Финансије желе да знају које резервације сутра постају неповратне, да би агенција стигла да контактира клијента пре истека рока. Ток после резервације мора да каже купцу, у тренутку кад притисне „откажи“, тачно колико ће платити. Ништа од тога не ради над реченицом.

Моделујте сваки услов као уређену листу казнених прозора: од овог тренутка до оног наплата је толика (или такав удео боравка, или толико ноћи). Границе су временске ознаке са временском зоном — временском зоном хотела, не вашег сервера и не корисника — јер „3 дана пре доласка“ значи различит тренутак у зависности од тога чију поноћ рачунате. Чувајте оригинални текст добављача поред структуриране верзије, приказујте структурирану, а неслагање између њих третирајте као нешто што треба истражити, а не сакрити.

И проверите услове поново при резервацији, не само при претрази. Мењају се између та два позива чешће него што ико очекује.

Колико грешка заиста кошта

Спора претрага кошта вас конверзија — лоше, али видљиво; неко ће се жалити. Скупи неуспеси су они тихи.

Цена приказана као повратна, коју добављач третира као неповратну, значи спор са купцем који има снимак екрана, а казну обично на крају плати сама агенција. Цена по ноћи приказана као укупна цена боравка продаје собе испод цене коштања док неко у рачуноводству не примети. Соба спојена са другом собом шаље четворочлану породицу у собу за двоје. Таксе које се плаћају у хотелу, а никада нису приказане, претварају рецензију са пет звездица у chargeback. Свака од ових ствари је одлука о моделу донета у првом спринту, обично под етикетом „средићемо касније“.

Кеширање: шта смете да задржите, а шта не

Сваки тим који интегрише хотелски API пре или касније пита да ли може да кешира резултате како би претрага била бржа и јефтинија. Одговор је да, за неке ствари — а граница између њих важнија је од било ког броја о перформансама.

Статички садржај — називи хотела, адресе, координате, фотографије, листе садржаја, описи соба — ретко се мења и управо је оно што треба да кеширате, агресивно, у сопственом складишту. Проверите услове добављача о томе како смете да га чувате и приказујете; неке лиценце то ограничавају. Преузимати га уживо при свакој претрази споро је и без користи.

Цене и доступност уживо су друга прича. Кеширана цена је нагађање о томе шта ће добављач наплатити, а добављачи не поштују ваша нагађања. Краткотрајно кеширање резултата претраге може бити прихватљиво за приказ странице — под условом да сваки пут ка резервацији поново провери цену код добављача пре него што узме новац, и да интерфејс третира промењену цену као нормалан исход, а не као грешку. Неки добављачи такође ограничавају колико често смете да претражујете у односу на то колико често резервишете; агресивно кеширање које од њих крије ваш стварни саобраћај није рупа у правилима на коју се вреди ослонити.

Оно што никада не смете кеширати јесте све што представља обавезу: задржани ценовни токен, број резервације, понуду за отказивање. Они припадају једном кориснику и једном тренутку.

Пре него што кажете да је готово

Кратка провера коју вреди покренути над сопственом интеграцијом пре него што почне да носи праве резервације:

  • Претрага враћа стање завршености, а клијент се понаша различито пре и после њега.
  • Хотели имају као кључ ваш сопствени ID, са кодом сваког добављача повезаним с њим.
  • Соба, rate plan и цена су засебни објекти у вашим подацима, шта год екран приказивао.
  • Свака цена каже да ли је по ноћи или за боравак, и шта се плаћа по доласку.
  • Услови отказивања чувају се као временски казнени прозори у временској зони хотела, уз сачуван оригинални текст.
  • Пут ка резервацији поново проверава цену и поново чита услове пре него што било кога задужи.
  • Ништа што представља обавезу никада се не служи из кеша.

Ако одмеравате да ли да све ово правите према појединачним добављачима или да кренете од платформе која се са овим проблемима већ сусрела, уговорна страна важна је колико и код — наш текст о уговорима са хотелским консолидаторима и bedbank ценама објашњава шта треба тражити. Наши сопствени API за летове и хотеле отварају се кроз разговор, а не самоуслужним кључем; ако је то пут који желите да истражите, започните разговор на страници travel APIs.

Fan-out никада не нестаје. Добар клијент само престане да се претвара да га нема.

Редакција Tekravel

Деск за путничке технологије

Деск за путничке технологије Tekravel-а пише за струку: власнике агенција, консолидаторе и програмере који их интегришу. Сваки чланак се пре објаве проверава на платформи коју описује.