Описание
ShelterCloudAPI — это интерфейс для взаимодействия внешних систем с данными в системе управления отелем Shelter CLOUD. Он позволяет получать и изменять информацию через стандартные HTTP-запросы.
Тестовые среды
- Продуктовый стенд: https://cloud.shelter.ru/sheltercloudapi/swagger/index.html
- Тестовый стенд: https://test.shelter.ru/sheltercloudapi/swagger/index.html
Указанные ссылки ведут на встроенный инструмент тестирования запросов — Swagger.
Предварительные требования
Для работы с API необходимо:
- Приобрести и активировать модуль Shelter CLOUD API. Указанный модуль должен быть включен в тариф вашего объекта размещения.
- Получить токен доступа в технической поддержке после активации модуля.
- Авторизоваться в инструменте Swagger. Для этого нажать кнопку Authorize и ввести полученный токен после слова Bearer.
Работа со Swagger
Запросы в Swagger сгруппированы по функционалу. Например, группа Accruals для работы с начислениями.
- Разверните нужный запрос, чтобы увидеть его параметры и описание.
- Нажмите кнопку Try it out, заполните параметры и выполните запрос.
- После выполнения отобразятся полный cUrl-запрос и ответ сервера.
Важно! Shelter CLOUD API не делает различий между запросами из Swagger и других инструментов (Postman, Bruno и т.д.).
Если запрос работает в Swagger, он будет работать и извне.
Доступные методы API
Методы сгруппированы для работы со следующими сущностями:
- Accruals — Начисления
- Contragents — Контрагенты
- Debug — Отладка (служебная, не для внешнего ПО)
- ExtraServiceGroups — Группы доп. услуг
- ExtraServices — Доп. услуги
- Fields — Справочник дополнительных полей
- Hotels — Отель
- Payments — Платежи
- PaymentTypes — Типы платежей
- Reservations — Бронирования
- Rooms — Номера
- RoomTypes — Категории номеров
- SimpleReferences — Простые справочники
- SimpleReferenceTypes — Типы простых справочников
- Tariffs — Тарифы (не цены)
- Users — Пользователи
- WebHooks — Веб-хуки
Важно! Не все сущности можно добавлять или изменять через API. Например, бронирования в этом API создать нельзя. Для создания бронирования используется
API виджетов бронирования
.
Особенности групп
Группа Бронирования (Reservations)
Поддерживаемые методы:
- Получение списка бронирований по ID или фильтру.
- Получение списка гостей по определенному бронированию.
- Получение данных определенного гостя.
- Добавление, изменение и удаление гостей.
- Заселение и выезд по определенному бронированию.
- Управление дополнительными полями бронирования.
Группы справочников
К ним относятся:
- Contragents,
- ExtraServiceGroups,
- ExtraServices,
- Fields,
- PaymentTypes,
- Rooms,
- RoomTypes,
- SimpleReferences,
- SimpleReferenceTypes,
- Tariffs,
- Users.
Важно! Большинство методов в этих группах поддерживают не только получение списка, но также добавление,
изменение и удаление элементов. Однако функциональность может быть ограничена по сравнению с интерфейсом
PMS Shelter Cloud (например, невозможна загрузка изображений для категорий номеров).
Веб-хуки (WebHooks)
На данный момент поддерживается один тип вебхук-уведомлений: Reservation. При подписке на указанный URL будет отправляться ID бронирования, в котором произошли изменения (гости, начисления, платежи и т.д.). Для получения полных данных по бронированию требуется выполнить отдельный запрос.
Применимость API
С помощью API можно решать различные задачи, включая:
- Интеграцию с CRM-системами для передачи бронирований из PMS.
- Интеграцию с системами рассылки.
- Построение внешней отчётности.
- Внешнее управление начислениями и платежами.
- Управление онлайн-заселением (чек-ин).
Пример использования
Задача: Получить все бронирования, в которых гости проживали, заезжали или выезжали 19 марта 2025 года.
Запрос:
curl -X 'POST' \
'https://cloud.shelter.ru/sheltercloudapi/Reservations/ByFilter' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer token_token_token' \
-H 'Content-Type: application/json' \
-d '{ "livedFrom": "2025-03-19T00:00:00.000Z", "livedTo": "2025-03-19T23:59:59.000Z", "isAnnul": false, "pagination": { "from": 0, "count": 10 } }'
Пояснение к запросу:
- Authorization — заголовок для передачи токена ShelterCloudToken. Важно: слово Bearer перед токеном обязательно
- livedFrom/livedTo — начало и конец заданного интервала времени.
- isAnnul: false — исключить аннулированные бронирования.
- pagination — настройки разбивки на страницы: сколько броней, начиная с нулевой, выводить на страницу. В данном пример до 10 броней.
Ответ:
Сервер вернёт объект со счётчиком (count) и массивом элементов (items), структура которых описана в ReservationDto в Swagger.
{ начало пакета
"count": 2, число элементов в выдаче
"items": [ начало списка броней
{ начало данных первого бронирования
"id": 13035476, идентификатор бронирования
"number": 3003, номер бронирования
"clientGuid": null, токен гостя
"hotelId": 1570, идентификатор отеля
"hotelName": "Firefly", название отеля
"from": "2025-03-18T13:00:00", дата и время заезда
"until": "2025-03-19T12:00:00", дата и время выезда
"date": "2025-03-10T12:46:50.38", дата и время создания
"roomTypeId": 47986, идентификатор категории
"roomId": 0, идентификатор комнаты (номера)
"roomNumber": null, номер комнаты
"roomTypeName": "Пентхаус ", название категории номера
"checkInStatus": "Ожидание", состояние заезда
"isAnnul": false, отменена ли бронь
"tariffId": 25040, идентификатор тарифа (простой справочник)
"statusID": 7816, идентификатор статуса (простой справочник)
"agencyID": 0, идентификатор контрагента (справочник)
"contractID": 0, идентификатор договора (справочник)
"contractName": null, название договора
"contactName": null, имя заказчика
"contactPhone": null, телефон заказчика
"contactEmail": null, email заказчика
"commentHotel": "", примечание отеля
"commentGuest": null, примечание гостя
"responsibleId": 12037, идентификатор ответственного менеджера (справочник)
"ourFirmId": null, идентификатор нашей фирмы (справочник контрагентов)
"reservationPrice": 29000, цена бронирования
"discount": 0, скидка
"guests": [ список гостей
{ начало данных первого гостя
"id": 18908171, идентификатор гостя
"lastName": "Петров", фамилия гостя
"firstName": "", имя гостя
"middleName": "", отчество гостя
"country": "РФ", гражданство
"birthDate": null, дата рождения
"email": "", email
"phone": "", телефон
"accommodation": "Main" размещение
} окончание данных первого гостя
] окончание списка гостей
}, окончание данных первой брони
{ начало данных второй брони
"id": 13035479, "number": 3004, "clientGuid": null, "hotelId": 1570, "hotelName": "Firefly", "from": "2025-03-18T13:00:00", "until": "2025-03-19T12:00:00", "date": "2025-03-10T12:47:08.613", "roomTypeId": 47986, "roomId": 0, "roomNumber": null, "roomTypeName": "Пентхаус ", "checkInStatus": "Ожидание", "isAnnul": false, "tariffId": 25040, "statusID": 7816, "agencyID": 0, "contractID": 0, "contractName": null, "contactName": null, "contactPhone": null, "contactEmail": null, "commentHotel": null, "commentGuest": null, "responsibleId": 0, "ourFirmId": null, "reservationPrice": 29000, "discount": 0, "guests": [] данные второй брони (гости отсутствуют)
} окончание данных второй брони
] окончание списка броней
} окончание пакета
Получение списка бронирований и комнат:
Получение списка бронирований и комнат:
curl -X 'GET' \
'https://cloud.shelter.ru/sheltercloudapi/Rooms' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer Bearer token_token_token' [ { "id": 116812, "name": "101", "roomTypeName": "2осн2доп", "number": "101", "roomTypeId": 47963, "building": null, "stage": null, "comment": null } ]
Пример заселения гостя
- Получите список бронирований и список номеров (как в примере выше).
- Из ответа возьмите id нужного бронирования и id номера (roomId).
- Выполните запрос на заселение, подставив полученные значения.
Запрос на заселение:
curl -X 'GET' \
'https://cloud.shelter.ru/sheltercloudapi/Rooms' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer token_token_token'
[
{
"id": 116812,
"name": "101",
"roomTypeName": "2осн2доп",
"number": "101",
"roomTypeId": 47963,
"building": null,
"stage": null,
"comment": null
}
]
В ответе придет ReservationDto.