Sections and articles

Getting Started with the Shelter CLOUD PMS API

Description

ShelterCloudAPI is an interface for external systems to interact with data in the Shelter CLOUD PMS. It allows you to receive and change information.

The protocol is published on the following stands:

These links lead to the built—in query testing tool Swagger.

Terms of use

To work with the API, you must:

  • Purchase and activate the Shelter CLOUD API module. The specified module must be included in the tariff of your accommodation facility.

  • Get an access token from technical support after activating the module.

  • Log in to the Swagger tool. To do this, click Authorize and enter the received token after the word Bearer.

Working with Swagger

Swagger requests are grouped by functionality. For example, the Accruals group for working with accruals.

  1. Expand the desired query to see its parameters and description.

  2. Click the Try it out button, fill in the parameters, and complete the request.

  3. After execution, the full cUrl request and the server response will be displayed.

Important: The Shelter CLOUD API does not distinguish between requests from Swagger and other tools (Postman, Bruno, etc.). If the request works in Swagger, it will also work externally.

Available API methods

The methods are grouped to work with the following entities:

  1. Accruals — Accruals
  2. Contragents — Counterparties
  3. Debug — Debugging (service, not for external software)
  4. ExtraServiceGroups — Additional groups. services
  5. ExtraServices — Add. services
  6. Fields — Directory of additional fields
  7. Hotels — The Hotel
  8. Payments — Payments
  9. PaymentTypes — Payment Types
  10. Reservations — Reservations
  11. Rooms — Rooms
  12. RoomTypes — Room Categories
  13. SimpleReferences — Simple Reference Books
  14. SimpleReferenceTypes — Types of simple reference books
  15. Tariffs — Tariffs (not prices)
  16. Users — Users
  17. WebHooks — Webhooks

Important: Not all entities can be added or modified via the API. For example, reservations cannot be created in this API. The Booking Widgets API is used to create a reservation.

Group Features

Reservations Group

Supported methods:

  • Getting a list of bookings by ID or filter.

  • Getting a guest list for a specific booking.

  • Getting the data of a certain guest.

  • Adding, changing, and deleting guests.

  • Check-in and check-out based on a specific reservation.

  • Managing additional booking fields.

Important: Creating, changing, and canceling bookings through this API is not available. This functionality is partially implemented in the Booking widget API.

Reference groups

These include:

  • Contragents,

  • ExtraServiceGroups,

  • ExtraServices,

  • Fields,

  • PaymentTypes,

  • Rooms,

  • RoomTypes,

  • SimpleReferences,

  • SimpleReferenceTypes,

  • Tariffs,

  • Users.

Important: Most of the methods in these groups support not only getting a list, but also adding, changing, and deleting items. However, the functionality may be limited compared to the PMS Shelter Cloud interface (for example, it is not possible to upload images for room categories).

WebHooks

Currently, one type of webhook notification is supported: Reservation. When subscribing to the specified URL, the booking ID will be sent, in which changes have occurred (guests, charges, payments, etc.). To receive complete booking data, you need to make a separate request.

API Applicability

Using the API, you can solve various tasks, including:

  • Integration with CRM systems for transferring bookings from PMS.

  • Integration with mailing systems.

  • Building external reporting.

  • External management of charges and payments.

  • Online check-in management.

Usage example

Task: To receive all reservations in which guests stayed, checked in or left on March 19, 2025.

Request:

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 } }'

Explanation of the request:

  • Authorization is the header for transmitting the ShelterCloudToken token. Important: The word Bearer is required before the token.

  • livedFrom/livedTo — start and end of the specified time interval.

  • isAnnul: false — exclude cancelled bookings.

  • pagination — pagination settings: how many armor, starting from zero, should be displayed on the page. In this example, up to 10 armor pieces.

Answer:

The server will return an object with a count and an array of items, the structure of which is described in the ReservationDto in Swagger.

 {   the beginning of the package
 "count": 2,  number of items in the output
 "items": [   the beginning of the armor list
   {   the beginning of the first booking data
  "id": 13035476,  booking ID
   "number": 3003,   booking number
   "clientGuid": null,  guest token
   "hotelId": 1570,    Hotel ID
   "hotelName": "Firefly",   The name of the hotel
   "from": "2025-03-18T13:00:00",     date and time of arrival
  "until": "2025-03-19T12:00:00",   date and time of departure
   "date": "2025-03-10T12:46:50.38",  date and time of creation
   "roomTypeId": 47986,  category ID
  "roomId": 0,   room (room) ID
   "roomNumber": null,   room number
   "roomTypeName": "Penthouse",  Room category name
   "checkInStatus": "Waiting",  check-in status
   "isAnnul": false,     has the booking been cancelled
  "tariffId": 25040,     tariff ID (simple reference)
   "statusID": 7816,   status ID (simple reference)
   "agencyID": 0,  counterparty's ID (reference list)
  "contractID": 0,   contract ID (reference book)
  "contractName": null,  name of the agreement
   "contactName": null,  customer's name
 "contactPhone": null,  customer's phone number
 "contactEmail": null,  customer's email address
 "commentHotel": "",   The hotel's note
  "commentGuest": null,   Guest's note
  "responsibleId": 12037,   ID of the responsible manager (reference list)
 "ourFirmId": null,     the identifier of our company (the directory of counterparties)
  "reservationPrice": 29000,   booking price
   "discount": 0,   discount
  "guests": [   guest list
  {  the beginning of the first guest's data
    "id": 18908171,   guest ID
    "lastName": "Petrov",  last name of the guest
    "firstName": "",     guest's name
    "middleName": "",    patronymic of the guest
  "country": "Russian Federation",   citizenship
  "birthDate": null,   date of birth
    "email": "",   email
    "phone": "",   placement
  "accommodation": "Main"   placement
    }      the end of the first guest's data
   ]  end of the guest list
  },   the end of the first booking data
 {  "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": "Penthouse", "checkInStatus": "Waiting", "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": []     }   
     ]    ending the armor list
   }     end of the package

Getting a list of bookings and rooms:

curl -X 'GET' \ 'https://cloud.shelter.ru/sheltercloudapi/Rooms' \ -H 'accept: text/plain' \ -H 'Authorization: Bearer token_token_token' [ { "id": 116812, "name": "101", "roomTypeName": "2n2dop", "number": "101", "roomTypeId": 47963, "building": null, "stage": null, "comment": null } ]

Example of guest check-in

  1. Get a list of bookings and a list of rooms (as in the example above).

  2. Take the booking ID and room ID (roomId) from the response.

  3. Execute the check-in request by substituting the received values.

Check-in request:

curl -X 'GET' \ 'https://cloud.shelter.ru/sheltercloudapi/Rooms' \ -H 'accept: text/plain' \ -H 'Authorization: Bearer token_token_token' [ { "id": 116812, "name": "101", "roomTypeName": "2n2dop", "number": "101", "roomTypeId": 47963, "building": null, "stage": null, "comment": null } ]

You will receive a ReservationDto in the response.

Table of contents