API виджета бронирования Shelter Cloud v2

URL: POST https://cloud.shelter.ru/api/online/getHotelParams

Назначение: Возвращает настройки виджета и справочные данные отеля. Вызывается один раз при инициализации виджета.

Пример: Полный запрос и ответ — GetHotelParams.7z

Запрос

{
  "token": "EE9217BE-2D5C-47AF-93D2-31B9EEFD3317",
  "language": "ru"
}

Ответ

Ответ содержит массив data из 8 вложенных массивов. Порядок массивов фиксирован.

{
  "data": [
    [ /* Массив 1: Настройки виджета */ ],
    [ /* Массив 2: Промокоды */ ],
    [ /* Массив 3: Доступные языки */ ],
    [ /* Массив 4: Опции категорий номеров (справочник) */ ],
    [ /* Массив 5: Группы тарифов */ ],
    [ /* Массив 6: Опции тарифов (справочник) */ ],
    [ /* Массив 7: Категории номеров */ ],
    [ /* Массив 8: Данные отеля */ ]
  ]
}

Массив 1 — Настройки виджета:

{
  "allowBeds": 0,
  "minDateFrom": "2024-09-18T00:00:00",
  "defaultDateFrom": "2024-09-18T00:00:00",
  "defaultDateTo": "2024-09-19T00:00:00",
  "defaultNumberOfGuests": null,
  "minAgeOfChild": null,
  "maxAgeOfChild": null,
  "maxRoomCapacity": null,
  "allowRostourismProgram": false,
  "allowUpsale": true,
  "agreeText": null,
  "agreeUrl": null,
  "metrikaCounter": null,
  "metrikaGoalCalendar": null,
  "metrikaGoalSearch": null,
  "metrikaGoalBasket": null,
  "metrikaGoalBook": null,
  "metrikaGoalConfirm": null,
  "metrikaGoalOrder": null,
  "metrikaGoalPaid": null,
  "analyticsCounter": "123",
  "analyticsGoalCalendar": "1",
  "analyticsGoalSearch": "2",
  "analyticsGoalBasket": "3",
  "analyticsGoalBook": "4",
  "analyticsGoalOrder": "5",
  "analyticsGoalPaid": "6",
  "disableAuth": "0",
  "openPaymentInNewTab": true,
  "fullPaymentIncludeExtra": false,
  "askOnlyFirstGuest": false,
  "defaultPhoneCode": "7",
  "onlyBedPlaces": false
}

Массив 3 — Языки:

{ "id": "ru", "name": "Руccкий" }

Массив 4 — Опции категорий номеров:

{ "id": 2, "name": "Мини-бар", "url": "Content/Gallery/RoomOptions/bar.svg" }

Массив 5 — Группы тарифов:

{ "id": 23974, "name": "Базовый", "isPromotionGroup": false }

Массив 6 — Опции тарифов:

{
  "id": 2,
  "name": "Без предоплаты",
  "url": "Content/Gallery/TariffOptions/prepayment.svg",
  "isIncluded": false
}

Массив 7 — Категории номеров:

{ "id": 6930, "name": "Стандарт" }

Массив 8 — Данные отеля:

{ "hotelName": "Firefly hotel 2", "token": "EE9217BE-2D5C-47AF-93D2-31B9EEFD3317" }

URL: POST https://cloud.shelter.ru/api/online/getVariants

Назначение: Основной метод поиска. Возвращает доступные варианты размещения с ценами для указанных дат и состава гостей.

Пример: Полный запрос и ответ — getVariants.7z

Запрос

{
  "token": "EE9217BE-2D5C-47AF-93D2-31B9EEFD3317",
  "dateFrom": "2024-09-18",
  "dateTo": "2024-09-19",
  "rooms": [
    {
      "adults": 2,
      "kidsAges": "7"
    }
  ]
}

Логика подбора номеров

Система автоматически определяет подходящие номера и рассаживает гостей:

• Номер подходит, если основных мест + доп. мест >= запрошенное кол-во гостей
• Сначала занимаются основные места, затем дополнительные
• Гости рассаживаются начиная со взрослых
• Пример: номер (2 основных + 1 доп.) при поиске на 1 взрослого + 1 ребёнка + 1 младенца → взрослый и ребёнок на основные места, младенец на доп. место

