Shelter Cloud API (ShelterCloudAPI)

Версия: v1 | Статус: Stable | Лицензия: ShelterCloudAPI | Продукт: Shelter Cloud | Уровень: Пользовательский

Postman-коллекция для тестирования

Оглавление


Описание модуля

ShelterCloudAPI — REST API для Shelter Cloud, предоставляющий доступ к данным PMS (Property Management System) отеля. В отличие от API виджета бронирования (v1/v2/v3), которое предназначено для создания модуля онлайн-бронирования на сайте, ShelterCloudAPI решает задачи серверной интеграции:

  • Чтение и фильтрация бронирований
  • Заселение и выселение (Check-in / Check-out)
  • Управление гостями (добавление, редактирование, удаление)
  • Работа с номерным фондом (номера, категории номеров)
  • Управление тарифами
  • Финансовые операции (начисления, платежи)
  • Справочники и дополнительные поля
  • Контрагенты
  • Дополнительные услуги и группы услуг
  • Вебхуки для получения уведомлений об изменениях в бронированиях
  • Информация об отеле и пользователях

API используется для интеграции с CRM-системами (amoCRM и др.), системами гостиничного ТВ, мобильными приложениями, каналами продаж и другими внешними системами, которым необходим доступ к данным Shelter Cloud.


Ограничения

ShelterCloudAPI не поддерживает следующие операции:

Операция Как выполнить
Создание бронирования Через API виджета бронирования (методы putOrder в v2/v3)
Изменение параметров бронирования (даты, категория, тариф) Не поддерживается. Для изменения необходимо отменить бронирование через API виджета v3 (метод annulOrder) и создать новое
Отмена бронирования Через API виджета бронирования v3 (метод annulOrder) или v1 (метод AnnulateOrder)

ShelterCloudAPI предоставляет доступ к уже существующим бронированиям: чтение, поиск, работа с гостями, заселение/выселение, платежи и начисления.


Общие сведения

Параметр Значение
Продукт Shelter Cloud
Лицензия ShelterCloudAPI
Протокол HTTPS REST API
Формат данных JSON
Основной URL https://cloud.shelter.ru/sheltercloudapi/
Резервный URL https://pms.frontdesk24.ru/sheltercloudapi/
Swagger https://cloud.shelter.ru/sheltercloudapi/swagger/index.html
Количество эндпоинтов 72 (44 уникальных пути)

ShelterCloudAPI работает только с облачной версией Shelter Cloud. Для локальной версии Shelter PRO используется отдельное XML API.


Схема работы

                                      ShelterCloudAPI
+------------------+                +----------------------------+
|                  |  HTTPS + JSON  |                            |
|  Внешняя система | -------------> |  Аутентификация (Bearer)   |
|  (CRM, ТВ,      | <------------- |  Rate Limiting             |
|   приложение)    |                |  Контроллеры (19 шт.)      |
|                  |                |                            |
+------------------+                |         |                  |
                                    |         v                  |
+------------------+  WebHook POST  |  +------------------+     |
|  Подписчик       | <------------ |  |  MS SQL Server   |     |
|  вебхуков        |                |  |  (БД Shelter)    |     |
+------------------+                |  +------------------+     |
                                    |                            |
                                    |  WebHooksMonitor           |
                                    |  (фоновый сервис)          |
                                    +----------------------------+

Фоновый сервис WebHooksMonitor работает параллельно с API. Периодически проверяет наличие обновлённых бронирований и отправляет уведомления на URL-ы зарегистрированных вебхуков.


Настройки в Shelter

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

  1. Лицензия на модуль ShelterCloudAPI — без неё API недоступно
  2. Токен авторизации типа ShelterCloudApiToken

Получение токена

Токен создаётся на экране управления токенами, доступном по прямой ссылке:

https://cloud.shelter.ru/shelter-cloud/#/tokens

Данный экран доступен только техподдержке Shelter. Для получения токена обратитесь в техподдержку.

При создании токена:

  • Тип токена: ShelterCloudApiToken
  • Токен привязан к конкретному отелю
  • Все запросы через этот токен автоматически ограничены данными только этого отеля

Аутентификация

Все методы API (кроме Debug) требуют аутентификации по схеме Bearer Token.

Формат заголовка

Authorization: Bearer ВАШ_ТОКЕН

Процесс аутентификации

  1. Из заголовка Authorization извлекается токен
  2. Проверяется наличие токена с типом ShelterCloudApiToken в базе данных
  3. Проверяется, что токен активен
  4. Из токена определяется отель — все дальнейшие операции ограничены данными этого отеля

Ошибки аутентификации

Ситуация HTTP-код
Отсутствует заголовок Authorization 401
Неверная схема (не Bearer) 401
Пустой или невалидный токен 401
Токен не найден в БД 401
Токен деактивирован 401

Ограничение частоты запросов

API использует ограничение частоты запросов (Rate Limiting) для каждого токена.

Лимит Значение
В минуту 60 запросов
В час 3600 запросов

При превышении лимита API возвращает:

HTTP 429 Too Many Requests

Счётчики ведутся отдельно для каждого токена.


Логирование (Graylog)

ShelterCloudAPI отправляет логи в Graylog по протоколу GELF.

Фильтры для поиска в Graylog

channelName:"ShelterCloudApi"
appType:"Service"

Дополнительные поля в каждом сообщении:

Поле Описание
IP IP-адрес клиента
Token Токен авторизации
HotelId ID отеля

Формат сообщений

Каждый запрос логируется в формате:

Request: POST /Reservations/ByFilter?param=value {"number":0,"createdStart":"2024-01-01"}
Response: 125ms 200: [{"id":123,"number":456,...}]

Уровни логирования

Уровень Когда используется
Info Все обычные запросы и ответы
Warn Превышение лимита запросов (Rate Limit)
Error Ошибки обработки запросов, исключения

