Қонақүй бос нөмірлері API: баяу жеткізушілерге дайындық

Тапсырма әдетте зиянсыз көрінеді. «Брондау бетіне қонақүй іздеуін қосу керек — жеткізуші қонақүй бос нөмірлері API-ін берді, sandbox бар, бір спринтте бітеді». Құжаттаманы оқисыз, Дубайға екі ересекке үш түнге сұрау жібересіз — жауап келеді. Содан кейін дәл сол сұрауды нысандары көбірек қалаға жібересіз де, ұзақ әрі ыңғайсыз уақыт бойы ештеңе келмейді. Ақыры келгенде, бұл JSON парсеріңізді өмірдің мәні туралы ойландыратындай үлкен құжат болып шығады.
Дәл осы сәтте жұмыстың сипаты өзгереді. Қонақүйдің бос нөмірлерін іздеу — қарапайым lookup емес. Бұл тарату (fan-out): пайдаланушының бір сұрағы көптеген жеткізушіге қойылатын көп сұраққа айналады, ал олардың әрқайсысы өз жылдамдығымен, өз терминологиясымен, «нөмір» деген не екені туралы өз түсінігімен жауап береді. Сіз жасайтын клиент осы тарату әлі аяқталмай тұрғанда да пайдалы болып қалуы тиіс. Бұл мақала сол клиентті жобалау туралы. Ол REST пен JSON-ды жақсы білетін, бірақ қонақүйге қонақтың қайтарылмайтын тарифі неге тегін күшін жою ретінде көрсетілгенін әлі түсіндіріп көрмеген әзірлеушіге арналған.
Қонақүй бос нөмірлері API неге сіз үйренген эндпоинттерден баяу
Сырттай қарағанда авиабилет іздеу мен қонақүй іздеу ұқсас: сұрау кетеді, бағасы бар нұсқалар қайтады. Ішінде бұлар бір мәселе емес. Егер авиабилет брондау API интеграциясы шын мәнінде нені қамтитыны туралы жазбамызды оқыған болсаңыз, іздеген баға мен брондайтын баға әрдайым сәйкес келмейтінін білесіз. Қонақүйлер оның үстіне екінші қиындық қосады: көлем.
Бір қалада жүздеген нысан болуы мүмкін. Әр нысан бірнеше нөмір түрін сатады. Әр нөмір түрі бірнеше тарифтік жоспармен сатылады — таңғы асымен немесе онсыз, қайтарылатын, қайтарылмайтын, мүшелерге арналған тариф, пакеттік тариф. Әр тарифтік жоспар бірнеше жеткізушіден келуі мүмкін: bedbank, channel manager, тікелей келісімшарт, бір қонақүйдегі allotment-і басқалардікінен жақсы болғандықтан қол қойған көтерме сатушы. Осының бәрін көбейтсеңіз, «қарапайым» іздеу атаулар мен ID-лер бойынша бір-бірімен келіспейтін бірнеше көзден құралған үлкен ағашқа айналады.
Сондықтан баяу бөлік сирек жағдайда ғана сіздің кодыңыз болады. Әдетте бұл — күтуді өзіңіз таңдаған ең баяу жеткізуші.
Біртіндеп нәтиже ме, әлде толық жауап па: саналы түрде таңдаңыз
Қонақүй іздеу нәтижелерін қайтарудың екі адал жолы бар, ал интеграциялардың көбі ақыры екеуінің ортасындағы жайсыз бір жерге тоқтайды.
Барлығын күту. Бэкенд сұрауды таратады, әр жеткізуші жауап бергенше немесе таймаутқа түскенше күтеді, нәтижелерді біріктіреді, қайталанғандарды алып тастайды, сұрыптайды және бір толық тізім қайтарады. Нәтиже таза: бір сұрау, бір жауап, бағалардың бәрі үстелде тұрғандықтан оларды салыстыруға болады. Бағасы — пайдаланушыңыз ең баяу жеткізуші қанша уақыт алса, сонша айналып тұрған жүктелу белгісіне қарап отырады. Әр жолы.
Барын ағынмен беру. Бэкенд таратуды бастайды да, бірден іздеу идентификаторын (handle) қайтарады. Клиент сол handle-ды кезекпен сұрап отырады немесе ағынды ашық ұстайды, ал нәтижелер жеткізушілер жауап берген сайын топ-топ болып келеді. Алғашқы қонақүйлер тез көрінеді. Бағасы — қалған жердің бәріндегі күрделілік: пайдаланушы оқып отырғанда тізімнің реті өзгереді, «ең арзан» белгісі орнын ауыстыруы мүмкін, ал бір жеткізушіден шыққан қонақүй кейін басқасынан арзанырақ тариф алуы ықтимал.
Егер интерфейсіңіз адамның алдындағы іздеу беті болса, біртіндеп нәтиже беру дерлік әрқашан дұрыс: адам шолып отыр, пакеттік тапсырма іске қосып отырған жоқ, ал жұмыс істеп жатқаны көрініп тұрған бет үнсіз ойланып тұрған беттен әлдеқайда жақсы. Ал тұтынушыңыз басқа машина болса — тарифтерді салыстыратын тапсырма немесе бір нақты жауап қажет корпоративтік брондау құралы — күту көбіне әрі қарапайым, әрі дұрыс.
Қайсысын таңдасаңыз да, біртіндеп жұмыс істейтін клиентті ретте ұстайтын үш ереже бар:
- Әр топ бүкіл іздеудің аяқталу күйін алып жүреді, сонда клиент «әзірге басқа нәтиже жоқ» пен «енді ешқашан нәтиже болмайды» дегенді ажырата алады.
- Нәтижелер серверде тізімнің соңына жай қосылмайды, тұрақты қонақүй кілті бойынша біріктіріледі. Екі карточканың бір ғимарат екенін клиент өзі анықтауға тиіс емес.
- Бағасы бойынша сұрыптау іздеу аяқталғанша уақытша болады, мұны интерфейс ашық айтады. Пайдаланушылар орнығып жатқан тізімді кешіреді; кейін қате болып шыққан «ең төмен баға» белгісін кешірмейді.
Нөмірлер мен тарифтік жоспарларды араластырмай модельдеу
Қонақүй интеграцияларының көбі дәл осы жерде үнсіз сәтсіздікке ұшырайды, ал бұл сәтсіздік бірнеше айдан кейін баг туралы есеп ретінде емес, қолдау қызметіне түскен өтініш ретінде шығады.
Ең оңай көрінетін модель — жалпақ модель: қонақүйде ұсыныстар тізімі бар, әр ұсыныста нөмір атауы мен баға. Экранда әдемі көрінеді. Сосын бір жеткізуші анық бір нөмір үшін «Deluxe King» және «Deluxe Room, 1 King Bed» қайтарады, екіншісі шын мәнінде екі түрлі нөмірге (біреуінен қала көрінеді, біреуінен көрінбейді) бірдей атау береді, ал үшіншісі басқалардың бәрі бүкіл тұру мерзіміне баға бергенде, бір түннің бағасын қайтарады. Жалпақ тізім осылардың қайсысына қарап тұрғаныңызды айта алмайды. Ол оларды жай ғана көрсетеді.
Нақты жеткізушілермен кездескенде аман қалатын модельде кемінде төрт деңгей болады, және олар бір-бірінен бөлек сақталады:
| Деңгей | Нені сақтайды | Неден аулақ болу керек |
|---|---|---|
| Қонақүй | Әр жеткізушінің кодымен сәйкестендірілген өз тұрақты ID-іңіз | Жеткізушінің қонақүй ID-ін бастапқы кілт ретінде пайдалану |
| Нөмір | Сыйымдылық, төсек конфигурациясы, жеткізушінің нөмір мәтіні сөзбе-сөз сақталған күйде | Екі түрлі нөмір біреуге қосылып кеткенше нөмір атауларын «тазалау» |
| Тарифтік жоспар | Тамақтану түрі, қайтарылуы, төлем түрі, қай жеткізушіден келгені | Таңғы асты немесе қайтарылуды нөмір атауының бөлігі деп санау |
| Баға | Бүкіл тұру мерзімінің жалпы сомасы, валюта, ішіне қандай салықтар мен алымдар кіретіні және қайсысы қонақүйде төленетіні | Бір түнгі соманы бүкіл мерзімге арналған сомалардың жанына қою немесе келгенде төленетін алымдарды жасыру |
Шекаралардың қай жерден өтетінімен келіспеуіңіз мүмкін — кейбір командалар сыйымдылықты жеке деңгейге бөледі, бұл бірнеше нөмірлік брондау сата бастағанда әбден орынды. Бірақ интерфейс екеуін ғана көрсететіндіктен деңгейлерді біріктіруге болмайды. Интерфейс көрсету сәтінде жалпақтай алады. Деректер жалпақтамауы тиіс.
Бір нюанс жеке сөйлемге лайық: нені қалыпқа келтірсеңіз де, жеткізушінің нөмір туралы бастапқы сипаттамасын қатар сақтаңыз. Қонақ келгенде оған ваучердегіден басқа нөмір берілсе, кез келген адам ең алдымен жеткізуші шынымен не жібергенін сұрайды.
Күшін жою саясаты — абзац емес, деректер
Көп жеткізуші күшін жою шарттарын еркін мәтінмен қайтарады: «Келуден 3 күн бұрынға дейін тегін күшін жою, одан кейін 1 түн айыппұл». Сол жолды экранға шығарып, әрі қарай кете салу өте азғырады.
Олай істемеңіз. Мәтінді салыстыру, сұрыптау, сүзу немесе орындату мүмкін емес. Пайдаланушыңыз тек қайтарылатын тарифтерді сүзгісі келеді. Қаржы бөлімі ертең қай брондаулар қайтарылмайтын болатынын білгісі келеді, сонда агенттік мерзім өтпей тұрып клиентпен хабарласа алады. Брондаудан кейінгі процесс клиентке күшін жою батырмасын басқан сәтте дәл қанша сома ұсталатынын айтуы керек. Мұның ешқайсысы бір сөйлеммен жұмыс істемейді.
Әр саясатты айыппұл терезелерінің реттелген тізімі ретінде модельдеңіз: осы сәттен бастап сол сәтке дейін ұсталатын сома мынау (немесе тұру құнының мынадай үлесі, немесе мынанша түн). Шекаралар — уақыт белдеуі көрсетілген timestamp-тар, және бұл белдеу сіздің серверіңіздікі де, пайдаланушынікі де емес, қонақүйдікі, өйткені «келуден 3 күн бұрын» кімнің түн ортасынан санағаныңызға қарай әртүрлі сәтті білдіреді. Жеткізушінің бастапқы мәтінін құрылымдалған нұсқаның жанында сақтаңыз, экранда құрылымдалғанын көрсетіңіз, ал екеуінің арасындағы сәйкессіздікті жасыратын нәрсе емес, тексеретін нәрсе деп қараңыз.
Саясатты тек іздеу кезінде емес, брондау сәтінде де қайта тексеріңіз. Саясаттар осы екі шақырудың арасында кез келген адам күткеннен жиі өзгереді.
Қателіктің шын бағасы
Баяу іздеу конверсияны жоғалтады — бұл жаман, бірақ көзге көрінеді: біреу міндетті түрде шағымданады. Қымбатқа түсетіні — үнсіз сәтсіздіктер.
Жеткізуші қайтарылмайтын деп санайтын тарифті қайтарылатын етіп көрсету — қолында скриншоты бар клиентпен дау, ал айыппұлды әдетте агенттіктің өзі төлеп шығады. Бір түнгі бағаны бүкіл мерзімнің сомасы ретінде көрсету бухгалтериядағы біреу байқағанша нөмірлерді өзіндік құнынан төмен сатады. Басқа нөмірмен біріктіріліп кеткен нөмір төрт адамдық отбасын екі адамға арналған бөлмеге жібереді. Ешқашан көрсетілмеген, қонақүйде төленетін алымдар бес жұлдызды пікірді chargeback-ке айналдырады. Әрқайсысы — бірінші спринтте, әдетте «кейін ретке келтіреміз» деген желеумен қабылданған модельдеу шешімі.
Кэштеу: нені сақтауға болады, нені болмайды
Қонақүй API-ін біріктіретін әр команда ерте ме, кеш пе іздеуді жылдамырақ әрі арзанырақ ету үшін нәтижелерді кэштеуге бола ма деп сұрайды. Жауабы: иә, кейбір нәрселер үшін, және олардың арасындағы шекара кез келген өнімділік көрсеткішінен маңыздырақ.
Статикалық контент — қонақүй атаулары, мекенжайлар, координаттар, фотосуреттер, қызметтер тізімі, нөмір сипаттамалары — сирек өзгереді, және дәл соны өз қоймаңызда батыл кэштеу керек. Оны қалай сақтап, қалай көрсетуге болатыны туралы жеткізушінің шарттарын тексеріңіз; кейбір лицензиялар мұны шектейді. Оны әр іздеуде тікелей сұрау еш пайдасыз баяулатады.
Тірі тарифтер мен бос орындар — басқа әңгіме. Кэштелген баға — жеткізуші қанша сұрайтыны туралы болжам ғана, ал жеткізушілер сіздің болжамыңызды мойындамайды. Іздеу нәтижелерін қысқа уақытқа кэштеу бетті көрсету үшін қолайлы болуы мүмкін — тек ақша алмас бұрын әр брондау жолы жеткізушіден бағаны қайта алса және интерфейс өзгерген бағаны қате емес, қалыпты нәтиже деп қабылдаса. Кейбір жеткізушілер іздеу санын брондау санына шаққанда шектейді; нақты трафигіңізді олардан жасыратын агрессивті кэштеу — сенім артуға тұрарлық олқылық емес.
Міндеттемені білдіретін ештеңені ешқашан кэштемеңіз: ұсталған баға токенін, брондау нөмірін, күшін жою бойынша есептемені. Олар бір пайдаланушыға және бір сәтке тиесілі.
«Дайын» деп айтпас бұрын
Нақты брондауларды қабылдамас бұрын өз интеграцияңызда жүргізуге тұрарлық қысқа тексеру:
- Іздеу аяқталу күйін қайтарады, ал клиент оған дейін және одан кейін әртүрлі әрекет етеді.
- Қонақүйлер сіздің өз ID-іңізбен кілттеледі, әр жеткізушінің коды соған сәйкестендірілген.
- Экранда не көрсетілсе де, деректеріңізде нөмір, тарифтік жоспар және баға бөлек объектілер.
- Әр баға бір түнге ме, бүкіл мерзімге ме екенін және келгенде не төленетінін айтады.
- Күшін жою саясаттары қонақүйдің уақыт белдеуіндегі уақытпен белгіленген айыппұл терезелері ретінде сақталады, бастапқы мәтін де қалады.
- Брондау жолы біреуден ақша алмас бұрын бағаны қайта алады және саясатты қайта оқиды.
- Міндеттемені білдіретін ештеңе ешқашан кэштен берілмейді.
Осының бәрін жеке жеткізушілермен өзіңіз құру мен бұл мәселелермен бұрыннан бетпе-бет келген платформадан бастауды салыстырып отырсаңыз, келісімшарт жағы кодтан кем маңызды емес — қонақүй консолидаторымен келісімшарттар және bedbank тарифтері туралы мақаламыз нені сұрау керектігін қарастырады. Біздің авиабилет пен қонақүй API-ларымыз өз бетінше алынатын кілт арқылы емес, әңгіме арқылы ашылады; егер дәл осы жолды зерттегіңіз келсе, сол әңгімені travel APIs бетінде бастаңыз.
Тарату ешқашан жоғалмайды. Жақсы клиент оны жоқ сияқты көрсетуге тырыспайды, болғаны сол.