Ответ

Массив data содержит 6 вложенных массивов. Порядок следования обязателен.

{
  "data": [
    [ /* Массив 1: Категории номеров */ ],
    [ /* Массив 2: Опции категорий */ ],
    [ /* Массив 3: Тарифы и акции */ ],
    [ /* Массив 4: Опции тарифов */ ],
    [ /* Массив 5: Фото и видео */ ],
    [ /* Массив 6: Варианты бронирования */ ]
  ]
}

Массив 1 — Категории номеров:

{
  "id": 6930,
  "name": "Стандарт",
  "description": null,
  "availableRooms": 3,
  "availableBeds": 0,
  "roomArea": null,
  "mainBeds": 4,
  "extraBeds": 0,
  "withoutBeds": null,
  "allowConnectBeds": 0
}

Массив 2 — Опции категорий:

{
  "roomCategoryID": 6930,
  "roomCategoryOptionID": 2
}

Связывает категорию номера с опцией из справочника getHotelParams (массив 4).

Массив 3 — Тарифы и акции:

{
  "id": 23974,
  "name": "Базовый",
  "isPromotion": false,
  "description": null,
  "image": null
}

Массив 4 — Опции тарифов:

{
  "tariffID": 23974,
  "isPromotion": false,
  "tariffOptionID": 2
}

Связывает тариф с опцией из справочника getHotelParams (массив 6).

Массив 5 — Фото и видео:

{
  "roomCategoryID": 6930,
  "url": "Content/Gallery/RoomTypes/no-image-grey.jpg",
  "urlLarge": "Content/Gallery/RoomTypes/no-image-grey.jpg",
  "isVideo": false
}

Массив 6 — Варианты бронирования (основной):

{
  "roomCategoryID": 6930,
  "tariffID": 23974,
  "TariffOrder": null,
  "isPromotion": false,
  "bedPlace": false,
  "accmdId": 25203,
  "accmdName": "Основное",
  "price": 5000,
  "currency": null,
  "priceRub": 5000,
  "totalDiscountPercent": 0,
  "promocodeDiscountPercent": 0,
  "promotionDiscountPercent": 0,
  "priceWithoutDiscount": 5000,
  "prepaymentRub": 0,
  "prepaymentCurrency": 0,
  "amountOfAdults": 2,
  "amountOfChildrenWithBeds": 1,
  "KidAge": null,
  "amountOfChildrenWithoutBeds": null,
  "countGuestsOnMainAccmd": 3,
  "countGuestsOnExtraAccmd": 0,
  "countGuestsOnWithoutBed": 0,
  "agesOfChildrenWithBeds": "7",
  "agesOfChildrenWithoutBeds": null,
  "cashbackRub": null
}

Важно: Каждый вариант из getVariants использует свой уникальный signatureId (не показан в примере, но передаётся в ответе). Этот signatureId необходимо передать в putOrder.

URL: POST https://cloud.shelter.ru/api/online/getPaymentOptions

Назначение: Возвращает доступные способы оплаты для выбранного варианта бронирования.

Пример: Полный запрос и ответ — GetPaymentOptions.7z

Запрос

{
  "token": "EE9217BE-2D5C-47AF-93D2-31B9EEFD3317",
  "extraServicesSum": 0,
  "dateFrom": "2024-09-18",
  "dateTo": "2024-09-19",
  "amountOfAdults": 1,
  "amountOfChildren": 1,
  "ageOfChildren": "7",
  "roomCategoriesIDs": "6930",
  "numberOfRooms": 1,
  "tariffsIDs": "23974",
  "promotionsIDs": "",
  "bedPlace": "0",
  "onlyRostourismProgram": false
}

Ответ

{
  "data": [
    {
      "id": 2,
      "name": "Оплата в отеле",
      "description": "Оплата при заезде наличными или картой",
      "image": "Content/Gallery/PaymentTypes/hotel-payment.svg",
      "paymentKind": null
    }
  ]
}

URL: POST https://cloud.shelter.ru/api/online/putOrder

Назначение: Создаёт новое бронирование. Возвращает данные заказа, включая ссылку на оплату (при необходимости).

