Перейти к содержимому
Блог

API доступности отелей: клиент для медленных поставщиков

Редакция Tekravel
Написано с помощью ИИ

Задача обычно приходит в безобидной формулировке: «Добавить поиск отелей на страницу бронирования — поставщик дал нам API доступности отелей, есть песочница, это на один спринт». Вы читаете документацию, отправляете запрос на двух взрослых в Стамбуле на три ночи — ответ приходит. Затем отправляете тот же запрос для города, где объектов размещения гораздо больше, и долгое, неловкое время не приходит ничего. А когда приходит, это документ такого размера, что ваш JSON-парсер начинает сомневаться в выборе профессии.

Именно в этот момент работа меняет форму. Доступность отелей — это не поиск по ключу. Это fan-out: один вопрос пользователя превращается во множество вопросов множеству поставщиков, и каждый отвечает со своей скоростью, своим словарём и своим представлением о том, что такое «номер». Клиент, который вы строите, должен оставаться полезным, пока этот разлёт запросов ещё не завершился. Эта статья — о проектировании такого клиента. Она написана для разработчика, который хорошо знает REST и JSON, но ни разу не объяснял отелю, почему невозвратный тариф был показан гостю как тариф с бесплатной отменой.

Почему API доступности отелей медленнее привычных эндпоинтов

Поиск авиабилетов и поиск отелей снаружи похожи: запрос уходит, возвращаются варианты с ценами. Внутри это разные задачи. Если вы читали наши заметки о том, что на самом деле означает интеграция API авиабилетов, вы уже знаете, что цена при поиске — не всегда цена при бронировании. Отели добавляют поверх этого вторую сложность: объём.

В одном городе могут быть сотни объектов. Каждый продаёт несколько категорий номеров. Каждая категория продаётся по нескольким тарифным планам — с завтраком и без, возвратный и невозвратный, тариф для участников программы, пакетный тариф. Каждый тарифный план может приходить от нескольких поставщиков: bedbank, channel manager, прямой контракт, оптовик, с которым вы подписали договор, потому что его allotment в конкретном отеле был лучше, чем у остальных. Перемножьте всё это — и «простой» поиск окажется большим деревом, собранным из источников, которые не сходятся ни в названиях, ни в идентификаторах.

Так что медленная часть — редко ваш код. Это самый медленный поставщик, которого вы решили дождаться.

Постепенные результаты или полный ответ: выбирайте осознанно

Есть два честных способа возвращать результаты поиска отелей, и большинство интеграций застревают где-то посередине, в неудобном компромиссе.

Ждать всех. Бэкенд рассылает запрос, ждёт, пока каждый поставщик ответит или отвалится по таймауту, объединяет, убирает дубли, сортирует и возвращает один полный список. Результат чистый: один запрос, один ответ, сопоставимые цены, потому что все они на столе. Плата за это: пользователь каждый раз смотрит на индикатор загрузки ровно столько, сколько отвечает ваш самый медленный поставщик.

Отдавать то, что пришло. Бэкенд запускает рассылку и сразу возвращает идентификатор поиска. Клиент опрашивает его или держит открытый поток и получает результаты пачками по мере ответов поставщиков. Первые отели появляются быстро. Плата — сложность во всём остальном: список перестраивается, пока пользователь его читает, значок «самый дешёвый» может переехать, а отель, пришедший от одного поставщика, позже может получить более низкую цену от другого.

Если ваш интерфейс — страница поиска перед живым человеком, постепенная выдача почти всегда правильна: человек просматривает варианты, а не запускает пакетную задачу, и страница, которая видимо работает, лучше страницы, которая молча думает. Если потребитель — другая система, например задача сравнения цен или корпоративный инструмент бронирования, которому нужен один окончательный ответ, — ждать часто проще и правильнее.

