Руководство по началу работы с Shelter CLOUD PMS API

Описание

ShelterCloudAPI — это интерфейс для взаимодействия внешних систем с данными в системе управления отелем Shelter CLOUD. Он позволяет получать и изменять информацию через стандартные HTTP-запросы.

Тестовые среды

Указанные ссылки ведут на встроенный инструмент тестирования запросов — Swagger.

Предварительные требования

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

  • Приобрести и активировать модуль Shelter CLOUD API. Указанный модуль должен быть включен в тариф вашего объекта размещения.
  • Получить токен доступа в технической поддержке после активации модуля.
  • Авторизоваться в инструменте Swagger. Для этого нажать кнопку Authorize и ввести полученный токен после слова Bearer.

Работа со Swagger

Запросы в Swagger сгруппированы по функционалу. Например, группа Accruals для работы с начислениями.

  1. Разверните нужный запрос, чтобы увидеть его параметры и описание.
  2. Нажмите кнопку Try it out, заполните параметры и выполните запрос.
  3. После выполнения отобразятся полный cUrl-запрос и ответ сервера.

Важно! Shelter CLOUD API не делает различий между запросами из Swagger и других инструментов (Postman, Bruno и т.д.). Если запрос работает в Swagger, он будет работать и извне.

Доступные методы API

Методы сгруппированы для работы со следующими сущностями:

  1. Accruals — Начисления
  2. Contragents — Контрагенты
  3. Debug — Отладка (служебная, не для внешнего ПО)
  4. ExtraServiceGroups — Группы доп. услуг
  5. ExtraServices — Доп. услуги
  6. Fields — Справочник дополнительных полей
  7. Hotels — Отель
  8. Payments — Платежи
  9. PaymentTypes — Типы платежей
  10. Reservations — Бронирования
  11. Rooms — Номера
  12. RoomTypes — Категории номеров
  13. SimpleReferences — Простые справочники
  14. SimpleReferenceTypes — Типы простых справочников
  15. Tariffs — Тарифы (не цены)
  16. Users — Пользователи
  17. 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 } ]

Пример заселения гостя

  1. Получите список бронирований и список номеров (как в примере выше).
  2. Из ответа возьмите id нужного бронирования и id номера (roomId).
  3. Выполните запрос на заселение, подставив полученные значения.

Запрос на заселение:

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.