Примеры сообщений в Graylog

Успешный запрос:

Request: GET /Rooms
Response: 45ms 200: [{"id":1,"number":"101","roomTypeId":2,...}]

Превышение лимита:

Request: GET /Rooms...Rate limit exceeded. Try again later

Коды ответов

HTTP-код Описание
200 Успех (тело ответа содержит результат)
204 Успех без тела ответа (DELETE-операции)
400 Ошибка в запросе (невалидные данные)
401 Не авторизован (отсутствует или невалидный токен)
429 Превышен лимит запросов
500 Внутренняя ошибка сервера

Формат ошибки

{
  "Code": "ERR_AUTH",
  "Desc": "Token not found"
}

Известные коды ошибок:

Код Описание
ERR_AUTH Ошибка авторизации
XERR_RESOURCE_NOT_FOUND Ресурс не найден

Группы методов

Reservations — Бронирования

Метод Путь Описание
POST /Reservations/List Список бронирований по массиву ID (максимум 50)
POST /Reservations/ByFilter Поиск бронирований по фильтру с пагинацией
GET /Reservations/{id}/Guests Список гостей бронирования
GET /Reservations/Guests/{clientInReservationId} Чтение одного гостя
POST /Reservations/AddOrUpdateGuest Добавить или изменить гостя
POST /Reservations/DeleteGuest Удалить гостя из бронирования
POST /Reservations/{id}/Checkin Заселение (Check-in)
POST /Reservations/{id}/Checkout Выселение (Check-out)
POST /Reservations/{id}/UpdateField Обновить дополнительное поле бронирования
GET /Reservations/{id}/Fields Список дополнительных полей бронирования
GET /Reservations/{id}/ClientFields Дополнительные поля гостей бронирования
POST /Reservations/{id}/UpdateClientField Обновить дополнительное поле гостя
POST /Reservations/{id}/DoAction Выполнить действие над бронированием
POST /Reservations/OrderReservations Бронирования заказа (по OrderId или ReservationId)

POST /Reservations/List — запрос

Тело запроса: массив int (ID бронирований). Максимум 50 ID за один запрос. Массив не может быть пустым.

[123, 456, 789]

POST /Reservations/ByFilter — запрос (ReservationFilterDto)

Все поля фильтра необязательные. Если не указано ни одного фильтра — возвращаются все бронирования (с учётом пагинации).

Поле Тип Обяз. Описание
number int — Номер бронирования
createdStart datetime — Дата создания — начало периода
createdEnd datetime — Дата создания — конец периода
from datetime — Дата заезда — начало
until datetime — Дата заезда — конец
livedFrom datetime — Дата начала проживания
livedTo datetime — Дата окончания проживания
isAnnul bool — Признак аннулированной брони
clientName string — ФИО гостя (частичное совпадение), например "Иванов"
clientGuid string — GUID клиента
orderId int — Идентификатор заказа
pagination object — Пагинация (см. ниже)

Поля пагинации (pagination):

Поле Тип Обяз. Описание
from int — Смещение, начиная с 0
count int — Количество элементов (максимум 50)

Ответ — ReservationDto (для List и ByFilter)

Метод ByFilter возвращает обёртку { count, items }, где items — массив ReservationDto. Метод List возвращает массив ReservationDto напрямую.

Поле Тип Описание
id int ID бронирования
number int Номер бронирования
clientGuid string GUID клиента
hotelId int ID отеля
hotelName string Название отеля
from datetime Дата заезда
until datetime Дата выезда
date datetime Дата создания брони
roomTypeId int ID категории номера
roomId int ID номера
roomNumber string Номер комнаты
roomTypeName string Название категории номера
checkInStatus string Статус заселения: Wait, CheckedIn, CheckedOut
isAnnul bool Аннулировано
tariffId int ID тарифа
statusID int ID статуса бронирования
agencyID int ID агентства
contractID int ID договора
contractName string Номер договора
contactName string Заказчик (имя)
contactPhone string Телефон заказчика
contactEmail string Email заказчика
commentHotel string Комментарий отеля
commentGuest string Комментарий гостя
responsibleId int ID ответственного сотрудника
ourFirmId int ID юридического лица
reservationPrice float Стоимость
discount float Размер скидки
guests array Массив гостей (краткая информация)

Поля гостя в бронировании (GuestDto):

Поле Тип Описание
id int ID гостя
lastName string Фамилия
firstName string Имя
middleName string Отчество
country string Страна
birthDate datetime Дата рождения
email string Email
phone string Телефон
accommodation string Тип размещения

POST /Reservations/AddOrUpdateGuest — запрос (AddGuestDto)

Если передан clientInReservationId > 0 — редактирование существующего гостя, иначе — добавление нового.

Поле Тип Обяз. Описание
reservationId int да ID бронирования
clientId int — ID клиента (0 = новый клиент)
clientInReservationId int — ID клиента в бронировании (> 0 = редактирование)
surname string — Фамилия
firstName string — Имя
patronomic string — Отчество
birthDate datetime — Дата рождения
sex int — Пол: 0 = женщина, 1 = мужчина
phone string — Телефон
email string — Email
isRFSitizenship bool — Российское гражданство
foreignCitizenship string — Страна иностранного гражданства
surnameRus string — Фамилия на русском (для иностранцев)
firstNameRus string — Имя на русском (для иностранцев)
patronomicRus string — Отчество на русском (для иностранцев)
tripGoalId int — ID цели поездки
pansionId int — ID типа питания
accomodationId int — ID типа размещения
clientDiscount int — Скидка клиента
loyaltyCard string — Карта лояльности
carNumber string — Номер автомобиля
passport object — Данные документа (см. ниже)
birthPlace object — Место рождения (см. ниже)
rfLocation object — Место жительства (см. ниже)
foreignMigrationCard object — Миграционная карта (только иностранцы)
foreignResolutionType object — Документ права на пребывание (только иностранцы)
resortFee object — Курортный сбор