Что бы вы ни выбрали, три правила сохраняют постепенный клиент в здравом уме:

  • Каждая пачка несёт статус завершения поиска в целом, чтобы клиент отличал «пока больше результатов нет» от «больше результатов не будет».
  • Результаты объединяются на сервере по стабильному ключу отеля, а не просто дописываются в конец. Клиент никогда не должен сам догадываться, что две карточки — это одно здание.
  • Сортировка по цене предварительна до завершения поиска, и интерфейс об этом говорит. Пользователи прощают список, который устаканивается; они не прощают ярлык «лучшая цена», который оказался неправдой.

Как моделировать номера и тарифные планы, чтобы всё не развалилось

Именно здесь большинство гостиничных интеграций тихо ломаются, и поломка проявляется спустя месяцы — как обращение в поддержку, а не как баг-репорт.

Соблазнительная модель — плоская: у отеля есть список предложений, у каждого предложения — название номера и цена. Выглядит красиво. Потом один поставщик возвращает «Deluxe King» и «Deluxe Room, 1 King Bed» для явно одного и того же номера, другой возвращает одинаковое название для двух действительно разных номеров (один с видом на город, другой без), а третий отдаёт цену за ночь, когда все остальные — за всё проживание. Плоский список не скажет вам, какой из этих случаев перед вами. Он просто покажет.

Модель, которая выдерживает встречу с реальными поставщиками, имеет как минимум четыре уровня и держит их раздельно:

УровеньЧто хранитОшибка, которой нужно избежать
ОтельВаш собственный стабильный ID, сопоставленный с кодом каждого поставщикаИспользовать ID отеля у поставщика как первичный ключ
НомерРазмещение, конфигурация кроватей, исходный текст поставщика без изменений«Чистить» названия номеров, пока два разных номера не сольются в один
Тарифный планТип питания, возвратность, способ оплаты, поставщик-источникСчитать завтрак или возвратность частью названия номера
ЦенаИтог за проживание, валюта, какие налоги и сборы включены и что оплачивается в отелеПоказывать цену за ночь рядом с ценами за проживание или скрывать сборы, оплачиваемые по прибытии

С расположением границ можно спорить — некоторые команды выделяют размещение в отдельный уровень, и это разумно, как только вы продаёте бронирования на несколько номеров. Нельзя другое: сливать уровни потому, что интерфейс показывает только два из них. Интерфейс может уплощать при отрисовке. Данные — нет.

Одна деталь заслуживает отдельного предложения: храните сырое описание номера от поставщика рядом со всем, что вы нормализуете. Когда гость приедет и получит не тот номер, что указан в ваучере, первый вопрос у всех будет один: что на самом деле прислал поставщик?

Условия отмены — это данные, а не абзац текста

Многие поставщики отдают условия отмены свободным текстом: «Бесплатная отмена за 3 дня до заезда, далее штраф 1 ночь». Очень хочется вывести эту строку и двигаться дальше.

Не делайте этого. Текст нельзя сравнить, отсортировать, отфильтровать или применить. Пользователь хочет отфильтровать возвратные тарифы. Финансовый отдел хочет знать, какие брони завтра станут невозвратными, чтобы агентство успело связаться с клиентом до дедлайна. Пост-бронировочный сценарий должен в момент нажатия кнопки «Отменить» точно сказать клиенту, сколько с него удержат. Ничего из этого не работает на предложении.

Моделируйте каждое условие как упорядоченный список штрафных окон: с этого момента до того момента штраф составляет такую сумму (или такую долю проживания, или столько-то ночей). Границы — это метки времени с часовым поясом, причём поясом отеля, а не вашего сервера и не пользователя: «за 3 дня до заезда» означает разные моменты в зависимости от того, от чьей полуночи считать. Храните исходный текст поставщика рядом со структурированной версией, показывайте структурированную, а расхождение между ними считайте поводом для разбирательства, а не тем, что нужно спрятать.

И перепроверяйте условия при бронировании, а не только при поиске. Между двумя вызовами они меняются чаще, чем кажется.

