Действующий протокол обмена Frontdesk24 с внешним каналом продаж (v1.12)
Версия: 1.12 | Статус: Stable | Лицензия: Channel Manager | Продукт: Shelter Cloud (Frontdesk24) | Уровень: Пользовательский | Дата редактирования: 2026-11-03
Протокол описывает обмен данными между Frontdesk24 (Shelter Cloud) и внешним каналом продаж по протоколу JSON over HTTPS. На стороне канала должен быть расположен веб-сервис, который принимает запросы.
Оглавление
- Версии протокола
- Общие сведения
- Направление вызовов
- Подключение канала
- Методы обмена
- Первый обмен данными
- Механизм сопоставления
- Обязательные коды ошибок
- Content API
- Тестирование и приёмка
- Ограничения протокола
- Чек-лист для самостоятельной проверки
Версии протокола
| Версия | Дата | Описание изменений |
|---|---|---|
| 1.0 | 01.01.2020 | Первая версия |
| 1.1 | 04.12.2023 | Добавлено Content API |
| 1.2 | 07.12.2023 | Добавлены политики аннуляции в Content API |
| 1.3 | 15.12.2023 | В метод HotelInfo добавлен признак Active, который сигнализирует о том, что ARI уже можно передавать (для схемы, когда весь контент идёт из Shelter). В метод HotelInfo добавлено поле ContentAPIWebHookUrl. Если в нём указан URL, то при изменении контента (либо по кнопке на странице настройки канала) на него будет отправляться хук о событии ContentChanged с идентификатором отеля, по которому можно в Content API получить контент (информацию об отеле, категории номеров, тарифы). Добавлен метод ContentChanged для уведомления канала об изменении контента (вызывается, если в канале указан ContentAPIWebHookUrl). Content API переведено с push на вебхук+pull. |
| 1.4 | 18.01.2024 | Добавлен вывод параметров предоплаты тарифа в HotelRatePlansDescriptions. Добавлено указание, какие поля являются обязательными. В HotelRatePlansDescriptions добавлена информация о предоплате по тарифу. Добавлен вывод видов размещений в HotelRoomTypesDescriptions. |
| 1.5 | 24.01.2024 | Во все ответы добавлен текст ошибки error, если Success = false. |
| 1.6 | 08.02.2024 | Добавлено описание политик аннулирования. OccupancyID теперь int, переименованы параметры с питанием. |
| 1.7 | 28.02.2024 | В запросе броней /bookings hotelId теперь может быть пустым. В ответ по броням добавлен идентификатор отеля. Переименованы поля в информации по политикам аннулирования: FreeAnnulBeforeDays → FreeAnnulBeforeHours, Fee → Penalty, FeeUnits → PenaltyUnit. |
| 1.8 | 04.04.2024 | Добавлен идентификатор заказа при получении бронирований. |
| 1.9 | 10.04.2024 | Добавлен чек-лист для самостоятельной проверки. |
| 1.10 | 16.01.2026 | Добавлено поле ReestrNumber (номер в реестре классифицируемых средств) в метод HotelDescription. |
| 1.11 | 17.07.2025 | Убраны устаревшие метки «В разработке» с Content API и /ContentChanged. Добавлен раздел «Механизм доставки» (периодичность, retry, поведение при недоступности). Описан порядок первого обмена данными. Уточнены: тип OccupancyId, местное время отеля, поведение Modified (полный объект), ценообразование по размещения. |
| 1.12 | 24.07.2025 | Добавлены разделы: «Подключение канала», «Направление вызовов», «Происхождение идентификаторов», «Связь /HotelInfo и Content API», «Подтверждение доставки брони в PMS», «Изменения и отмены бронирований со стороны отеля», «Справочники», «Действия канала при получении /ContentChanged». Исправлена опечатка Wifi → Wi-Fi. |
Общие сведения
На стороне канала должен быть расположен веб-сервис, который принимает запросы по HTTPS в формате JSON POST.
Общая часть всех запросов:
{
"Username": "test",
"Password": "test",
"HotelId": "Leto"
}
Используется для авторизации во внешней системе.
HotelId — строковый идентификатор отеля на стороне канала. Назначается каналом и сообщается команде Shelter при подключении. Один и тот же HotelId используется во всех запросах к данному отелю.
Логин и пароль выдаются при подключении. Допускается два варианта:
- Отдельный логин/пароль на каждый отель — каждый отель авторизуется своими учётными данными.
- Общий логин/пароль для всех отелей — все отели используют одни и те же учётные данные. В этом случае при запросе бронирований (
/Bookings) можно передатьHotelId = null, и Shelter получит бронирования для всех отелей одним запросом.
Если на стороне канала произошла ошибка, то должен быть возвращен ответ с ошибкой:
{
"Success": false,
"Error": {
"Code": 1,
"Message": "Неверное имя пользователя или пароль"
}
}
Перечень обязательных кодов — см. ниже в разделе Обязательные коды ошибок.
Если запрос выполнен успешно, возвращаются требуемые данные:
{
"Success": true,
// … данные
}
- Формат дат —
yyyy-MM-dd, если указывается время, то+ hh:MM[:ss](нотация .NET). - Даты всегда отражают местное время отеля (часовой пояс PMS отеля). В UTC передаются время создания, изменения, отмены бронирования; период заезда передаётся в местном времени отеля.
- В методах, которые выдают данные на стороне канала, все поля являются обязательными, если в описании метода не указано иное. Если поле является массивом и не содержит элементов (например, список категорий номеров в
HotelInfoдо того как они созданы), то следует возвращать пустой массив.
Направление вызовов
Направление вызовов
Все методы протокола делятся на две группы по направлению вызова:
| Метод | Направление | Где реализуется |
|---|---|---|
/HotelInfo |
Shelter → Канал | На стороне канала |
/Availables |
Shelter → Канал | На стороне канала |
/Restrictions |
Shelter → Канал | На стороне канала |
/Prices |
Shelter → Канал | На стороне канала |
/Bookings |
Shelter → Канал (pull) | На стороне канала |
/ContentChanged |
Shelter → Канал | На стороне канала |
/HotelDescription |
Канал → Shelter | На стороне Shelter (Content API) |
/HotelRoomTypesDescriptions |
Канал → Shelter | На стороне Shelter (Content API) |
/HotelRatePlansDescriptions |
Канал → Shelter | На стороне Shelter (Content API) |
Методы первой группы (Shelter → Канал) канал реализует на своём веб-сервисе. Методы Content API (Канал → Shelter) развёрнуты на стороне Shelter — канал обращается к ним как клиент.
Методы обмена
Запрос информации об отеле
Получает информацию о типах номеров, размещениях и тарифах от поставщика для сопоставления.
URL: /HotelInfo
Входные параметры:
{
"Username": "test",
"Password": "test",
"HotelId": "Leto"
}
Возвращаемые данные:
{
"Success": true,
"Error": null,
"HotelId": "Leto",
"Active": true,
"ContentAPIWebHookUrl": "url1",
"RoomTypes": [
{
"RoomTypeId": "RL1",
"RoomTypeName": "двухместный номер Комфорт с 1 кроватью",
"Occupancies": [
{ "OccupancyId": 1, "OccupancyName": "Одноместное" },
{ "OccupancyId": 2, "OccupancyName": "Двуместное" },
{ "OccupancyId": 3, "OccupancyName": "Двуместное+Доп" }
]
},
{
"RoomTypeId": "RL2",
"RoomTypeName": "двухместный номер эконом класса с 2 отдельными кроватями",
"Occupancies": [
{ "OccupancyId": 1, "OccupancyName": "Одноместное" },
{ "OccupancyId": 2, "OccupancyName": "Двуместное" }
]
}
],
"RatePlans": [
{
"RatePlanId": "P1",
"RatePlanName": "Лето",
"RatePlanDescription": "Питание \"Летоутро\""
},
{
"RatePlanId": "P2",
"RatePlanName": "Без питания",
"RatePlanDescription": null
}
]
}
Питание определяется тарифом. Размещение должно быть указано, даже если такая сущность отсутствует у поставщика — в этом случае необходимо сгенерировать виртуальное размещение вида:
{
"OccupancyId": 1,
"OccupancyName": "Стандартное"
}
Допустимо отдавать только 1 RatePlan и 1 Occupancy (виртуальные) — Shelter не присылает данные с другими RatePlanId или OccupancyId, кроме полученных из /HotelInfo. Если у канала нет понятия тарифа или размещения, достаточно вернуть один виртуальный элемент.
Тип
OccupancyId: в текущей реализации передаётся как строка (string). В будущих версиях протокола планируется стандартизация до int.
Цены на детей: в текущей версии отдельного ценообразования на детей нет. Ценообразование — по размещениям (
OccupancyId): детские места представлены как дополнительные размещения (например, «Двуместное+Доп»). Цена — за номер за ночь по конкретному размещению. Расширенное ценообразование (цены за отдельных гостей, детей с возрастными диапазонами) будет поддержано в будущих версиях протокола.
Передача информации о наличии мест
URL: /Availables
Входные параметры:
{
"Username": "test",
"Password": "test",
"HotelId": "Leto",
"Availables": [
{
"From": "2017-11-08",
"Until": "2017-12-30",
"RoomTypeId": "RL2",
"Quota": 4
},
{
"From": "2017-11-08",
"Until": "2017-12-31",
"RoomTypeId": "RL3",
"Quota": 1
},
{
"From": "2017-11-08",
"Until": "2017-12-30",
"RoomTypeId": "RL1",
"Quota": 3
}
]
}
Возвращаемые данные:
{
"Success": true
}
Поля:
From/Until— период действия квоты.Until— включительная дата (последняя дата периода, по которой есть данные).Quota(int) — количество свободных номеров.Quota = 0означает фактическое отсутствие свободных мест.
Важно:
Quota = 0в/AvailablesиClosed = 1в/Restrictions— это независимые механизмы:
Quota = 0— мест физически нет (проданы или заблокированы).Closed = 1— продажи запрещены, даже если места есть. Shelter передаёт оба параметра независимо друг от друга.
При первом обмене передаётся вся актуальная информация о наличии мест (от текущей даты). В случае успешной первой передачи при последующих передачах будут передаваться только изменения. Чтобы передать снова все актуальные данные, необходимо, чтобы запрос вернул ошибку с кодом 4.
Передача информации об ограничениях
URL: /Restrictions
Входные параметры:
{
"Username": "test",
"Password": "test",
"HotelId": "Leto",
"Restrictions": [
{
"From": "2017-11-05",
"Until": "2017-11-07",
"RoomTypeId": "RL1",
"RatePlanId": "P1",
"RestrictionType": "MinStay",
"RestrictionValue": 10
}
]
}
Возвращаемые данные:
{
"Success": true
}
При первом обмене передаётся вся актуальная информация об ограничениях (от текущей даты). В случае успешной первой передачи при последующих передачах будут передаваться только изменения. Чтобы передать снова все актуальные данные, необходимо, чтобы запрос вернул ошибку с кодом 4. Если какой-то тип ограничения не поддерживается каналом, нужно принимать данные, возвращая Success, без обработки.
Ограничения RestrictionType могут быть:
Closed— запрещено проживание в указанную дату.RestrictionValue(int):1= закрыто (продажи запрещены),0= открыто (продажи разрешены).MinStay— минимальное число ночей.RestrictionValue(int) — количество ночей.MaxStay— максимальное число ночей.RestrictionValue(int) — количество ночей.ClosedToArrival— запрещён заезд в указанную датуClosedToDeparture— запрещён выезд в указанную дату
From / Until — период действия ограничения. Until — включительная дата (последняя дата периода, по которой есть данные).
См. также: разница между
Closed = 1в/RestrictionsиQuota = 0в/Availablesописана в разделе Передача информации о наличии мест.
Снятие ограничения: чтобы снять ранее переданное ограничение, передайте его повторно с
RestrictionValue: null. Shelter передаётnull, когда оператор удалил ограничение в PMS. Канал должен удалить соответствующую запись.Пример — снятие
MinStay(оператор убрал минимальный срок проживания):{ "From": "2017-11-05", "Until": "2017-11-07", "RoomTypeId": "RL1", "RatePlanId": "P1", "RestrictionType": "MinStay", "RestrictionValue": null }Особые случаи:
Closedсо значениемnull— снять закрытие продаж (открыть продажи).MinStay/MaxStayсо значениемnull— снять ограничение на минимальный/максимальный срок.- Если канал не поддерживает снятие ограничений через
null, следует вернутьSuccess: trueи проигнорировать запись.
Передача информации о ценах
URL: /Prices
Входные параметры:
{
"Username": "test",
"Password": "test",
"HotelId": "Leto",
"Prices": [
{
"From": "2017-11-08",
"Until": "2017-12-31",
"RoomTypeId": "RL2",
"RatePlanId": "P1",
"OccupancyId": 2,
"Price": 1750
},
{
"From": "2017-11-08",
"Until": "2018-01-05",
"RoomTypeId": "RL4",
"RatePlanId": "P1",
"OccupancyId": 1,
"Price": 3000
},
{
"From": "2017-11-08",
"Until": "2018-01-05",
"RoomTypeId": "RL4",
"RatePlanId": "P1",
"OccupancyId": 2,
"Price": 3000
},
{
"From": "2017-11-08",
"Until": "2018-01-05",
"RoomTypeId": "RL4",
"RatePlanId": "P1",
"OccupancyId": 3,
"Price": 3000
}
]
}
Возвращаемые данные:
{
"Success": true
}
Поля:
From/Until— период действия цены.Until— включительная дата.Price— цена за номер за ночь (не за гостя). Валюта — валюта отеля, установленная в настройках.Price = 0— допустимо, означает «бесплатно» (проживание без оплаты).
При первом обмене передаётся вся актуальная информация о ценах (от текущей даты). В случае успешной первой передачи при последующих передачах будут передаваться только изменения. Чтобы передать снова все актуальные данные, необходимо, чтобы запрос вернул ошибку с кодом 4.
Получение информации о бронированиях
URL: /Bookings
Входные параметры:
{
"Username": "hotel111",
"Password": "test",
"HotelId": "hotel111", // может быть пустым
"BookingId": null,
"ChangesAfter": "2017-11-01 10:02:33"
}
Возвращаемые данные:
{
"Success": true,
"Error": null,
"ResponseTime": "2017-11-01 10:02:33",
"HotelId": "Leto", // заполняется если в запросе был HotelId
"Bookings": [
{
"HotelId": "hotel111", // заполняется если в запросе не было HotelId
"BookingId": "1112233_1",
"OrderId": "1112233",
"Status": "Created",
"CreatedAt": "2017-11-08 12:58:41",
"ModifiedAt": null,
"CancelledAt": null,
"From": "2017-11-16 00:00",
"Until": "2017-11-24 00:00",
"RoomTypeId": "RL4",
"RatePlanId": "P1",
"Price": 1000,
"Payed": 0,
"Comment": "возможен поздний заезд",
"GuestCount": 2,
"Customer": {
"FirstName": "Иван",
"LastName": "Иванов",
"PatName": "Иванович",
"Birthday": "1980-12-12",
"Email": "aaa@aaa.com",
"Phone": "+7(999)1133-444"
},
"Guests": [
{
"FirstName": "Иван",
"LastName": "Иванов",
"PatName": "Иванович",
"Birthday": "1980-12-12",
"Email": "aaa@aaa.com",
"Phone": "+7(999)1133-444"
},
{
"FirstName": "Петр",
"LastName": "Петров",
"PatName": "Петрович",
"Birthday": null,
"Email": null,
"Phone": "+7(999)1133-444"
}
]
}
]
}
Поведение в зависимости от HotelId в запросе:
Если в запросе указан HotelId:
- возвращаются все изменённые брони для указанного отеля;
- верхний уровень ответа должен содержать
HotelId; - в объекте брони наличие
HotelIdнеобязательно.
Если в запросе не указан HotelId:
- возвращаются все изменённые брони для всех отелей;
- верхний уровень ответа не содержит
HotelId; - в объекте брони наличие
HotelIdобязательно.
Поля бронирования:
BookingId— уникальный идентификатор бронирования (не может повторяться).OrderId— уникальный идентификатор заказа, состоящего из бронирований. Все бронирования с одинаковымOrderIdбудут объединены в 1 заказ. В случае, если бронируется 2 номера — нужно сделать 2Bookingс разнымBookingId, но с одинаковымOrderId. Допускается вBookingIdпередавать номер заказа с суффиксом, идентифицирующим бронь в заказе.
Статус Status может принимать значения:
Created— новое бронирование. События: первичное создание брони на стороне канала.Modified— модифицированное бронирование. События: изменение дат заезда/выезда, изменение категории номера, изменения тарифа, изменение количества гостей, изменение состава гостей, изменение цены, изменение комментария, изменение суммы предоплаты. ПолеModifiedAtдолжно содержать дату и время изменения. ПриModifiedпередаётся полный объект бронирования со всеми полями, а не дельта изменений. Сокращение срока проживания (частичная отмена) передаётся какModifiedс новыми датамиFrom/Until.Cancelled— отменённое бронирование. ПолеCancelledAtдолжно содержать дату и время отмены. После отмены бронирование больше не может перейти в статусCreatedилиModified.Поле
CreatedAtотражает дату и время создания бронирования,ModifiedAt— его последнего изменения,CancelledAt— дату и время отмены. Они должны передаваться в UTC.Необязательное поле
BookingIdпозволяет получить информацию по конкретному бронированию. ПолеChangesAfterв параметрах запроса задаёт дату изменения статуса бронирования, начиная с которой будут выдаваться бронирования из системы поставщика — оно передаётся в UTC. При указанииBookingIdзначение поляChangesAfterигнорируется.Поле
ResponseTimeпоказывает, какое время было на сервере на момент получения данных. В следующий раз бронирования будут запрошены с передачей этого значения вChangesAfter.Дата и время заезда
From,Untilпередаются в местном времени.Поля в
CustomerиGuestsмогут быть равныnull(сам массивGuestsобязателен, может не содержать элементов).Поле
Payedсодержит сумму, которую гость уже оплатил в канале. Оставшуюся часть он оплатит в отеле.
Подтверждение доставки брони в PMS:
В текущей версии протокола нет механизма уведомления канала о том, что бронь успешно сохранена в PMS отеля (или об ошибках сохранения). Канал может косвенно определить успешность:
- По уменьшению квоты в следующем
/Availables.- По отсутствию повторного запроса той же брони (если бронь не сохранилась, Shelter запросит её снова).
Уведомление об изменении контента
Вызывается при первоначальном подключении или при любом изменении контента, требующем выгрузки в канал продаж. В поле HotelId передаётся идентификатор отеля, по которому можно в Content API получить новые данные. В поле Change передаётся что изменилось.
Варианты Change:
Full— первоначальная выгрузкаRatePlans— тарифыRoomTypes— категории номеровHotelInfo— общая информация об отеле
URL: /ContentChanged
Входные параметры:
{
"Username": "hotel111",
"Password": "test",
"HotelId": "hotel111",
"Change": "Full"
}
Возвращаемые данные:
{
"Success": true,
"Error": null
}
Действия канала при получении /ContentChanged:
- Получить уведомление с
HotelIdи типом изменения (Change). - Обратиться к соответствующим методам Content API на стороне Shelter:
Change: Full→/HotelDescription+/HotelRoomTypesDescriptions+/HotelRatePlansDescriptionsChange: HotelInfo→/HotelDescriptionChange: RoomTypes→/HotelRoomTypesDescriptionsChange: RatePlans→/HotelRatePlansDescriptions
- Сохранить/обновить контент на своей стороне.
- Вернуть
{ "Success": true }.
/ContentChanged — это сигнал «данные изменились», а не сами данные. Канал должен сам скачать обновления через Content API.
Подключение канала
Процесс подключения нового канала продаж состоит из следующих шагов:
- Согласование — канал продаж и Shelter договариваются об интеграции. Канал предоставляет: URL веб-сервиса, логин, пароль,
HotelId(идентификатор отеля на стороне канала). - Создание канала — оператор Shelter создаёт запись канала в настройках PMS, указывая полученные логин, пароль и
HotelId; URL веб-сервиса задаётся командой Shelter в регистрации типа канала. - Запрос справочников — Shelter вызывает
/HotelInfoна стороне канала, получает категории номеров (RoomTypes), размещения (Occupancies), тарифы (RatePlans). - Маппинг — оператор сопоставляет внешние ID (от канала) с внутренними ID Shelter. Это ручная операция в интерфейсе Shelter.
- Полная выгрузка ARI — Shelter передаёт все актуальные данные последовательно:
/Availables→/Restrictions→/Prices.
HotelIdназначается каналом продаж и сообщается команде Shelter при подключении. Отельер получает этот ID в экстранете канала и вписывает его при добавлении канала продаж в Shelter. Это ручная настройка, не API-обмен.
/HotelInfoвызывается в двух сценариях:
- При генерации маппинга — когда оператор Shelter нажимает «загрузить справочники» на странице настройки канала. Shelter запрашивает полный ответ и строит дерево маппинга.
- Автоматически при каждой итерации опроса — но только если в настройках канала включён флаг проверки
Active. В этом случае Shelter запрашивает/HotelInfoдля проверки готовности отеля к передаче ARI. Справочники при этом не обновляются — только проверяется признакActive.
Изменение состава категорий и тарифов
Состав категорий номеров и тарифов на стороне канала со временем меняется. Порядок действий в этом случае:
- Новые категории и тарифы попадают в Shelter только при повторной загрузке справочников — оператор снова нажимает «Загрузить справочники» на странице настройки канала, Shelter повторно вызывает
/HotelInfoи перестраивает дерево сопоставления. Автоматического обновления справочников и уведомлений о новых сущностях (писем, задач, индикаторов в интерфейсе) не предусмотрено: о появлении новых категорий или тарифов канал сообщает отелю или команде Shelter самостоятельно — например, через личный кабинет канала или поддержку. - Выполненные сопоставления сохраняются — при повторной загрузке уже выполненные сопоставления сверяются по внешнему ID: сопоставленные сущности остаются сопоставленными, а сущности, исчезнувшие из ответа
/HotelInfo, убираются из дерева. - Новые сущности появляются несопоставленными — они отображаются в списке сопоставления со значением «--» и ожидают ручного сопоставления оператором. Автоматического повторного сопоставления новых сущностей канала в этой схеме нет.
- Несопоставленные сущности в обмене не участвуют — пока категория или тариф не сопоставлены, ARI по ним не передаётся, и это не считается ошибкой обмена: канал просто не получает по ним данные.
Существует альтернативная схема — контент из Shelter (Content API, см. Связь /HotelInfo и Content API). В ней справочник категорий и тарифов определяется на стороне Shelter, а каналу передаются внутренние ID Shelter (внешний ID совпадает с внутренним). Для такой схемы доступно автоматическое сопоставление: дерево сопоставления строится без участия оператора, а новые категории и тарифы, созданные в Shelter, подхватываются автоматически — при очередном цикле фоновой проверки контента, без нажатия кнопки «Загрузить справочники». Схема выбирается на этапе согласования при подключении канала.
Первый обмен данными
При первом подключении канала Shelter выполняет полную выгрузку всех актуальных данных (наличие мест, ограничения, цены) от текущей даты. Инициатор выгрузки — Shelter: после создания канала и завершения маппинга оператором Shelter автоматически начинает выгрузку. Механизм работает следующим образом:
/HotelInfo— Shelter запрашивает у канала категории номеров, размещения и тарифы.- Маппинг — оператор сопоставляет внешние ID (от канала) с внутренними ID Shelter.
- Полная выгрузка ARI — Shelter передаёт все актуальные данные последовательно: сначала
/Availables, затем/Restrictions, затем/Prices. Каждый метод — отдельным запросом с полным объёмом данных за весь горизонт. - Подтверждение — если все запросы полной выгрузки вернули
Success: true, Shelter считает первый обмен успешным и переходит на инкрементальную дельту — при последующих передачах отправляются только изменения. - Сброс — если канал возвращает ошибку с кодом
4(«Необходимо снова передать все актуальные данные»), Shelter повторяет полную выгрузку с самого начала. После успешного завершения снова переходит на дельту.
Рекомендация: при первом обмене канал должен корректно обработать большой объём данных и вернуть
Success: trueдля каждого запроса. Возврат ошибки с кодом 4 на этапе первого обмена приведёт к бесконечному циклу повторных полных выгрузок.
Происхождение идентификаторов
| Где используется | Поля | Чей ID |
|---|---|---|
/HotelInfo (ответ канала) |
RoomTypeId, RatePlanId, OccupancyId |
Внутренние ID канала продаж |
/Availables, /Restrictions, /Prices (запросы Shelter → Канал) |
RoomTypeId, RatePlanId, OccupancyId |
Те же ID канала продаж, полученные из маппинга |
Content API (/HotelRoomTypesDescriptions и др.) |
Id, OccupancyId, BoardingId |
Внутренние ID Shelter |
Shelter преобразует свои внутренние ID во внешние (канала) перед отправкой /Availables, /Restrictions, /Prices. ID Shelter и ID канала не совпадают — маппинг нужен именно поэтому.
Механизм сопоставления
Что такое сопоставление. Сопоставление (маппинг) — таблица соответствий, которая хранится на стороне Shelter: для каждой категории номеров, тарифа и размещения в ней записано, какая сущность канала ему соответствует (пара «внутренний ID Shelter — внешний ID канала»). Канал эту таблицу не видит, не запрашивает и не редактирует.
Зачем оно нужно. Справочники сторон независимы: ID категорий и тарифов в PMS Shelter и в системе канала — разные числа. Чтобы передать наличия, ограничения или цены, Shelter должен знать, в какие ID канала «оборачивать» каждую сущность, — это и есть запись соответствия. Пока сущность не сопоставлена, данные по ней не отправляются вообще, и это не считается ошибкой обмена.
Где выполняется. На странице настройки канала в PMS (вкладки «Категории», «Тарифы», «Размещения»). Список сущностей канала попадает на страницу после «Загрузить справочники» (Shelter вызывает /HotelInfo), затем оператор для каждой сущности Shelter выбирает парную сущность канала; несопоставленные отображаются со значением «--». Порядок действий при изменении состава справочников — в разделе Изменение состава категорий и тарифов.
Как результат доходит до канала. Отдельной передачи результата сопоставления протокол не предусматривает — канал узнаёт его только по самим данным:
| Куда приходят данные | Что получает канал | Чьи ID |
|---|---|---|
/Availables, /Restrictions, /Prices |
ARI по сущностям, которые сопоставлены и включены к передаче в канал | ID канала — Shelter подставляет их из таблицы соответствий |
Content API (/HotelRoomTypesDescriptions, /HotelRatePlansDescriptions и др.) |
описательный контент по сопоставленным и включённым к передаче сущностям | внутренние ID Shelter |
Отсюда практические правила для канала:
- сущность не приходит в ARI-запросах — значит, она не сопоставлена или исключена из передачи; ошибкой это не является;
- сущность приходит в ARI — с тем же ID, который канал отдавал в
/HotelInfo(ID канала); - канал, пользующийся Content API для витрины, получает те же сущности, но с внутренними ID Shelter — связать описания со своими сущностями канал должен сам.
Две схемы ведения справочника.
- Классическая (справочник ведёт канал). Канал отдаёт свои справочники в
/HotelInfo, оператор Shelter сопоставляет их с сущностями PMS вручную; ID сторон не совпадают. - «Контент из Shelter» (справочник ведёт Shelter). Внешний ID равен внутреннему ID Shelter, сопоставление строится автоматически, новые сущности подхватываются сами; ID из Content API и ID в ARI-запросах — одни и те же числа, канал сохраняет их как идентификаторы собственных сущностей, отдельное сопоставление на его стороне не нужно.
Признак устаревшего сопоставления. Если сущность удалена на стороне канала, а соответствие в Shelter ещё не убрано, Shelter продолжит отправлять её ID. Канал должен отвечать ошибкой 5, 6 или 7 (см. Обязательные коды ошибок) — это штатный сигнал, что справочники и сопоставление пора обновить.
Обязательные коды ошибок
| Код | Описание |
|---|---|
| 1 | Неверный логин или пароль |
| 2 | Неверный код отеля |
| 3 | Отель отключен от системы обмена |
| 4 | Необходимо снова передать все актуальные данные |
| 5 | Неверный код типа номера + код |
| 6 | Неверный код размещения + код |
| 7 | Неверный код тарифа + код |
| … | Другие ошибки |
Content API
Развёрнуто на стороне Shelter по ссылке https://pms.frontdesk24.ru/ContentAPI/
Связь /HotelInfo и Content API
Content API — это опциональный механизм для выгрузки описательного контента (названия, описания, фото, удобства, площади, кровати, политики аннуляции) из Shelter в канал. Он не заменяет /HotelInfo и не является источником RoomTypeId/RatePlanId для ARI-обмена.
Сущности канала (RoomTypes, RatePlans, Occupancies) должны существовать в канале до первого вызова /HotelInfo, независимо от Content API.
Типичный сценарий использования Content API: канал хочет отображать на своей витрине фото номеров, удобства, описания отеля — он скачивает их из Content API после получения /ContentChanged.
ID в Content API (Id в /HotelRoomTypesDescriptions) — это внутренние ID Shelter. В классической схеме они не совпадают с RoomTypeId из /HotelInfo (это ID канала): соответствие устанавливает оператор Shelter вручную, а канал, использующий Content API для витрины, связывает полученные описания со своими сущностями на своей стороне. В схеме «контент из Shelter» внешний ID совпадает с внутренним, поэтому ID из Content API — это те же ID, что приходят в ARI-запросах. Как именно результат сопоставления доходит до канала — см. Механизм сопоставления.
Передача информации об отеле
Возвращает общую информацию по отелю с запрошенным идентификатором.
URL: /HotelDescription
Входные параметры:
{
"Username": "hotel111",
"Password": "test",
"HotelId": "hotel111"
}
Возвращаемые данные:
{
"Success": true,
"Name": "Firefly",
"Type": "Отель",
"Phone": "+7(495)123-45-67",
"Address": "Москва, Красная пл. д.1",
"Email": "test@shelter.ru",
"Description": "отличный отель",
"Stars": "3*",
"CheckIn": "14:00",
"CheckOut": "12:00",
"ContactName": "Иванов Иван",
"ContactEmail": "test@shelter.ru",
"ContactPhone": "+79161234567",
"ReestrNumber": "123-456-789",
"Photos": [
{ "Url": "https://url" },
{ "Url": "https://url1" }
],
"Amenities": [
{ "Name": "Wi-Fi" }
]
}
Передача информации о категориях номеров
Возвращает информацию о категориях номеров в указанном отеле.
URL: /HotelRoomTypesDescriptions
Входные параметры:
{
"Username": "hotel111",
"Password": "test",
"HotelId": "hotel111"
}
Возвращаемые данные:
{
"Success": true,
"RoomTypes": [
{
"Id": 2925,
"Name": "Стандарт*",
"Description": "Номер как номер",
"MainPlaces": 2,
"ExtraBeds": 1,
"Meters": 20.2,
"Beds": [
{ "Name": "2-спальная", "Men": 2, "Quantity": 1 }
],
"Occupancies": [
{ "OccupancyId": 1, "OccupancyName": "Одноместное" },
{ "OccupancyId": 2, "OccupancyName": "Двуместное" },
{ "OccupancyId": 3, "OccupancyName": "Двуместное+Доп" }
],
"Amenities": [
{ "Name": "Wi-Fi" }
],
"Photos": [
{ "Url": "https://url" },
{ "Url": "https://url1" }
]
},
{
"Id": 2941,
"Name": "Люкс",
"Description": "Супер номер",
"MainPlaces": 3,
"ExtraBeds": 2,
"Occupancies": [
{ "OccupancyId": 1, "OccupancyName": "Одноместное" },
{ "OccupancyId": 2, "OccupancyName": "Двуместное" },
{ "OccupancyId": 3, "OccupancyName": "Трёхместное" },
{ "OccupancyId": 4, "OccupancyName": "Трёхместное + доп." }
],
"Amenities": [
{ "Name": "Wi-Fi" }
],
"Photos": [
{ "Url": "https://url" },
{ "Url": "https://url1" }
]
}
]
}
Передача информации о тарифах
Возвращает информацию о тарифах в указанном отеле.
Допустимые значения PrepaymentKind и PenaltyUnits:
NIGHTS— количество ночейPERCENTAGE— проценты от стоимости заказаABSOLUTE— абсолютная величинаFIRST_NIGHT_PERCENTAGE— процент от стоимости первых суток (только вPenaltyUnits)
Поля политики аннулирования:
FreeAnnulAlways— признак, что отмена всегда без штрафаFreeAnnulBeforeDays/FreeAnnulBeforeHours— количество дней/часов на аннуляцию без штрафа (если бронирование со штрафом)Penalty— размер штрафаPenaltyUnits/PenaltyUnit— единицы измерения размера штрафа
URL: /HotelRatePlansDescriptions
Входные параметры:
{
"Username": "hotel111",
"Password": "test",
"HotelId": "hotel111"
}
Возвращаемые данные:
{
"Success": true,
"RatePlans": [
{
"Id": 123,
"Name": "BAR",
"Description": "Наши лучшие цены",
"AnnulPolicies": {
"FreeAnnulAlways": false,
"FreeAnnulBeforeDays": 1,
"Penalty": 1,
"PenaltyUnits": "nights"
},
"BoardingId": 321,
"BoardingName": "Bed and breakfast",
"Prepayment": 1.0,
"PrepaymentKind": "NIGHTS"
},
{
"Id": 124,
"Name": "Nonref",
"Description": "Невозвратный тариф",
"AnnulPolicies": {
"FreeAnnulAlways": false,
"FreeAnnulBeforeHours": 100,
"Penalty": 100.0,
"PenaltyUnit": "percents"
},
"BoardingId": 321,
"BoardingName": "Bed and breakfast",
"Prepayment": 100.0,
"PrepaymentKind": "PERCENTAGE"
}
]
}
Справочники
Content API передаёт данные из двух типов справочников:
| Сущность | Тип | Фиксированный? | Передаётся по |
|---|---|---|---|
| Удобства (отель + номер) | Системный (10 значений) | Да | Имени (Name) |
| Размещения | На уровне отеля | Нет | ID + имя |
| Типы кроватей | На уровне отеля | Нет | Имени (Name) |
| Типы питания | На уровне отеля | Нет | ID + имя |
| Типы номеров | На уровне отеля | Нет | ID + имя |
Фиксированный справочник удобств (Amenities) — один и тот же для отеля и для номера. Значение Name должно точно совпадать со справочником (включая регистр и дефис):
Кондиционер, Мини-бар, Балкон, Ванна, Холодильник, Кухня, Вид на море, Терраса, Телевизор, Wi-Fi.
Важно: справочники в Content API — это справочники Shelter. В
/HotelInfoаналогичные сущности (RoomTypeName,OccupancyName) — это данные канала продаж, не связанные со справочниками Shelter. Маппинг между ними выполняется вручную оператором.
Тестирование и приёмка
Перед запуском в продакшен канал продаж должен пройти тестирование на тестовом стенде Shelter.
Тестовый стенд
- URL тестового стенда предоставляется интегрирующей стороне при подключении.
- Тестовый
HotelIdназначается на стороне канала и сообщается команде Shelter. - Логин и пароль для тестирования выдаются командой Shelter.
Тестовые сценарии
- Запрос информации об отеле (
/HotelInfo) — убедиться, что возвращаются корректныеRoomTypes,Occupancies,RatePlans. - Передача наличия мест (
/Availables) — проверить приём квоты и изменениеQuota = 0. - Передача ограничений (
/Restrictions) — проверить приёмClosed,MinStay,MaxStay. - Передача цен (
/Prices) — проверить приём цен за номер за ночь. - Получение бронирований (
/Bookings) — создать тестовое бронирование, проверить получение статусовCreated,Modified,Cancelled. - Первый обмен — убедиться, что полная выгрузка проходит успешно и Shelter переходит на инкрементальную дельту.
- Обработка ошибок — проверить возврат ошибки с кодом 4 и повторную полную выгрузку.
Чек-лист приёмки
-
/HotelInfoвозвращает корректные данные по тестовомуHotelId -
/Availablesпринимает данные и возвращаетSuccess: true -
/Restrictionsпринимает данные и возвращаетSuccess: true -
/Pricesпринимает данные и возвращаетSuccess: true -
/Bookingsвозвращает тестовое бронирование со статусомCreated - Изменение брони на стороне канала корректно отображается в Shelter (статус
Modified) - Отмена брони на стороне канала корректно отображается в Shelter (статус
Cancelled) - При возврате ошибки с кодом 4 Shelter повторяет полную выгрузку
- Общий логин/пароль работает для нескольких отелей (
HotelId = nullв запросе/Bookings)
Проверка интеграции со стороны Shelter
Перед переходом на production Shelter проверяет работу канала на тестовом стенде. Порядок:
- Канал сообщает о готовности — когда все методы протокола реализованы на тестовом окружении, канал сообщает об этом команде Shelter и передаёт тестовые реквизиты: URL тестового веб-сервиса, логин/пароль для вызовов и тестовый
HotelId. - Shelter подключает канал на тестовом стенде — оператор Shelter создаёт канал с тестовыми реквизитами и прогоняет тестовые сценарии: загрузка справочников (
/HotelInfo), полная выгрузка ARI (/Availables,/Restrictions,/Prices), получение тестовых бронирований (/Bookings) и обработка ошибки с кодом 4. Отдельные шаги запускаются вручную кнопками «Загрузить справочники», «Выгрузить всё» и «Загрузить бронирования» на странице настройки канала, дальше обмен идёт штатным автоматическим опросом. - Shelter анализирует обмен по своим журналам — все запросы и ответы фиксируются журналом службы обмена на стороне Shelter. Доступ в систему канала при этом не требуется: Shelter видит, что и когда было отправлено и что ответил канал.
- Канал проверяет свою сторону по собственным логам — каналу рекомендуется сверять входящие запросы от Shelter (порядок вызовов, состав данных, ответы) в своих журналах. Расхождения стороны разбирают совместно, по журналам каждой из сторон.
Итог приёмки — прохождение чек-листа из раздела выше. Процесс проверки одинаков для тестовой и рабочей среды: отличается только окружение (тестовый стенд / production) и реквизиты подключения.
Переход на production
Production-реквизиты не выдаются автоматически по факту тестирования — переход согласовывается. Последовательность действий:
- Завершение приёмки — тестовые сценарии и чек-лист приёмки пройдены на тестовом стенде, обе стороны подтверждают готовность к работе в production.
- Подготовка production-окружения на стороне канала — канал разворачивает рабочий веб-сервис и передаёт команде Shelter: production URL веб-сервиса, production логин/пароль (общий для всех отелей или отдельный на каждый отель — по схеме, согласованной при подключении) и
HotelIdкаждого подключаемого отеля (назначается на стороне канала). - Регистрация канала в production — тип канала регистрируется в рабочей среде Shelter; для новых каналов это выполняет команда Shelter, действий от канала не требуется.
- Подключение отелей — для каждого отеля оператор (команда Shelter, дилер или отельер) добавляет канал в менеджере каналов и заполняет на вкладке «Настройки авторизации» логин, пароль и
HotelIdотеля; URL веб-сервиса и адреса методов уже заданы в регистрации типа канала (шаг 3). - Справочники и сопоставление — «Загрузить справочники», затем сопоставление категорий и тарифов (ручное или автоматическое — в зависимости от схемы, см. Изменение состава категорий и тарифов).
- Включение обмена — канал включается, Shelter выполняет полную выгрузку ARI, далее обмен идёт штатно (опрос каждые 60 секунд, передаются только изменения). Входящие бронирования принимаются и отображаются в PMS отеля.
Протокол и логика обмена в production полностью совпадают с тестовым стендом: различаются только реквизиты (URL, логин/пароль, HotelId) и то, что обмен идёт с рабочими отелями и реальными бронями.
Ограничения протокола
Изменения и отмены бронирований со стороны отеля (PMS → Канал) — механизм экспорта аннуляций (
ExportAnnuls) не реализован. Технически отельер может отменить бронь в PMS, но канал продаж в таком случае всё равно выставит отелю счёт на комиссию. Чтобы избежать комиссии, отель обращается в канал продаж (через личный кабинет канала или поддержку), канал отменяет бронь на своей стороне — после этого аннуляция выгружается в менеджер каналов (Shelter) через стандартный поток/Bookings. Автоматический экспорт аннуляций из PMS в канал не реализован намеренно, чтобы не создавать лазейку для уклонения от комиссии. Изменения бронирований со стороны отеля (продление, сокращение срока проживания) также не передаются в канал напрямую. Однако вызванное этими изменениями изменение наличия мест передаётся обычным образом через/Availables: например, если гость продлил проживание, канал не получит уведомление об изменении брони, но увидит уменьшение квоты на новые даты.Таймаут ожидания ответа — 120 секунд. Если канал не ответил за это время, Shelter считает запрос неуспешным и повторяет его на следующей итерации опроса (через 60 секунд).
Периодичность опроса — Shelter опрашивает канал каждые 60 секунд. При первом обмене передаётся полный дамп всех данных; при последующих — только изменения (дельта).
Поведение при недоступности канала — при ошибке (timeout, HTTP 5xx, сетевая ошибка) Shelter повторяет запрос через 60 секунд. Количество повторов не ограничено. Данные не теряются: при ошибке экспорта сбрасывается дата последней успешной передачи, и при следующей итерации передаётся полный объём данных с момента последнего успеха.
Rate-limiter — отсутствует. Shelter отправляет запросы последовательно, по одному каналу за раз.
Лимит на размер запроса и ответа — отсутствует. При первичной выгрузке весь объём данных (наличие мест, ограничения, цены за весь горизонт) передаётся одним запросом на каждый метод. Shelter обрабатывает ответы любого размера.
Пагинация — отсутствует. Все данные передаются одним ответом. Для бронирований используется инкрементальная выборка через
ChangesAfter(см. Получение информации о бронированиях).Кодировка — UTF-8 во всех запросах и ответах.
Сжатие — поддерживается gzip (по заголовку
Accept-Encoding).
Чек-лист для самостоятельной проверки
Перед запуском в продакшен убедитесь, что реализованы все методы протокола:
- Авторизация по
Username/Password/HotelId - Поддержка общего логина для всех отелей (
HotelId = nullв/Bookings) -
/HotelInfo— возвращаетRoomTypes,Occupancies,RatePlans -
/Availables— принимает наличие мест, корректно обрабатываетQuota = 0 -
/Restrictions— принимаетClosed,MinStay,MaxStay,ClosedToArrival,ClosedToDeparture -
/Prices— принимает цены за номер за ночь -
/Bookings— возвращает брони со статусамиCreated,Modified,Cancelled; поддерживаетChangesAfter -
/ContentChanged— (если используется Content API) принимает уведомление - Обработка ошибки с кодом 4 — повторная полная выгрузка
- Все ответы содержат
SuccessиErrorсCodeиMessage - Таймаут ответа не превышает 120 секунд