Поля паспорта (passport):

Поле Тип Описание
docType string Вид документа
series string Серия
number string Номер
getBy string Кем выдан
getByCode string Код подразделения
docDate datetime Дата выдачи
foreignDocUntil datetime Срок действия (для иностранных документов)

Поля места рождения (birthPlace):

Поле Тип Описание
country string Страна
region string Регион
area string Район
city string Город
locality string Населённый пункт

Поля места жительства (rfLocation):

Поле Тип Описание
country string Страна
region string Регион
area string Район
city string Город
locality string Населённый пункт
street string Улица
house string Дом
housing string Корпус
building string Строение
apartmentNumber string Квартира

Ответ — ViewGuestDto (для Guests, AddOrUpdateGuest)

Возвращается полная информация о госте, включая все поля из запроса AddGuestDto плюс вложенные объекты (passport, birthPlace, rfLocation и т.д.).

POST /Reservations/DeleteGuest — запрос (DeleteGuestDto)

Поле Тип Обяз. Описание
clientId int да ID гостя
reservationId int да ID бронирования

Ответ: HTTP 204 (без тела).

POST /Reservations/{id}/Checkin — запрос (CheckInRequestDto)

Поле Тип Обяз. Описание
roomId int — ID номера для заселения. Если не указан — используется номер, привязанный к бронированию

Query-параметр:

Параметр Тип По умолч. Описание
allowCheckedIn bool false Разрешить повторное заселение (если бронирование уже заселено)

Ответ: ReservationDto.

POST /Reservations/{id}/Checkout

Query-параметр:

Параметр Тип По умолч. Описание
allowCheckedOut bool false Разрешить повторное выселение

Ответ: ReservationDto.

POST /Reservations/{id}/UpdateField

Обновление дополнительного поля бронирования.

Query-параметры:

Параметр Тип Обяз. Описание
name string да Имя дополнительного поля
value string — Новое значение

Ответ: HTTP 200 (без тела).

GET /Reservations/{id}/Fields — ответ (ReservationFieldDto)

Поле Тип Описание
reservationFieldId int ID поля в бронировании
fieldId int ID дополнительного поля
fieldName string Название поля
fieldDataType int Тип данных поля
fieldValue string Значение поля

POST /Reservations/{id}/UpdateClientField — запрос (UpdateClientFieldDto)

Поле Тип Обяз. Описание
clientId int да ID клиента
fieldId int да ID дополнительного поля
value string — Новое значение

Ответ: HTTP 200 (без тела).

GET /Reservations/{id}/ClientFields — ответ (ClientFieldsResponseDto)

Поле Тип Описание
fields array Список всех доступных дополнительных полей
values array Значения полей для гостей в бронировании

Поля элемента fields (ClientFieldDto):

Поле Тип Описание
id int ID поля
name string Название поля
dataType int Тип данных
dataTypeValues string Возможные значения (для типа «список»)

Поля элемента values (ClientFieldValueDto):

Поле Тип Описание
clientId int ID клиента
fieldId int ID поля
value string Значение

POST /Reservations/{id}/DoAction — запрос (DoActionRequestDto)

Поле Тип Обяз. Описание
action string да Название действия

Ответ (DoActionResponseDto):

Поле Тип Описание
success int Результат: 1 = успех, 0 = ошибка
message string Сообщение о результате
reload int Необходимость перезагрузки: 1 = да

POST /Reservations/OrderReservations — запрос (OrderReservationsRequestDto)

Возвращает все бронирования, входящие в состав одного заказа. Можно указать либо orderId, либо reservationId (тогда заказ будет найден автоматически по бронированию).

Поле Тип Обяз. Описание
orderId int —* Идентификатор заказа
reservationId int —* Идентификатор бронирования (будет найден заказ, к которому принадлежит бронь)

* Хотя бы одно из полей должно быть указано. Если указаны оба — приоритет у orderId.

Ответ (OrderReservationsResponseDto):

Поле Тип Описание
orderId int? Идентификатор заказа (null, если бронирование не привязано к заказу)
reservations array ReservationDto Список бронирований в заказе

Особые случаи:

  • Если передан только reservationId и бронирование не привязано к заказу — возвращается только это бронирование с orderId: null
  • Если заказ не найден — ошибка 404 (XERR_REF_NOT_FOUND)

Rooms — Номера

Метод Путь Описание
GET /Rooms Список всех номеров
GET /Rooms/{id} Получить номер по ID
POST /Rooms Создать номер
PUT /Rooms/{id} Изменить номер
GET /Rooms/{id}/CleanupStatus Статус уборки номера

Запрос на создание/изменение (AddRoomDto)

Поле Тип Обяз. Описание
number string — Номер комнаты
roomTypeId int да ID категории номера (не может быть 0)
building string — Корпус
stage int — Этаж
comment string — Комментарий

При изменении: нельзя сменить категорию номера, если для этого номера существуют бронирования.

Ответ (RoomDto)

Поле Тип Описание
id int ID номера
number string Номер комнаты
name string Название
roomTypeId int ID категории номера
roomTypeName string Название категории
building string Корпус
stage int Этаж
comment string Комментарий

GET /Rooms/{id}/CleanupStatus — ответ (RoomCleanupStatusDto)

Возвращает текущий статус уборки номера.

Поле Тип Описание
roomId int ID номера
roomNumber string Номер комнаты
status string Код статуса уборки (см. ниже)
isClean bool Номер чистый (true) / требует уборки (false)
lastActionId int? ID последнего действия по уборке
lastActionDate datetime? Дата последнего действия

Коды статусов (status):

Код Описание
CL Clean — номер чистый
DI Dirty — номер грязный
IP In Progress — уборка в процессе
OC Out of Cleaning — уборка не требуется
UN Unknown — неизвестный статус

