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

URL: POST /OnlineWidget3/online/v3/getHotelData

Назначение: Возвращает параметры отеля, доступные валюты, языки, сервисы, тарифы и категории номеров. Вызывается один раз при инициализации виджета.

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "language": "ru",
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "params": {
      "minDateFrom": "2024-08-16T00:00:00",
      "maxDateTo": "2024-08-17T00:00:00",
      "defaultDateFrom": "2024-08-16T00:00:00",
      "defaultDateTo": "2024-08-17T00:00:00",
      "allowBeds": true,
      "onlyBedPlaces": false,
      "defaultNumberOfGuests": null,
      "minAgeOfChild": null,
      "maxAgeOfChild": null,
      "maxRoomCapacity": null,
      "allowUpsale": true,
      "disableAuth": false,
      "askOnlyFirstGuest": false,
      "defaultPhoneCode": "7"
    },
    "currencies": [
      { "code": "RUB", "name": "Рубль", "id": "" }
    ],
    "languages": [
      { "code": "ru", "name": "Русский", "id": "" }
    ],
    "hotels": [
      { "token": "Токен отеля", "name": "Название отеля", "id": "id отеля" }
    ],
    "analytics": {
      "google": { "analyticsCounter": null, "analyticsGoalCalendar": null, "..." : "..." },
      "yandex": { "metrikaCounter": null, "metrikaGoalCalendar": null, "..." : "..." }
    },
    "services": [
      {
        "id": "",
        "name": "Номера",
        "filters": [
          { "type": "days", "name": "По дням", "id": "" },
          { "type": "hours", "name": "По часам", "id": "" }
        ]
      }
    ],
    "tariffs": [
      { "id": 24809, "name": "Стандарт", "isPromotionGroup": false }
    ],
    "tariffOptions": [],
    "roomTypes": [
      { "id": 39453, "name": "Полулюкс" }
    ],
    "roomCategoryOptions": [
      { "id": 1, "name": "Кондиционер", "url": "Content/Gallery/RoomOptions/cond.svg" }
    ]
  }
}

Описание полей ответа

params — Параметры виджета:

currencies — массив доступных валют (code, name, id)

languages — массив доступных языков (code, name, id)

hotels — массив отелей, подключённых к виджету (token, name, id)

analytics — настройки Google Analytics и Яндекс.Метрики

services — типы сервисов (Номера, Конференц-зал, SPA и т.д.) с фильтрами бронирования (days, hours)

tariffs — массив тарифов (id, name, isPromotionGroup)

roomTypes — массив категорий номеров (id, name)

roomCategoryOptions — массив опций категорий (id, name, url)

URL: POST /OnlineWidget3/online/v3/getVariants

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

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "language": "ru",
  "currency": "RUB",
  "dateFrom": "2024-09-02",
  "dateTo": "2024-09-12",
  "rooms": [
    { "adults": 2, "kids": 2, "kidsAges": [5, 3] }
  ],
  "serviceId": "3",
  "bookingType": "days",
  "roomsOnly": false,
  "promocode": null,
  "tariffId": null,
  "isPromotionGroup": null,
  "tariffOptionsIDs": [],
  "roomCategoryOptionsIDs": [],
  "checkInTime": null,
  "hours": null,
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "roomTypes": [
      {
        "id": 39329,
        "name": "Люкс (дабл)",
        "description": null,
        "availableRooms": 12,
        "availableBeds": 48,
        "roomArea": 32,
        "mainBeds": 4,
        "extraBeds": 2,
        "withoutBeds": false,
        "allowConnectBeds": false
      }
    ],
    "roomCategoryOptions": [
      { "roomCategoryId": 39332, "roomCategoryOptionId": 1 }
    ],
    "tariffs": [
      { "id": 24809, "name": "Стандарт", "isPromotion": false, "description": null, "image": null }
    ],
    "tariffOptions": [
      { "tariffID": 39332, "isPromotion": false, "tariffOptionID": 1 }
    ],
    "upsaleOptions": [],
    "variants": [
      {
        "roomCategoryId": 39332,
        "tariffId": 24854,
        "tariffOrder": null,
        "promotionId": 24854,
        "accmdId": 65721,
        "accmdName": "Основное",
        "currency": "RUB",
        "price": 3000,
        "bedPlace": true,
        "agesOfChildrenWithBeds": [7, 5, 3],
        "agesOfChildrenWithoutBeds": [7, 5, 3],
        "totalDiscountPercent": 0,
        "promocodeDiscountPercent": 0,
        "promotionDiscountPercent": 0,
        "priceWithoutDiscount": 3000,
        "prepayment": 0
      }
    ],
    "roomTypeImages": [
      {
        "roomCategoryId": 39453,
        "url": "Content/Gallery/RoomTypes/no-image-grey.jpg",
        "urlLarge": "Content/Gallery/RoomTypes/no-image-grey.jpg",
        "isVideo": false
      }
    ]
  }
}

