API виджета бронирования v1 (hmsExternalPrices)

URL: GET /externalPrices/jsTariffs.aspx

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

Параметры запроса

Пример запроса

GET /externalPrices/jsTariffs.aspx?token=<токен>

Формат ответа

Ответ всегда в формате JavaScript и содержит три переменных:

fd_tariffs — массив тарифов:

fd_tariffs = [
  {
    id: 123,                    // ID тарифа
    name: 'Стандартный',        // Название
    code: 'STANDARD',          // Код тарифа
    comment: 'Описание',       // Комментарий (может отсутствовать)
    hours4Prepayment: 72,      // Часов на предоплату (может отсутствовать)
    prepayment: 20,            // Размер предоплаты (может отсутствовать)
    prepaymentType: '%',       // Тип предоплаты (может отсутствовать), см. ниже
    costs: [                   // Массив цен
      {
        cost: 3500.00,         // Цена
        from: new Date(2025, 0, 1),   // Дата начала (формат JavaScript: месяц 0-индексирован, 0=Январь)
        to: new Date(2025, 11, 31),   // Дата окончания (11=Декабрь)
        roomId: 45,            // ID категории номера
        roomCode: 'DBL',       // Код категории (может отсутствовать)
        boardingId: 5,         // ID типа питания (может отсутствовать)
        boardingCode: 'HB',    // Код типа питания (может отсутствовать)
        ageFrom: 0,            // Возраст от (может отсутствовать = для всех)
        ageTo: 12,             // Возраст до (может отсутствовать = для всех)
        extraBed: true,        // true = цена для доп. места (может отсутствовать)
        type: 'perPerson',     // Тип цены (см. ниже)
        guests: 2,             // Кол-во гостей в номере (может отсутствовать = для всех)
        guestSerialNumber: 1,  // Порядковый номер гостя (может отсутствовать = для всех)
        weeks: '12345',        // Дни недели: 1=Пн...7=Вс (может отсутствовать = все)
        minLength: 3,          // Мин. продолжительность (может отсутствовать)
        maxLength: 7,          // Макс. продолжительность (может отсутствовать)
        period: 'night'        // Период расчёта цены (см. ниже)
      }
    ]
  }
];

Типы цены (type):

• perPerson — за человека
• perRoom — за номер
• perBed — за койко-место
• perMotherAndChild — за мать и дитя

Период (period):

• night — за ночь
• day — за день (сутки)
• arrival — за заезд

Тип предоплаты (prepaymentType):

• % — процент от стоимости проживания. Значение prepayment указывает процент (например, 20 = 20%)
• fix — фиксированная сумма. Значение prepayment указывает сумму в валюте отеля
• 24hours — предоплата за первые сутки проживания. Значение prepayment указывает количество суток, за которые взимается предоплата (например, 2 = предоплата за 2 первых суток)

fd_rooms — массив категорий номеров:

fd_rooms = [
  {
    id: 45,                    // ID категории
    name: 'Двухместный',       // Название
    code: 'DBL',               // Код
    allowByBeds: true,         // Бронирование по койко-местам (может отсутствовать)
    allowByRooms: true,        // Бронирование номера целиком (может отсутствовать)
    building: 'Корпус А',     // Корпус (может отсутствовать)
    comment: 'Вид на море',   // Комментарий (может отсутствовать)
    images: [                  // Изображения (может отсутствовать)
      { path: 'http://...', pathSmall: 'http://...' }
    ],
    mainBeds: 2,               // Основных мест
    extraBeds: 1               // Дополнительных мест
  }
];

fd_boardings — массив типов питания:

fd_boardings = [
  {
    id: 5,                     // ID типа питания
    name: 'Полупансион',       // Название
    code: 'HB'                // Код
  }
];

Если нет типов питания, возвращается fd_boardings = undefined;

URL: GET /externalPrices/jsAvailables.aspx

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

Параметры запроса

Пример запроса