--- — Категории номеров

Метод Путь Описание
GET /RoomTypes Список категорий номеров
GET /RoomTypes/{id} Получить категорию по ID
POST /RoomTypes Создать категорию
PUT /RoomTypes/{id} Изменить категорию

Запрос на создание/изменение (AddRoomTypeDto)

Поле Тип Обяз. Описание
name string — Название категории
mainPlaces int — Количество основных мест
extraBeds int — Количество дополнительных мест
useInOnline bool — Доступна для онлайн-бронирования
allowHourReservation bool — Доступна для почасового бронирования

Ответ (RoomTypeDto)

Поле Тип Описание
id int ID категории
name string Название
mainPlaces int Количество основных мест
extraBeds int Количество дополнительных мест
useInOnline bool Доступна для онлайн-бронирования
allowHourReservation bool Доступна для почасового бронирования

Tariffs — Тарифы

Метод Путь Описание
GET /Tariffs Список тарифов
GET /Tariffs/{id} Получить тариф по ID
POST /Tariffs Создать тариф
PUT /Tariffs/{id} Изменить тариф
DELETE /Tariffs/{id} Удалить тариф

Запрос на создание/изменение (EditTariffDto)

Поле Тип Обяз. Описание
name string — Название тарифа
comment string — Описание тарифа
dateFrom datetime — Дата начала действия цен
dateUntil datetime — Дата окончания действия цен
salesFrom datetime — Дата начала продаж (null = без ограничений)
salesUntil datetime — Дата окончания продаж (null = без ограничений)
boardingId int — ID типа питания
contragentId int — ID контрагента (для конфиденциальных тарифов)
allowOnline bool — Доступен для онлайн-бронирования
hours4Prepayment int — Часов на внесение предоплаты
prepayment int — Размер предоплаты
prepaymentType int — Единицы предоплаты: 0 = процент, 1 = фиксированная сумма, 2 = количество суток
type int — Тип тарифа: 0 = суточный, 1 = почасовой, 2 = динамический

Ответ (TariffDto)

Все поля из запроса + id (int) — ID тарифа.


Payments — Платежи

Метод Путь Описание
GET /Payments?reservationId={id} Платежи бронирования
GET /Payments/{id} Получить платёж по ID
POST /Payments Добавить платёж
PUT /Payments/{id} Изменить платёж
DELETE /Payments/{id} Удалить платёж

Запрос на создание/изменение (AddPaymentDto)

Поле Тип Обяз. Описание
reservationId int да ID бронирования
date datetime да Дата платежа
sum decimal да Сумма платежа
paymentTypeId int да ID типа платежа (из справочника PaymentTypes)
contragentIsPayer bool — Контрагент является плательщиком
clientId int — ID клиента
comment string — Комментарий
ourFirmId int — ID юридического лица
sumCurrency decimal — Сумма в валюте
currency string — Код валюты
rate decimal — Курс обмена
accruals array int — Массив ID начислений, к которым привязан платёж

Ответ (PaymentDao)

Поле Тип Описание
id int ID платежа
clientId int ID клиента
date datetime Дата платежа
comment string Комментарий
sum decimal Сумма
invoiceNumber string Номер счёта в платёжной системе
contragentIsPayer bool Контрагент является плательщиком
checkNo string Номер чека
paymentTypeId int ID типа платежа
extraserviceId int ID доп. услуги
ourFirmId int ID юридического лица
depositId int ID депозита
allowReturnSum decimal Сумма, доступная для возврата
kkmId string ID кассы
sumCurrency decimal Сумма в валюте
currency string Код валюты
rate decimal Курс

Accruals — Начисления

Метод Путь Описание
GET /Accruals?reservationId={id} Начисления бронирования
GET /Accruals/{id} Получить начисление по ID
POST /Accruals Добавить начисление
PUT /Accruals/{id} Изменить начисление
DELETE /Accruals/{id} Удалить начисление

Запрос на создание (AddAccrualDto)

Поле Тип Обяз. Описание
reservationId int да ID бронирования
count int да Количество
sum decimal да Сумма
comment string — Комментарий
extraServiceId int — ID доп. услуги
executeDate datetime — Дата предоставления
contragentIsPayer bool — Контрагент является плательщиком
clientId int — ID клиента (за кого начисление)

Запрос на изменение (EditAccrualDto)

То же, что AddAccrualDto, но без поля reservationId.

Ответ (AccrualDao)

Поле Тип Описание
id int ID начисления
date datetime Дата создания
sum decimal Сумма
count int Количество
comment string Комментарий
byReservation bool Относится к бронированию
payed decimal Уже оплачено из суммы
dateExecute datetime Дата предоставления
contragentIsPayer bool Контрагент является плательщиком
invoiceNumber string Номер счёта
invoiceValidTill datetime Срок действия счёта
invoicePaymentSystemId int ID платёжной системы
invoiceUrl string URL счёта в платёжной системе
clientId int ID клиента
extraServiceId int ID доп. услуги
extraServiceGroupId int ID группы доп. услуг

Contragents — Контрагенты

Метод Путь Описание
GET /Contragents Список контрагентов
GET /Contragents/{id} Получить контрагента по ID
POST /Contragents Создать контрагента
PUT /Contragents/{id} Изменить контрагента
DELETE /Contragents/{id} Удалить контрагента

Запрос на создание/изменение (EditContragentDto)

Поле Тип Обяз. Описание
fullName string — Полное наименование
shortName string — Краткое наименование
inn string — ИНН
kpp string — КПП
legalAddress string — Юридический адрес
factAddress string — Фактический адрес
account string — Расчётный счёт
corrAccount string — Корреспондентский счёт
bank string — Банк
bik string — БИК
okato string — ОКАТО
eMail string — Email
phone string — Телефон
boss string — Руководитель

Ответ (ContragentDto)