Описание полей ответа

roomTypes — категории номеров:

variants — варианты бронирования:

roomTypeImages — изображения категорий (roomCategoryId, url, urlLarge, isVideo)

URL: POST /OnlineWidget3/online/v3/getExtraServices

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

Запрос

{
  "token": "EAAB810C-EE10-4ED9-BA1E-BC5112BB6AB9",
  "language": "ru",
  "currency": "RUB",
  "roomCategoryIDs": [39332],
  "dateFrom": "2024-09-18",
  "dateTo": "2024-09-19",
  "amountOfAdults": 1,
  "amountOfChildren": 0,
  "ageOfChildren": [],
  "numberOfRooms": 1,
  "tariffsIDs": [24854],
  "promotionsIDs": [],
  "bedPlace": "0",
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "roomTypes": [],
    "roomCategoryOptions": [],
    "meals": [],
    "extraServiceGroups": [],
    "extraServices": []
  }
}

URL: POST /OnlineWidget3/online/v3/getPaymentOptions

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

Запрос

{
  "token": "EAAB810C-EE10-4ED9-BA1E-BC5112BB6AB9",
  "language": "ru",
  "currency": "RUB",
  "roomCategoryIDs": [39332],
  "dateFrom": "2024-09-18",
  "dateTo": "2024-09-19",
  "amountOfAdults": 1,
  "amountOfChildren": 0,
  "ageOfChildren": [],
  "numberOfRooms": 1,
  "tariffsIDs": [24854],
  "promotionsIDs": [],
  "bedPlace": "0",
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "agreeText": "Пользовательское соглашение",
    "agreeUrl": "https://example.com/agreement",
    "openPaymentInNewTab": true,
    "paymentOptions": [
      {
        "id": 1,
        "name": "Оплата картой",
        "description": "Оплата картой Visa, MasterCard или МИР",
        "image": "Content/Gallery/PaymentTypes/card.svg",
        "paymentKind": 24
      },
      {
        "id": 4,
        "name": "Перевод на расчётный счёт",
        "description": "Получить счёт на оплату через клиент-банк или по QR-коду",
        "image": "Content/Gallery/PaymentTypes/beznal.svg",
        "paymentKind": null
      },
      {
        "id": 2,
        "name": "Оплата в отеле",
        "description": "Оплата при заезде наличными или картой",
        "image": "Content/Gallery/PaymentTypes/hotel-payment.svg",
        "paymentKind": null
      }
    ]
  }
}

URL: POST /OnlineWidget3/online/v3/putOrder

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

Запрос