Пример: Полный запрос и ответ — putOrder.7z

Запрос

{
  "data": {
    "token": "EE9217BE-2D5C-47AF-93D2-31B9EEFD3317",
    "source": "hotel-website.ru",
    "paymentMethodID": 2,
    "comment": "Комментарий от гостя",
    "customer": {
      "email": "guest@example.com",
      "phone": "+79161234567",
      "surname": "Иванов",
      "name": "Иван",
      "secondName": "Иванович"
    },
    "reservations": [
      {
        "dateFrom": "2024-09-18",
        "dateTo": "2024-09-19",
        "roomCategoryID": 6930,
        "tariffID": 23974,
        "isPromotion": 0,
        "promocode": null,
        "guestsCount": 2,
        "bedPlace": 0,
        "currency": "",
        "price": 5000,
        "totalDiscountPercent": 0,
        "promocodeDiscountPercent": 0,
        "promotionDiscountPercent": 0,
        "priceWithoutDiscount": 5000,
        "priceRub": 5000,
        "prepaymentRub": 0,
        "prepaymentCurrency": 0,
        "guests": [
          {
            "surname": "Иванов",
            "name": "Иван",
            "secondName": "Иванович",
            "email": "guest@example.com",
            "phone": "+79161234567",
            "withoutBed": false
          },
          {
            "surname": "Иванова",
            "name": "Мария",
            "secondName": "",
            "age": 7,
            "withoutBed": false
          }
        ]
      }
    ],
    "extraServices": []
  }
}

Описание полей запроса

Корневой объект data:

Объект customer (заказчик):

Объект бронирования (элемент reservations):

Рекомендуется передавать сначала взрослых, потом детей. Количество гостей в массиве не обязано совпадать с guestsCount.

Объект гостя (элемент guests):

Ответ

Массив data содержит 4 вложенных массива:

{
  "data": [
    [ /* Массив 1: Информация о заказе */ ],
    [ /* Массив 2: Бронирования */ ],
    [ /* Массив 3: Гости */ ],
    [ /* Массив 4: Доп. услуги */ ]
  ]
}

Массив 1 — Информация о заказе:

{
  "hotelId": 2398,
  "hotelName": "Firefly hotel 2",
  "hotelAddress": "",
  "hotelLocation": null,
  "hotelEmail": "",
  "hotelPhones": "",
  "hotelImage": "Content/Images/2398_Hotels_638539579700390206_x450.jpg",
  "hotelLocation1": null,
  "bookingCode": 117,
  "createDate": "2024-09-18T14:55:49.187",
  "customerName": "Иванов Иван Иванович",
  "customerPhone": "+79161234567",
  "customerEmail": "guest@example.com",
  "comment": "Комментарий от гостя",
  "paymentMethodName": "Оплата в отеле",
  "accommodationPrice": 5000.0,
  "toPay": 5000.0,
  "prepayment": 5000.0,
  "paid": null,
  "linkToPay": null,
  "payBefore": null,
  "allowBill": 0,
  "orderCanceled": 0,
  "qrCodeLink": "https://cloud.shelter.ru/qrcoder/getqrcode.aspx?...",
  "reservationCurrency": null
}

Массив 2 — Бронирования:

{
  "id": 10931732,
  "arrivalDateTime": "2024-09-18T14:00:00",
  "departureDateTime": "2024-09-19T12:00:00",
  "roomTypeName": "Стандарт",
  "tariffName": "Базовый",
  "tariffDescription": null,
  "mealsIncluded": 0,
  "mealsType": null,
  "bedPlace": null,
  "numberOfGuests": 2,
  "price": 5000.0,
  "reservationCurrency": null
}

Массив 3 — Гости:

{
  "id": 13399971,
  "name": "Иванов Иван Иванович",
  "reservationID": 10931732,
  "age": null,
  "withoutBed": 0
}

Массив 4 — Доп. услуги: (пустой массив если не заказаны)

URL: POST https://cloud.shelter.ru/api/online/getOrder

Назначение: Получает данные созданного заказа для отображения страницы подтверждения.

Запрос

{
  "orderToken": "9bb11772-2843-4449-a766-84fa8c5c100b"
}

Ответ

Формат ответа аналогичен putOrder (те же 4 массива).