Все поля из запроса + id (int) — ID контрагента.


ExtraServices — Дополнительные услуги

Метод Путь Описание
GET /ExtraServices Список доп. услуг
GET /ExtraServices/{id} Получить доп. услугу по ID
POST /ExtraServices Создать доп. услугу
PUT /ExtraServices/{id} Изменить доп. услугу
DELETE /ExtraServices/{id} Удалить доп. услугу

Запрос на создание/изменение (EditExtraServiceDto)

Поле Тип Обяз. Описание
name string — Название услуги
description string — Описание
groupId int — ID группы услуг
cost float — Цена
unit string — Единица измерения
barcode string — Штрих-код
serviceType int — Тип: 0 = услуга, 1 = товар
onlineSellAvailable bool — Доступна для онлайн-продажи
onlineSelectCount bool — Разрешён выбор количества
onlineDefaultCountType int — Тип единицы измерения по умолчанию
onlineMaxCount int — Максимальное количество при онлайн-продаже
order int — Порядковый номер
params array string — Дополнительные параметры (максимум 2)

Ответ (ExtraServiceDto)

Все поля из запроса + id (int) — ID услуги.


ExtraServiceGroups — Группы дополнительных услуг

Метод Путь Описание
GET /ExtraServiceGroups Список групп доп. услуг
GET /ExtraServiceGroups/{id} Получить группу по ID
POST /ExtraServiceGroups Создать группу
PUT /ExtraServiceGroups/{id} Изменить группу
DELETE /ExtraServiceGroups/{id} Удалить группу

Запрос на создание/изменение (AddExtraServiceGroupDto)

Поле Тип Обяз. Описание
name string да Название группы
order int — Порядок сортировки
typeName string — Название типа группы. Если тип с таким названием существует — будет выбран, иначе — создан

Ответ (ExtraServiceGroupDto)

Поле Тип Описание
id int ID группы
name string Название
order int Порядок
typeName string Название типа группы

Hotels — Отель

Метод Путь Описание
GET /Hotels/Info Информация об отеле

Ответ (HotelInfoDto)

Поле Тип Описание
id int ID отеля
name string Название
phone string Телефон
address string Адрес
email string Email
timezoneOffset int Смещение часового пояса

Users — Пользователи

Метод Путь Описание
GET /Users Список пользователей отеля

Ответ (UserDto)

Поле Тип Описание
id int ID пользователя
login string Логин
email string Email
phone string Телефон
isActive int Активен: 1 = да, 0 = нет
userCulture string Локализация

PaymentTypes — Типы платежей

Метод Путь Описание
GET /PaymentTypes Список типов платежей

Ответ (PaymentTypeDto)

Поле Тип Описание
id int ID типа платежа
name string Название
description string Описание

Fields — Дополнительные поля

Метод Путь Описание
GET /Fields Список дополнительных полей

Ответ (FieldDto)

Поле Тип Описание
id int ID поля
name string Наименование
dataType int Тип данных
dataTypeName string Название типа данных
dataTypeValues string Возможные значения (для типа «список»)
order int Порядок

SimpleReferences — Справочники

Метод Путь Описание
GET /SimpleReferences Список справочников
GET /SimpleReferences/{id} Получить справочник по ID
POST /SimpleReferences Создать справочник
PUT /SimpleReferences/{id} Изменить справочник
DELETE /SimpleReferences/{id} Удалить справочник

Справочники с referenceTypeID = 2 защищены: их нельзя создавать, изменять и удалять через API.

Запрос на создание/изменение (EditSimpleReferenceDto)

Поле Тип Обяз. Описание
referenceTypeID int да ID типа справочника (не может быть 2)
name string — Название
description string — Описание
intValue int — Целочисленное значение
intValue2 int — Целочисленное значение 2
intValue3 int — Целочисленное значение 3
decimalValue decimal — Десятичное значение
stringValue string — Строковое значение
dateTimeValue datetime — Значение даты/времени

Ответ (SimpleReferenceDto)

Все поля из запроса + id (int) — ID справочника.


SimpleReferenceTypes — Типы справочников

Метод Путь Описание
GET /SimpleReferenceTypes Список типов справочников

Ответ (SimpleReferenceTypesDto)

Поле Тип Описание
id int ID типа
name string Наименование
description string Описание

WebHooks — Вебхуки

Метод Путь Описание
GET /WebHooks Список вебхуков
GET /WebHooks/{id} Получить вебхук по ID
POST /WebHooks Создать вебхук
PUT /WebHooks/{id} Изменить вебхук
DELETE /WebHooks/{id} Удалить вебхук

Запрос на создание (AddWebHookDto)

Поле Тип Обяз. Описание
hookType string да Тип вебхука. Допустимое значение: "Reservation"
url string да URL для отправки уведомлений

Запрос на изменение (EditWebHookDto)

Поле Тип Обяз. Описание
url string — Новый URL
isDisabled int — Отключён: 1 = да, 0 = нет

Ответ (ReadWebHookDto)

Поле Тип Описание
id int ID вебхука
hookType string Тип: "Reservation"
url string URL
isDisabled int Отключён: 1 = да, 0 = нет

Debug — Тестовые эндпоинты

Не требуют авторизации. Используются для проверки доступности API.

Метод Путь Описание
POST /Debug/Success Возвращает HTTP 200
POST /Debug/Error Возвращает HTTP 400
POST /Debug/Timeout Задержка 10 секунд, затем HTTP 200

OnlineWidget — Поиск доступных номеров

Метод Путь Описание
GET /OnlineWidget/Info Поиск номеров, доступных к бронированию

Запрос (OnlineWidgetGetVariantsDto)

Тело запроса передаётся в GET-запросе (body).

Поле Тип Обяз. Описание
language string — Язык
currency string — Валюта
dateFrom datetime — Дата заезда
dateTo datetime — Дата выезда
roomsOnly bool — Возвращать только номера (без койкомест)
roomCategoryOptionsIDs string — Фильтр по категориям (ID через запятую)
tariffID int — Фильтр по тарифу
isPromotionGroup bool — true если в tariffID указана промоакция
tariffOptionsIDs string — Фильтр по тарифам (ID через запятую)
promoCode string — Промокод
largePictures bool — true для больших картинок
token string — Токен отеля
onlineWidgetRoomGuestsTVP array — Список номеров и их вместимости

Поля элемента onlineWidgetRoomGuestsTVP:

Поле Тип Описание
adults int Количество взрослых
kidsAges string Возраста детей через запятую (null если детей нет)

Примечание: Ответ зависит от выполнения хранимой процедуры api.OnlineWidgetGetVariants и может отличаться для разных отелей.


Примеры запросов (cURL)

Во всех примерах используется переменная TOKEN — замените на ваш Bearer-токен.

Информация об отеле

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Hotels/Info" \
  -H "Authorization: Bearer $TOKEN"

Ответ:

{
  "id": 123,
  "name": "Название отеля",
  "address": "Адрес отеля",
  "phone": "+7-999-123-45-67",
  "email": "hotel@example.com"
}

Список номеров

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Rooms" \
  -H "Authorization: Bearer $TOKEN"

Ответ:

[
  {
    "id": 1,
    "number": "101",
    "roomTypeId": 2,
    "building": "Корпус 1",
    "stage": 1,
    "comment": null
  }
]

Категории номеров

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/RoomTypes" \
  -H "Authorization: Bearer $TOKEN"

Тарифы

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Tariffs" \
  -H "Authorization: Bearer $TOKEN"

Поиск бронирований по фильтру

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/ByFilter" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "createdStart": "2024-01-01T00:00:00.000Z",
    "createdEnd": "2024-12-31T23:59:59.000Z",
    "isAnnul": false,
    "pagination": {
      "from": 0,
      "count": 20
    }
  }'

Ответ:

{
  "count": 1,
  "items": [
    {
      "id": 456,
      "number": 789,
      "clientGuid": "e9ef745c-e70b-4699-9e93-6c3a159e9ffc",
      "hotelId": 123,
      "hotelName": "Название отеля",
      "from": "2024-03-15T14:00:00",
      "until": "2024-03-18T12:00:00",
      "date": "2024-03-10T10:30:00",
      "roomTypeId": 2,
      "roomId": 1,
      "roomNumber": "101",
      "roomTypeName": "Стандарт",
      "checkInStatus": "Wait",
      "isAnnul": false,
      "tariffId": 5,
      "statusID": 1,
      "agencyID": 0,
      "contractID": 0,
      "contractName": null,
      "contactName": "Иванов Иван",
      "contactPhone": "+7-999-123-45-67",
      "contactEmail": "ivanov@example.com",
      "commentHotel": "",
      "commentGuest": "",
      "responsibleId": 0,
      "ourFirmId": null,
      "reservationPrice": 15000.0,
      "discount": 0.0,
      "guests": [
        {
          "id": 1,
          "lastName": "Иванов",
          "firstName": "Иван",
          "middleName": "Иванович",
          "country": "Россия",
          "birthDate": "1990-05-15T00:00:00",
          "email": "ivanov@example.com",
          "phone": "+7-999-123-45-67",
          "accommodation": "Основное"
        }
      ]
    }
  ]
}

Получение бронирований по списку ID

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/List" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[123, 456, 789]'

Гости бронирования

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Reservations/456/Guests" \
  -H "Authorization: Bearer $TOKEN"

Заселение (Check-in)

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/456/Checkin" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"roomId": 1}'

Выселение (Check-out)

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/456/Checkout" \
  -H "Authorization: Bearer $TOKEN"

Добавление гостя

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/AddOrUpdateGuest" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": 456,
    "clientId": 0,
    "surname": "Иванов",
    "firstName": "Иван",
    "patronomic": "Иванович",
    "phone": "+7-999-123-45-67",
    "email": "ivanov@example.com",
    "isRFSitizenship": true,
    "sex": 1,
    "passport": {
      "docType": "Паспорт гражданина РФ",
      "series": "1234",
      "number": "567890",
      "getBy": "ОВД г. Москвы",
      "getByCode": "770-001",
      "docDate": "2015-06-20T00:00:00.000Z"
    }
  }'

Платежи бронирования

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Payments?reservationId=456" \
  -H "Authorization: Bearer $TOKEN"

Ответ:

[
  {
    "id": 10,
    "clientId": null,
    "date": "2024-03-15T12:00:00",
    "comment": "Оплата проживания",
    "sum": 5000.0,
    "invoiceNumber": null,
    "contragentIsPayer": false,
    "checkNo": null,
    "paymentTypeId": 1,
    "extraserviceId": null,
    "ourFirmId": null,
    "depositId": null,
    "allowReturnSum": 5000.0,
    "kkmId": null,
    "sumCurrency": 0.0,
    "currency": null,
    "rate": 0.0
  }
]

Добавление платежа

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationId": 456,
    "date": "2024-03-15T12:00:00.000Z",
    "sum": 5000.00,
    "paymentTypeId": 1,
    "comment": "Оплата проживания",
    "contragentIsPayer": false
  }'

Начисления бронирования

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Accruals?reservationId=456" \
  -H "Authorization: Bearer $TOKEN"

Ответ:

[
  {
    "id": 20,
    "date": "2024-03-15T14:00:00",
    "sum": 15000.0,
    "count": 3,
    "comment": "Проживание",
    "byReservation": true,
    "payed": 5000.0,
    "dateExecute": "2024-03-15T14:00:00",
    "contragentIsPayer": false,
    "invoiceNumber": null,
    "invoiceValidTill": null,
    "invoicePaymentSystemId": 0,
    "invoiceUrl": null,
    "clientId": null,
    "extraServiceId": null,
    "extraServiceGroupId": null
  }
]

