Shelter Cloud API (ShelterCloudAPI)
Версия: v1 | Статус: Stable | Лицензия: ShelterCloudAPI | Продукт: Shelter Cloud | Уровень: Пользовательский
Оглавление
- Описание модуля
- Ограничения
- Общие сведения
- Схема работы
- Настройки в Shelter
- Аутентификация
- Ограничение частоты запросов
- Логирование (Graylog)
- Коды ответов
- Группы методов
- Примеры запросов (cURL)
- Вебхуки (WebHooks)
- Swagger
Описание модуля
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 необходимы:
- Лицензия на модуль ShelterCloudAPI — без неё API недоступно
- Токен авторизации типа
ShelterCloudApiToken
Получение токена
Токен создаётся на экране управления токенами, доступном по прямой ссылке:
https://cloud.shelter.ru/shelter-cloud/#/tokens
Данный экран доступен только техподдержке Shelter. Для получения токена обратитесь в техподдержку.
При создании токена:
- Тип токена:
ShelterCloudApiToken - Токен привязан к конкретному отелю
- Все запросы через этот токен автоматически ограничены данными только этого отеля
Аутентификация
Все методы API (кроме Debug) требуют аутентификации по схеме Bearer Token.
Формат заголовка
Authorization: Bearer ВАШ_ТОКЕН
Процесс аутентификации
- Из заголовка
Authorizationизвлекается токен - Проверяется наличие токена с типом
ShelterCloudApiTokenв базе данных - Проверяется, что токен активен
- Из токена определяется отель — все дальнейшие операции ограничены данными этого отеля
Ошибки аутентификации
| Ситуация | 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 | |
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 | — | |
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 | — | |
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 | |
timezoneOffset |
int | Смещение часового пояса |
Users — Пользователи
| Метод | Путь | Описание |
|---|---|---|
| GET | /Users |
Список пользователей отеля |
Ответ (UserDto)
| Поле | Тип | Описание |
|---|---|---|
id |
int | ID пользователя |
login |
string | Логин |
email |
string | |
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 виджета бронирования.
Механизм работы вебхуков
- Регистрация вебхука: Вы создаёте вебхук через API, указывая URL для получения уведомлений
- Мониторинг изменений: Фоновый сервис
WebHooksMonitorпериодически (каждые 35 секунд по умолчанию) проверяет таблицуReservationsна наличие обновлений - Определение изменений: Сервис сравнивает поле
D_UpdateDateбронирований сD_LastSendDateвебхука:- Если
D_UpdateDate > D_LastSendDate— бронирование изменилось - Если
D_LastSendDate IS NULLи есть новые бронирования — первое срабатывание
- Если
- Отправка уведомления: На указанный URL отправляется HTTP POST с JSON-телом, содержащим массив ID изменённых бронирований
- Обновление статуса: После успешной отправки (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 от вашего сервера
Для повторной активации вебхука:
- Исправьте проблему на вашем сервере
- Обновите вебхук:
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
Рекомендации
- Быстрый ответ: Ваш обработчик должен возвращать HTTP 200 как можно быстрее (в пределах 5 секунд)
- Асинхронная обработка: Запрос деталей бронирований выполняйте в фоновом задании
- Идемпотентность: Обрабатывайте уведомления идемпотентно — одно бронирование может прийти несколько раз
- Дедупликация: Храните историю обработанных уведомлений по
D_UpdateDateбронирования - Мониторинг: Логируйте все полученные уведомления для отладки
- Повторный запрос: Если при обработке произошла ошибка, запросите бронирование повторно через 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:
- Нажмите кнопку Authorize в правом верхнем углу
- В поле Value введите:
Bearer ВАШ_ТОКЕН - Нажмите Authorize