GET /externalPrices/jsAvailables.aspx?token=e4922afa-...&dateFrom=2025-03-01&dateTo=2025-03-31&json

Валидация

• dateFrom автоматически устанавливается не раньше сегодня
• dateFrom <= dateTo
• Диапазон не более 366 дней
• Токен должен быть валидным (hotelId > 0)

Формат ответа

JavaScript-режим:

fd_periodAvailables = [
  { dateFrom: '2025-03-01', dateTo: '2025-03-15', onlyByRequest: false },
  { dateFrom: '2025-03-20', dateTo: '2025-03-31', onlyByRequest: true }
];

JSON-режим:

[
  { "dateFrom": "2025-03-01", "dateTo": "2025-03-15", "onlyByRequest": false },
  { "dateFrom": "2025-03-20", "dateTo": "2025-03-31", "onlyByRequest": true }
]

URL: GET /externalPrices/jsSearchJoin.aspx

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

Параметры запроса

Формат параметра filter

[{token:<токен>}]

С фильтрацией по тарифу и категории:

[{token:e4922afa-...,tariff:STANDARD,room:DBL}]

С фильтрацией по ID:

[{token:e4922afa-...,tariffId:123,roomId:45}]

Несколько отелей:

[{token:token1},{token:token2}]

Пример запроса

GET /externalPrices/jsSearchJoin.aspx?arrival=2025-03-01&depart=2025-03-05&adults=2&childs=1&ages=8&filter=[{token:<токен>}]&json

Валидация

• departure >= arrival
• guestsCount (adults + childs) > 0
• Диапазон дат не более 180 дней (6 месяцев)
• Если childs > 0, количество элементов в ages должно совпадать с childs
• filter обязателен, в нём должен быть хотя бы один элемент с валидным токеном

Формат ответа (JavaScript-режим)

fd_avails = [
  {
    hotelId: 100,
    roomId: 45,
    byBedsVariant: false,
    tariffId: 123,
    parentTariffId: 0,
    boardingId: 5,
    count: 3,                  // Кол-во доступных номеров (undefined = по запросу)
    price: 10500.00,
    details: { ... },          // Детализация по дням
    room: { ... },             // Информация о категории
    tariff: { ... },           // Информация о тарифе
    boarding: { ... },         // Информация о питании
    hotel: { ... }             // Информация об отеле
  }
];

Формат ответа (JSON-режим)

В JSON-режиме структура отличается — используется объект AvailablesData с вложенной моделью:

[
  {
    "hotelId": 100,
    "roomId": 45,
    "byBedsVariant": false,
    "tariffId": 123,
    "parentTariffId": 0,
    "boardingId": 5,
    "count": 3,
    "price": 10500.00,
    "details": [ ... ],
    "room": { ... },
    "tariff": { ... },
    "boarding": { ... },
    "hotel": { ... }
  }
]

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

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

URL: GET /externalPrices/jsAlternatives.aspx

Назначение: Если на запрошенные даты нет доступных вариантов, этот метод вернёт ближайшие альтернативные периоды.

Параметры запроса

Формат ответа

fd_alternatives = [
  { arrival: '2025-03-10', departure: '2025-03-14' },
  { arrival: '2025-03-20', departure: '2025-03-24' }
];

Если альтернатив не найдено:

fd_alternatives = [];

URL: GET /externalPrices/jsExtrtaServices.aspx

Примечание: Опечатка в названии Extrta (вместо Extra) присутствует в исходном коде и сохранена для совместимости.

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

Параметры запроса

Формат ответа

fd_extraservices = [
  {
    group: 'Трансфер',
    services: [
      { id: 201, name: 'Трансфер из аэропорта', desciption: 'В одну сторону', cost: 2500.00 },
      { id: 202, name: 'Трансфер в аэропорт', desciption: 'В одну сторону', cost: 2500.00 }
    ]
  },
  {
    group: 'Услуги номера',
    services: [
      { id: 101, name: 'Поздний выезд', desciption: 'До 18:00', cost: 1500.00 }
    ]
  }
];