Контрагенты

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Contragents" \
  -H "Authorization: Bearer $TOKEN"

Дополнительные услуги

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/ExtraServices" \
  -H "Authorization: Bearer $TOKEN"

Создание вебхука

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/WebHooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hookType": "Reservation",
    "url": "https://your-server.com/webhook/reservations"
  }'

Типы платежей

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/PaymentTypes" \
  -H "Authorization: Bearer $TOKEN"

Пользователи

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Users" \
  -H "Authorization: Bearer $TOKEN"

Справочники

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/SimpleReferences" \
  -H "Authorization: Bearer $TOKEN"

Типы справочников

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/SimpleReferenceTypes" \
  -H "Authorization: Bearer $TOKEN"

Тестовый запрос (без авторизации)

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Debug/Success"

Бронирования заказа

curl -X POST "https://cloud.shelter.ru/sheltercloudapi/Reservations/OrderReservations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orderId": 12345}'

Ответ:

{
  "orderId": 12345,
  "reservations": [
    {
      "id": 456,
      "number": 789,
      "clientGuid": "e9ef745c-e70b-4699-9e93-6c3a159e9ffc",
      "hotelId": 123,
      "hotelName": "Название отеля",
      "from": "2024-03-15T14:00:00",
      "until": "2024-03-18T12:00:00",
      "date": "2024-03-10T10:30:00",
      "roomTypeId": 2,
      "roomId": 1,
      "roomNumber": "101",
      "roomTypeName": "Стандарт",
      "checkInStatus": "Wait",
      "isAnnul": false,
      "tariffId": 5,
      "statusID": 1,
      "guests": []
    }
  ]
}

Статус уборки номера

curl -X GET "https://cloud.shelter.ru/sheltercloudapi/Rooms/1/CleanupStatus" \
  -H "Authorization: Bearer $TOKEN"

Ответ:

{
  "roomId": 1,
  "roomNumber": "101",
  "status": "CL",
  "isClean": true,
  "lastActionId": 0,
  "lastActionDate": "2024-03-15T10:00:00"
}

Вебхуки (WebHooks)

ShelterCloudAPI поддерживает вебхуки для получения уведомлений об изменениях в бронированиях.

Примечание: Вебхуки срабатывают на изменения из любых источников: ShelterCloudAPI, Shelter API (hmsShelterApi), PMS Shelter и API виджета бронирования.

Механизм работы вебхуков

  1. Регистрация вебхука: Вы создаёте вебхук через API, указывая URL для получения уведомлений
  2. Мониторинг изменений: Фоновый сервис WebHooksMonitor периодически (каждые 35 секунд по умолчанию) проверяет таблицу Reservations на наличие обновлений
  3. Определение изменений: Сервис сравнивает поле D_UpdateDate бронирований с D_LastSendDate вебхука:
    • Если D_UpdateDate > D_LastSendDate — бронирование изменилось
    • Если D_LastSendDate IS NULL и есть новые бронирования — первое срабатывание
  4. Отправка уведомления: На указанный URL отправляется HTTP POST с JSON-телом, содержащим массив ID изменённых бронирований
  5. Обновление статуса: После успешной отправки (HTTP 200) обновляется D_LastSendDate вебхука

Типы вебхуков

Тип Описание
Reservation Уведомление об обновлении бронирований

Формат уведомления

При обнаружении изменений сервис отправляет на ваш URL HTTP POST запрос:

{
  "reservations": [123, 456, 789]
}

Требования к обработчику:

  • Ваш сервер должен вернуть HTTP 200 для подтверждения получения
  • Таймаут ожидания ответа: 5 секунд
  • После получения списка ID запросите детали через POST /Reservations/List

Какие изменения вызывают вебхук

Вебхук срабатывает при изменении поля D_UpdateDate в таблице Reservations. Это происходит при:

Источник Операция Метод / Процедура
ShelterCloudAPI Заселение POST /Reservations/{id}/Checkin
Выселение POST /Reservations/{id}/Checkout
Добавление гостя POST /Reservations/AddOrUpdateGuest
Редактирование гостя POST /Reservations/AddOrUpdateGuest
Удаление гостя POST /Reservations/DeleteGuest
Добавление платежа POST /Payments
Редактирование платежа PUT /Payments/{id}
Удаление платежа DELETE /Payments/{id}
Добавление начисления POST /Accruals
Редактирование начисления PUT /Accruals/{id}
Удаление начисления DELETE /Accruals/{id}
Выполнение действия POST /Reservations/{id}/DoAction (зависит от типа действия)
Shelter API (связка Про-Клауд или внешняя ПМС-Клауд) Создание/обновление брони booking_add_or_update (только при реальном изменении данных)
Shelter (PMS) Создание бронирования Через интерфейс или API виджета
Отмена бронирования Через интерфейс или API виджета
Изменение параметров брони Через интерфейс
Изменение статуса оплаты Автоматически при платёжных операциях
Любые другие изменения Через интерфейс Shelter

Важно: Метод booking_add_or_update в Shelter API обновляет D_UpdateDate только если данные бронирования действительно изменились (сравниваются все поля). При идентичных данных вебхук не срабатывает.

Какие изменения НЕ вызывают вебхук

