Разделы и статьи

API для виджета бронирования на сайте для Shelter CLOUD

Назначение

Данное API предназначено для интеграции виджета онлайн-бронирования Shelter CLOUD версии v2 на сторонние сайты и платформы.

Требования

Для работы с API необходим:

  • Аккаунт в Shelter CLOUD;
  • Токен доступа.

Важно
Все методы API требуют указания токена авторизации в заголовках запроса.

Как получить токен доступа

  1. Кликните по имени пользователя в правом верхнем углу экрана Shelter Cloud;
  2. Перейдите на вкладку Онлайн v2;
  3. Нажмите кнопку Добавить виджет;
  4. Скопируйте токен в блоке Код вставки на главную страницу.

Типовой процесс бронирования

1. Поиск вариантов

  • Пользователь указывает даты заезда/выезда, количество номеров;
  • Указывает состав гостей (взрослые/дети/возраст детей);
  • Вызывается метод getVariants.

2. Выбор подходящего варианта

  • Пользователь выбирает подходящий вариант размещения;
  • Запрашиваются доступные способы оплаты через getPaymentOptions.

3. Создание бронирования

  • Пользователь заполняет данные гостей;
  • Выбирает способ оплаты;
  • Вызывается метод putOrder для создания бронирования;
  • В ответе получает информацию о созданном бронировании, включая ссылку на оплату (если требуется).

4. Управление бронированием

  • Детали заказа можно получить через getOrder;
  • Отмена бронирования через annulOrder.

Методы API

Получение параметров отеля

Метод: POST /api/online/getHotelParams

Назначение:Возвращает настройки виджета и справочники отеля.

URL: https://pms.frontdesk24.ru/api/online/getHotelParams

Результат: Возвращается массив с вариантами размещения в строго определённом порядке.

Пример в архиве:

Поиск вариантов размещения

Метод: POST /api/online/getVariants

Назначение: Поиск доступных номеров на указанные даты для заданного состава гостей.

URL: https://pms.frontdesk24.ru/api/online/getVariants

Особенности работы:

  • Система автоматически подбирает номера, подходящие по количеству мест. Номер считается подходящим, если число основных и доп.мест в нём больше либо равно запрошенному;
  • Сначала занимаются основные места, затем дополнительные
    Пример: Номер с 2 основными и 1 дополнительным местом:
    Запрос: 1 взрослый + 1 ребенок + 1 младенец
  • Результат: взрослый и ребенок на основных местах, младенец на дополнительном

Важно
Для каждого варианта из getVariants используется свой уникальный signatureId.

Пример в архиве:

Получение способов оплаты

Метод: POST /api/online/getPaymentOptions

Назначение: Возвращает список доступных способов оплаты.

URL: https://pms.frontdesk24.ru/api/online/getPaymentOptions

Пример в архиве:

Создание бронирования

Метод: POST /api/online/putOrder

Назначение: Создание новой брони

URL: https://pms.frontdesk24.ru/api/online/putOrder

Пример в архиве:

Отмена бронирования

Метод: POST /OnlineWidget3/online/v3/annulOrder

Назначение: Аннулирование существующей брони.

URL: https://pms.frontdesk24.ru/OnlineWidget3/online/v3/annulOrder

Обязательный параметр: orderToken (получается в ответе putOrder)

Пример в архиве:

Получение деталей заказа

Метод: POST /api/online/getOrder

Назначение: Получение информации о существующем бронировании.

Возможные проблемы и их решение

Проблема 1: Метод возвращает пустой массив данных

При отправке запроса, например, getVariants, не возвращаются данные. Например:



Решение:

1. Проверьте доступность модуля:

  • Убедитесь, что модуль онлайн-бронирования активен в вашем тарифе

2.  Если сайт отсутствует, либо модуль онлайн бронирования не установлен, то проведите проверку через автосайт:

  • Перейдите в Shelter CLOUD → кликните на имя пользователя → Настройки → Онлайн для сайта v2.0 → Автосайт;
  • Заполните поле Синоним отеля для ссылки;
  • Перейдите по сгенерированной ссылке;
  • Проверьте наличие номеров на нужные даты. Если в указанный период доступные номера отсутствуют, запрос будет возращать пустой массив данных.


3. Проверьте настройки:

  • Модуль бронирования доступен в тарифе Shelter Cloud;
  • Категории и тарифы настроены для выгрузки онлайн;
  • Отсутствуют ограничения для тарифов/категорий;
  • Установлены цены на запрашиваемый период.


Проблема 2: Некорректные данные в запросе

При отправке запроса, например, getVariants, метод возвращается некорректные данные. Например:



Решение (на примере Chrome):

  1. Откройте автосайт с модулем бронирования;
  2. Откройте DevTools (F12) → вкладка Сеть;
  3. Установите параметр Fetch/XDR;
  4. Найдите запрос getVariants;
  5. Во вкладках будут доступны следующие данные:
  • Заголовки: URL и метод запроса;
  • Полезная нагрузка → Посмотреть ресурс: тело запроса;
  • Ответ: структура ответа.     


Используйте эти данные для настройки API-клиента:

  1. Перейдите в инструмент тестирования API (Postman, Bruno и т.п.);
  2. Укажите URL и метод, указанные на вкладке Заголовки → Общие;
  3. Скопируйте тело запроса из вкладки Полезная нагрузка →Посмотреть ресурс;
  4. Отправьте запрос и дождитесь ответа;
  5. Сгенерируйте код.

Проблема 3: Ошибка сигнатуры в putOrder

При использовании метода putOrder, возникает ошибка вида:{

  "error": {

    "code": "0400",

    "message": "Не совпадают рассчитанная и входящая сигнатура",

    "description": null

  }

}


Причина: Неверный или отсутствующий signatureId


Решение:

  1. Получите signatureId из ответа метода getVariants;
  2. Каждый вариант размещения имеет уникальный signatureId;
  3. Передайте правильный signatureId в запросе putOrder.

Дополнительные материалы

Коллекция Postman во вложении содержит предварительно настроенные запросы для всех методов: