Search API — поиск доступных размещений

Ценообразование в TravelLine

Отель устанавливает цену на каждый тариф, категорию номера, тип места и дату. Например:

В поиске предоставляются данные на год вперед от текущей даты. Максимально количество дней между параметрами arrivalDate и departureDate равно 100. Максимальное количество дней между датой arrivalDate и текущей датой — 365.

Брутто и нетто цены

Передаются те цены, которые отельер настроит в своём личном кабинете. Мы передаем цены, не зная брутто это или нетто. Наценки и скидки создаются на стороне канала.

Фильтры в агрегационном поиске

В методе search/api/properties/room-stays/search можно указать фильтры:

По наличию питания — поле mealPreference.mealType. В запросе можно передать следующие значения:

• All — отображение минимального по стоимости варианта проживания по каждому объекту размещения.

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

• MealPriority — отображение минимального по стоимости варианта проживания с включенным в стоимость тарифа питанием по каждому объекту размещения. Если в объекте размещения отсутствуют такие варианты проживания, этот объект размещения также выводится в ответе.

По типу питания — поле mealPreference.mealsIncluded. В запросе можно передать значения возможных вариантов питания, которые доступны в ответе метода content/v1/meal-plans, а также в ответе методов content/v1/properties — отображение всей информации о доступных объектах размещения и content/v1/properties{propertyId} — отображение информации по конкретному объекту размещения.

Результат поиска показывает минимальные по стоимости варианты проживания с включенным в стоимость тарифа конкретными типом питания по каждому объекту размещения. Например, если в запросе указать только значения «BreakFast», в ответе можно получить минимальные по стоимости варианты проживания с включенным в стоимость тарифа питанием только типа «BreakFast». При этом в ответе будут отсутствовать варианты «AllInlusive» или «HalfBoard».

Фильтр по типу питания можно использовать только при наличии питания типа «MealOnly» или «MealPriority».

По минимальной и максимальной стоимости проживания — поля pricePreference.minPrice и pricePreference.maxPrice.

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

Работа с корпоративными тарифами

В методе search/api/properties/room-stays/search можно указать corporateCode (код идентификации корпоративных клиентов) для дополнительного отображения корпоративных тарифов. Если стоимость проживания по корпоративным тарифам будет ниже, чем по другим тарифам, то в ответе на агрегационном поиске будет получено проживание по корпоративному тарифу.

В методе «api/search/v1/properties/ {propertyId}/room-stays» укажите corporateCode. Тогда в ответе помимо проживаний по общедоступным тарифам будут отображены проживания по корпоративным и закрытым тарифам.

Поиск раннего заезда, позднего выезда и услуг за дополнительную плату по конкретному проживанию

Вам доступен дополнительный функционал для получения раннего заезда и позднего выезда (РЗПВ) и услуг за дополнительную плату. Подробности читайте в статьях «Как каналу продавать ранний заезд и поздний выезд через Partner API» и «Как каналу продаж продавать услуги через Partner API».

Работа с апартаментами

В агрегационном поиске отображаются варианты проживания с минимальной ценой в рамках апартаментов, которые находятся по разным адресам. Чтобы все апартаменты отображались в агрегационном поиске, необходимо:

• в настройках указать тип объекта размещения — «Апартаменты»;

• выбрать режим для квартир и апартаментов, который подключается через службу поддержки TravelLine;

• в категориях номеров каждого средства размещения указать свой адрес: город, улица, литера, строение, корпус.

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

Передается ли НДС

В теле ответа на создание и чтение брони содержатся поля:

• НДС проживания — booking.roomstays[].ratePlan VAT;

• НДС услуг — booking.roomstays[].services[] VAT.

НДС могут быть добавлены к проживанию отдельно. В состав проживания входит стоимость проживания по тарифу, дополнительные услуги, включенные в стоимость тарифа, и РЗПВ. Также НДС может быть добавлен к услугам за дополнительную плату.

С 1 января 2025 средства размещения, которые работают на упрощенной системе налогообложения (УСН) по закону № 176-ФЗ от 12.07.2024 признаются налогоплательщиками НДС. Более подробно про УСН вы можете почитать в статье «Как настроить НДС для упрощенной системы налогообложения (УСН)».

Налоги по УСН также передаются в массиве VAT.

Налоги и сборы (кроме НДС)

Поле taxAmount содержит сумму налогов и сборов, которую оплачивает гость при заезде. Согласно Федеральному закону № 214-ФЗ от 29 июля 2017 года и Закону Краснодарского края № 3690-КЗ от 27.11.2017 эта сумма не содержит НДС. Налоги и сборы могут быть добавлены к тарифу, к РЗПВ или к дополнительным услугам.

Тип питания в размещении RoomStay

Для одного RoomStay доступно только одно питание. В системе TravelLine отель может добавить в тариф только одну услугу с типом питания. Поэтому mealPlanCode является строковым типом данных.

Что делать, если запрос в «api/search/v1/properties/ {propertyId}/room-stays» не содержит ошибок и на него не приходит ответ

Обратите внимание. Поля «arrivalDate» и «departureDate» должны содержать даты в будущем.

Расселение гостей в номере

В результатах поиска возвращаются поля:

• roomStays.fullPlacementsName;

• roomStays.roomType.placements.

В placements перечислены не конкретные места, а типы условий для размещения гостей. В ответе видно, что два взрослых размещаются на основных местах, ребенок в возрасте 2 года на основном месте, а ребенок в возрасте 5 лет на дополнительном месте.

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

Расшифровка дополнительного места

Расшифровки дополнительных мест нет. Поэтому нельзя узнать — диван это или, например, детская кроватка.

Блоки доступности номеров

В результатах поиска вариантов размещений доступность зависит от выбранного отельером блока доступности в каждом тарифном плане. Подробности читайте в статье «Как работать с разными блоками доступности номеров». Тарифы передаются в каналы продаж только по одному блоку доступности.

Правила отмены бронирований

В каналы продаж передаются правила отмены бронирований, настроенные в личном кабинете TravelLine. Сумма штрафа может быть разной в зависимости от даты отмены, если у средства размещения настроены различные условия отмены.

В результатах поиска возвращаются следующие поля:

• roomStays.cancellationPolicy.freeCancellationPossible;

• roomStays.cancellationPolicy.freeCancellationDeadline;

• roomStays.cancellationPolicy.penaltyAmount.

В зависимости от полученных значений в полях правила отмены интерпретируются так.

Бронирование является невозвратным, при этом штраф за отмену на текущую дату составляет 4000 (в последующие даты размер штрафа может быть другим), при получении следующих значений:

• freeCancellationPossible = false;

• freeCancellationDeadline = null;

• penaltyAmount = 4000.

Отмена бронирования бесплатна до 30.09.2025 12:00. После этого времени штраф за отмену составит 4000 (в последующие даты размер штрафа может быть другим), при получении следующих значений:

• freeCancellationPossible = true;

• freeCancellationDeadline = 2025-09-30T12:00;

• penaltyAmount = 4000.

Штраф за отмену не взимается при отмене в любую дату, при получении следующих значений:

• freeCancellationPossible = true;

• freeCancellationDeadline = null;

• penaltyAmount = null.

Статистика времени ответа на запросы

Поиск вариантов проживаний по конкретному средству размещения:

• 90 pt — 866 ms;

• 95 pt — 1050 ms.

Поиск вариантов проживания с минимальной ценой по всем доступным средствам размещения:

• 90 pt — 1111 ms;

• 95 pt — 1728 ms.