{
  "token": "EAAB810C-EE10-4ED9-BA1E-BC5112BB6AB9",
  "language": "ru",
  "source": "hotel-website.ru",
  "paymentMethodID": 2,
  "comment": "Комментарий к заказу",
  "customer": {
    "email": "guest@example.com",
    "phone": "+79000000000",
    "surname": "Иванов",
    "name": "Иван",
    "secondName": "Иванович"
  },
  "reservations": [
    {
      "dateFrom": "2024-09-18",
      "dateTo": "2024-09-19",
      "roomCategoryId": 39469,
      "tariffId": 24853,
      "isPromotion": 0,
      "promocode": null,
      "guestsCount": 1,
      "bedPlace": 0,
      "currency": "RUB",
      "price": 2000,
      "totalDiscountPercent": 0,
      "promocodeDiscountPercent": 0,
      "promotionDiscountPercent": 0,
      "priceWithoutDiscount": 2000,
      "priceRub": 2000,
      "prepaymentRub": 0,
      "prepaymentCurrency": 0,
      "guests": [
        {
          "surname": "Иванов",
          "name": "Иван",
          "secondName": "Иванович",
          "email": "guest@example.com",
          "phone": "+79000000000",
          "withoutBed": false
        }
      ]
    }
  ],
  "extraServices": [
    { "id": 18188, "count": 1, "price": 1500, "priceRub": 1500, "prepaymentRub": 0, "prepaymentCurrency": 0 }
  ],
  "mealId": 87963,
  "mealPriceRub": 500,
  "mealPrepaymentRub": 0,
  "mealPrepaymentCurrency": 0,
  "userToken": ""
}

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

customer:

reservations[]:

guests[]:

extraServices[]:

Ответ

{
  "success": true,
  "data": {
    "paymentLink": null,
    "orderToken": "93744f45-e4f7-4271-8fb0-1d907e463b1d",
    "errorCreationPaymentLink": null,
    "bookingCode": 5138,
    "paymentSystemId": 0
  }
}

Как заполняется paymentSystemId и paymentLink:

• Поля заполняются только при онлайн-оплате — когда paymentMethodID соответствует способу оплаты с переходом на платёжный шлюз (банковская карта, СБП, QR и т.п., из getPaymentOptions).
• paymentSystemId — это внутренний ID платёжной системы, настроенной для отеля (совпадает со значениями из инструкций по платёжным системам: 2 — Hotel cash, 11 — Uniteller, 18 — Сбербанк, 20 — МИР и т.д.).
• Если выбрана оплата в отеле (paymentMethodID = 2) или другой способ без онлайн-платежа, ссылка на оплату не создаётся: в ответе придут paymentLink: null, paymentSystemId: 0, errorCreationPaymentLink: null — это нормальное поведение, а не ошибка.
• Если онлайн-оплата запрошена, но платёжная система для отеля не настроена или не удалось создать ссылку, paymentLink будет null, а причина — в errorCreationPaymentLink.

URL: POST /OnlineWidget3/online/v3/getOrder

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

Запрос

{
  "orderToken": "93744f45-e4f7-4271-8fb0-1d907e463b1d",
  "language": "ru",
  "currency": "RUB",
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "orderInfo": {
      "hotelId": 5655,
      "hotelName": "Родник Алтая",
      "hotelAddress": "659900, Алтайский, Белокуриха",
      "hotelEmail": "hotel@example.com",
      "hotelPhones": "88005500880",
      "hotelImage": "Content/Images/5655_Hotels_x450.jpg",
      "bookingCode": 5138,
      "createDate": "2024-09-03T09:35:50.35",
      "customerName": "Иванов Иван Иванович",
      "customerPhone": "+79000000000",
      "customerEmail": "guest@example.com",
      "comment": "Комментарий",
      "paymentMethodName": "Оплата в отеле",
      "accommodationPrice": 2000.0,
      "toPay": 4800.0,
      "prepayment": 4800.0,
      "paid": null,
      "linkToPay": null,
      "payBefore": null,
      "allowBill": 0,
      "orderCanceled": 0,
      "qrCodeLink": null,
      "reservationCurrency": "RUB"
    },
    "reservationTypes": [
      {
        "id": 7776624,
        "arrivalDateTime": "2024-09-18T14:00:00",
        "departureDateTime": "2024-09-19T12:00:00",
        "roomTypeName": "Стандарт",
        "tariffName": "Базовый",
        "tariffDescription": null,
        "mealsIncluded": 0,
        "mealsType": null,
        "bedPlace": null,
        "numberOfGuests": 1,
        "price": 2000.0,
        "reservationCurrency": "RUB"
      }
    ],
    "guests": [
      {
        "id": 363089,
        "name": "Иванов Иван Иванович",
        "reservationID": 7776624,
        "age": null,
        "withoutBed": 0
      }
    ],
    "extraServices": [
      {
        "id": 7281232,
        "serviceName": "Сауна",
        "reservationID": 7776624,
        "quantity": 1,
        "price": 1500.0
      }
    ]
  }
}

Описание полей ответа

orderInfo:

reservationTypes[]:

guests[]: id, name, reservationID, age, withoutBed

extraServices[]: id, serviceName, reservationID, quantity, price

URL: POST /OnlineWidget3/online/v3/annulOrder

Назначение: Отмена (аннуляция) существующего заказа.

Запрос

{
  "orderToken": "6c216700-28a8-480a-a4a0-9e3a253bce14",
  "token": "EAAB810C-EE10-4ED9-BA1E-BC5112BB6AB9",
  "annulDescription": "Причина отмены"
}

Пример запроса (cURL)

curl --request POST \
  --url https://cloud.shelter.ru/OnlineWidget3/online/v3/annulOrder \
  --header 'content-type: application/json' \
  --data '{
    "orderToken": "6c216700-28a8-480a-a4a0-9e3a253bce14",
    "token": "EAAB810C-EE10-4ED9-BA1E-BC5112BB6AB9",
    "annulDescription": "Причина отмены"
  }'

Ответ (успех)

{
  "success": true,
  "data": null,
  "errors": null,
  "notify": null
}

Ответ (ошибка)

{
  "success": false,
  "data": null,
  "errors": [
    { "code": "500", "message": "Не удалось аннулировать заказ" }
  ],
  "notify": null
}

URL: POST /OnlineWidget3/online/v3/getAvailableDates

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

Не учитывает ограничения, которые могут быть указаны для бронирования конкретной даты.

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "currency": "RUB",
  "dateFrom": "2024-08-27",
  "dateTo": "2024-09-12",
  "language": "ru",
  "roomCategoryId": 39329,
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": [
    { "roomCategoryId": 39329, "date": "2024-09-18", "price": 5000.0 },
    { "roomCategoryId": 39329, "date": "2024-09-19", "price": 5000.0 }
  ]
}

URL: POST /OnlineWidget3/online/v3/checkPromoCode

Назначение: Проверяет корректность промокода.

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "promocode": "SUMMER2024"
}

Ответ

{
  "success": true,
  "data": {
    "correct": true
  }
}

URL: POST /OnlineWidget3/online/v3/login

Назначение: Авторизация пользователя. Возвращает токен пользователя для передачи в последующих запросах.

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "login": "user@example.com",
  "password": "password123"
}

Ответ

{
  "success": true,
  "data": {
    "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A"
  }
}

URL: POST /OnlineWidget3/online/v3/setRequest

Назначение: Отправка заявки на бронирование (запрос без создания заказа). Заявка отправляется на почту отеля, указанную в поле «Email для заявок:» на вкладке «Онлайн для сайта v2.0».

Запрос

{
  "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A",
  "language": "ru",
  "currency": "RUB",
  "comment": "Комментарий к заявке",
  "contacts": "Телефон: 8-800-200-00-00",
  "dateFrom": "2024-08-31",
  "dateTo": "2024-09-01",
  "userToken": ""
}

Ответ

{
  "success": true,
  "data": {
    "token": "DCAE50E8-8795-4490-BC58-0C419B46F25A"
  }
}