Во что на самом деле обходится ошибка

Медленный поиск стоит вам конверсий — плохо, но заметно: кто-нибудь пожалуется. Дорогие ошибки — тихие.

Тариф, показанный как возвратный, который поставщик считает невозвратным, — это спор с клиентом, у которого есть скриншот, и штраф обычно платит само агентство. Цена за ночь, показанная как итог за проживание, продаёт номера ниже себестоимости, пока кто-то в бухгалтерии не заметит. Номер, слитый с другим, отправляет семью из четырёх человек в номер на двоих. Сборы, оплачиваемые в отеле и нигде не показанные, превращают отзыв на пять звёзд в чарджбэк. Каждая из этих проблем — решение по модели данных, принятое в первом спринте, чаще всего с пометкой «потом приберёмся».

Кэширование: что можно хранить, а что нельзя

Каждая команда, интегрирующая гостиничный API, рано или поздно спрашивает, можно ли кэшировать результаты, чтобы поиск стал быстрее и дешевле. Ответ — да, для некоторых вещей, и граница между ними важнее любой метрики производительности.

Статический контент — названия отелей, адреса, координаты, фотографии, списки удобств, описания номеров — меняется редко, и именно его стоит активно кэшировать в собственном хранилище. Проверьте условия поставщика о том, как его можно хранить и показывать: некоторые лицензии это ограничивают. Запрашивать его вживую при каждом поиске — медленно и бессмысленно.

Живые тарифы и наличие — другое дело. Закэшированная цена — это догадка о том, сколько возьмёт поставщик, а поставщики ваши догадки не соблюдают. Короткое кэширование результатов поиска может быть допустимо для показа страницы — при условии, что каждый путь бронирования переоценивает предложение у поставщика до списания денег, а интерфейс воспринимает изменившуюся цену как нормальный исход, а не ошибку. Некоторые поставщики к тому же ограничивают соотношение поисков к бронированиям; агрессивный кэш, скрывающий от них ваш реальный трафик, — не та лазейка, на которую стоит полагаться.

Никогда нельзя кэшировать то, что представляет собой обязательство: удерживаемый ценовой токен, номер бронирования, расчёт стоимости отмены. Они принадлежат одному пользователю и одному моменту.

Прежде чем сказать «готово»

Короткая проверка, которую стоит прогнать по своей интеграции до того, как через неё пойдут реальные брони:

  • Поиск возвращает статус завершения, и клиент ведёт себя по-разному до и после него.
  • Отели идентифицируются вашим собственным ID, к которому привязан код каждого поставщика.
  • Номер, тарифный план и цена — отдельные объекты в ваших данных, что бы ни показывал экран.
  • Каждая цена указывает, за ночь она или за проживание, и что оплачивается по прибытии.
  • Условия отмены хранятся как штрафные окна во времени по часовому поясу отеля, исходный текст сохранён.
  • Путь бронирования переоценивает и перечитывает условия, прежде чем что-либо списать.
  • Ничто, что представляет собой обязательство, никогда не отдаётся из кэша.

Если вы взвешиваете, строить ли всё это самостоятельно с каждым поставщиком или начать с платформы, которая уже прошла через эти проблемы, договорная сторона важна не меньше кода — в статье о гостиничном консолидаторе и тарифах bedbank разобрано, что стоит требовать. Наши собственные API авиабилетов и отелей открываются через разговор, а не через ключ в режиме самообслуживания; если вас интересует этот путь, начните разговор на странице туристических API.

Fan-out никуда не денется. Хороший клиент просто перестаёт делать вид, что его нет.

Редакция Tekravel

Отдел travel-технологий

Отдел travel-технологий Tekravel пишет для профессионалов рынка: владельцев агентств, консолидаторов и разработчиков, которые их интегрируют. Каждая статья проверяется на той самой платформе, которую описывает, до публикации.