Примечание: Поле desciption (вместо description) — опечатка в исходном коде, сохранена для совместимости.

URL: POST /externalPrices/CreateOrder.aspx

Назначение: Создание нового заказа с одним или несколькими бронированиями.

Параметры запроса (POST form data)

Формат параметра data

[
  {
    "arrival": "2025-03-01",
    "departure": "2025-03-05",
    "timeArrival": "14:30",
    "timeDeparture": "11:00",
    "adults": 2,
    "children": 1,
    "ages": [8],
    "comment": "Комментарий от гостя",
    "roomId": 45,
    "byBedsVariant": false,
    "count": 1,
    "amount": 10500.00,
    "payed": 0,
    "paymentType": 0,
    "boardingId": 5,
    "tariffId": 123,
    "contactName": "Иванов Иван Иванович",
    "contactPhone": "+7-999-123-4567",
    "contactEmail": "ivanov@example.com",
    "source": "hotel-website.ru",
    "guests": [
      {
        "surname": "Иванов",
        "name": "Иван",
        "patronymic": "Иванович",
        "phone": "+7-999-123-4567",
        "email": "ivanov@example.com",
        "age": 35,
        "birthdate": "1990-01-15"
      },
      {
        "surname": "Иванова",
        "name": "Мария",
        "patronymic": "Петровна",
        "phone": "",
        "email": "",
        "age": 32
      },
      {
        "surname": "Иванов",
        "name": "Петя",
        "age": 8
      }
    ],
    "extraservices": [
      { "id": 201, "count": 1, "date": "2025-03-01" }
    ]
  }
]

Описание полей бронирования (Reservation)

*Хотя бы одно из полей contactName/contactPhone/contactEmail должно быть заполнено.

Описание полей гостя (Guest)

*Для первого (основного) гостя обязательны surname и name.

Описание полей доп. услуги (ExtraService)

Валидация

• data и token обязательны
• Массив бронирований не может быть пустым
• Для каждого бронирования:
  • amount > 0
  • departure > arrival, departure >= сегодня
  • Минимум один гость с контактными данными
  • Время (если указано) в формате HH:mm (00:00–23:59)
  • roomId должен принадлежать отелю, определённому по токену

Формат ответа

Успех:

{
  "success": true,
  "orderId": 12345,
  "invoiceNumber": "INV-001",
  "paygateError": "",
  "apiKey": "payment-api-key",
  "guestCode": "a1b2c3d4-...",
  "error": ""
}

Ошибка:

{
  "success": false,
  "orderId": 0,
  "invoiceNumber": "",
  "paygateError": "",
  "apiKey": "",
  "guestCode": "",
  "error": "описание ошибки"
}

Возможные ошибки

Интеграция с платёжными системами

После успешного создания заказа, в зависимости от настроек отеля, автоматически создаётся платёжный документ:

• OrderPaygate — создаётся счёт, возвращаются invoiceNumber и apiKey
• Uniteller — создаётся ссылка на оплату

Если для отеля включен код гостя, в ответе также будет guestCode.

URL: POST /externalPrices/AnnulateOrder.aspx

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

Параметры запроса (POST form data)

Формат ответа

Успех:

{
  "success": true,
  "error": "",
  "orderId": 0
}

Ошибка:

{
  "success": false,
  "error": "orderId not found",
  "orderId": 0
}

Возможные ошибки

URL: GET /externalPrices/jsOrderStatus.aspx

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

Параметры запроса

Формат ответа

fd_order = 1;

Коды статусов

URL: GET /externalPrices/CheckPayment.aspx

Назначение: Детализированная проверка статуса оплаты заказа.

Параметры запроса

Формат ответа

Успех:

{
  "status": 200,
  "errorDescription": "",
  "payStatus": "PAID"
}

Ошибка (параметры не переданы):

{
  "status": 500,
  "errorDescription": "Не переданы обязательные параметры запроса",
  "payStatus": ""
}