Источник Операция Метод / Причина
ShelterCloudAPI Обновление доп. поля бронирования POST /Reservations/{id}/UpdateField — обновляет только ReservationFields
Обновление доп. поля гостя POST /Reservations/{id}/UpdateClientField — обновляет только ReservationClientFields
Чтение бронирований GET-запросы не изменяют данные
Чтение гостей, платежей, начислений Операции только для чтения
Управление номерами GET/POST/PUT /Rooms — не связано с бронированиями
Управление категориями номеров GET/POST/PUT /RoomTypes — не связано с бронированиями
Управление тарифами GET/POST/PUT/DELETE /Tariffs — не связано с бронированиями
Управление контрагентами GET/POST/PUT/DELETE /Contragents — не связано с бронированиями
Управление доп. услугами GET/POST/PUT/DELETE /ExtraServices — не связано с бронированиями
Управление справочниками GET/POST/PUT/DELETE /SimpleReferences — не связано с бронированиями
Shelter API Аннулирование брони booking_set_annuled — обновляет только N_Annul, V_AnnulDescription, D_DateAnnul
Подтверждение доставки booking_set_delivered — обновляет только системное поле DeliveredToShelter
Добавление/изменение платежа add_or_update_cash — обновляет только таблицу Cash

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

Метод POST /Reservations/{id}/DoAction вызывает вебхук только для некоторых действий:

Действие Вызывает вебхук Примечание
Изменение статуса брони Да Если статус связан с оплатой
Создание ключа TTLock Да Обновляет системные поля
Привязка промоакции Нет Только доп. поля
Другие действия Зависит Определяется конкретной бизнес-логикой

Shelter API (hmsShelterApi)

Помимо ShelterCloudAPI, существует отдельный Shelter API (endpoint /exec/{method}), который также может влиять на бронирования:

Метод Вызывает вебхук Примечание
booking_add_or_update Да При реальном изменении данных брони, гостей или начислений
booking_set_annuled Нет Не обновляет D_UpdateDate
booking_set_delivered Нет Обновляет только системное поле DeliveredToShelter
add_or_update_cash Нет Обновляет только таблицу Cash без каскада к Reservations
get_bookings Нет Только чтение
set_price Нет Управление ценами
set_quota Нет Управление квотами
set_stop Нет Управление стоп-продажами
set_min_stay / set_max_stay Нет Управление мин/макс проживанием
add_or_update_room Нет Управление номерами
add_or_update_roomtype Нет Управление категориями
add_or_update_rate Нет Управление тарифами
add_or_update_contragent Нет Управление контрагентами
add_or_update_extra_services Нет Управление доп. услугами

Важно: Метод booking_add_or_update в Shelter API обновляет D_UpdateDate только при фактическом изменении данных. Процедура сравнивает все поля бронирования и обновляет timestamp только если есть различия.

Политика повторных попыток

При ошибках отправки применяется экспоненциальная политика повторных попыток:

Длительность ошибок Интервал повторной попытки Действие
Первая ошибка 1 минута Повторная отправка
Более 1 часа 6 часов Увеличение интервала
Более 7 дней — Вебхук автоматически отключается

Политика отключения

Вебхук автоматически отключается (поле N_Disabled = 1) при:

  • Ошибках отправки в течение более 7 дней подряд
  • Невозможности получить HTTP 200 от вашего сервера

Для повторной активации вебхука:

  1. Исправьте проблему на вашем сервере
  2. Обновите вебхук: PUT /WebHooks/{id} с "isDisabled": 0

Управление вебхуками

# Создать вебхук
curl -X POST "https://cloud.shelter.ru/sheltercloudapi/WebHooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hookType": "Reservation", "url": "https://your-server.com/webhook"}'

# Список вебхуков
curl -X GET "https://cloud.shelter.ru/sheltercloudapi/WebHooks" \
  -H "Authorization: Bearer $TOKEN"

# Отключить вебхук
curl -X PUT "https://cloud.shelter.ru/sheltercloudapi/WebHooks/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "isDisabled": 1}'

# Включить вебхук
curl -X PUT "https://cloud.shelter.ru/sheltercloudapi/WebHooks/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "isDisabled": 0}'

# Удалить вебхук
curl -X DELETE "https://cloud.shelter.ru/sheltercloudapi/WebHooks/1" \
  -H "Authorization: Bearer $TOKEN"

Пример обработки вебхука

# Python Flask example
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/reservations', methods=['POST'])
def handle_webhook():
    # Получаем список ID изменённых бронирований
    data = request.json
    reservation_ids = data.get('reservations', [])
    
    # Подтверждаем получение (обязательно HTTP 200)
    # Запрос деталей будет выполняться асинхронно
    
    # Запускаем асинхронную обработку
    process_reservations.delay(reservation_ids)
    
    return '', 200

def process_reservations(reservation_ids):
    # Запрашиваем детали бронирований
    response = requests.post(
        'https://cloud.shelter.ru/sheltercloudapi/Reservations/List',
        headers={'Authorization': 'Bearer YOUR_TOKEN'},
        json=reservation_ids
    )
    
    reservations = response.json()
    
    # Обрабатываем изменения
    for res in reservations:
        # Ваша логика обработки
        pass

Рекомендации

  1. Быстрый ответ: Ваш обработчик должен возвращать HTTP 200 как можно быстрее (в пределах 5 секунд)
  2. Асинхронная обработка: Запрос деталей бронирований выполняйте в фоновом задании
  3. Идемпотентность: Обрабатывайте уведомления идемпотентно — одно бронирование может прийти несколько раз
  4. Дедупликация: Храните историю обработанных уведомлений по D_UpdateDate бронирования
  5. Мониторинг: Логируйте все полученные уведомления для отладки
  6. Повторный запрос: Если при обработке произошла ошибка, запросите бронирование повторно через API

Swagger

Интерактивная документация доступна по адресу:

https://cloud.shelter.ru/sheltercloudapi/swagger/index.html

Резервный адрес:

https://pms.frontdesk24.ru/sheltercloudapi/swagger/index.html

OpenAPI-спецификация (JSON):

https://cloud.shelter.ru/sheltercloudapi/swagger/v1/swagger.json

Для авторизации в Swagger UI:

  1. Нажмите кнопку Authorize в правом верхнем углу
  2. В поле Value введите: Bearer ВАШ_ТОКЕН
  3. Нажмите Authorize