Процесс бронирования

Типичный процесс для модуля бронирования: получить токен, запросить список номеров на даты и количество гостей из поиска, применить выбранный тариф и купон, если он есть, пройти этап оплаты и записать бронирование в HMS с помощью BookingPushRQ. В этом руководстве каждый шаг разобран на реальных запросах и ответах.

1Вход/external/public/login

2Список номеров/external/online/roomType

3Купон · Пакетыcoupon/search · stock/packages

4Оплатаpayment/type/{type}

5Передачаchannel/booking

1. Получите токен#

Выполните вход один раз при запуске сервера или по истечении срока токена и сохраните токен вместе с ID отеля. Подробнее: Аутентификация.

2. Запросите список номеров#

Запросите список номеров со значениями из формы поиска гостя. Если с гостями едут дети, передайте их возраст: цена для детей рассчитывается по возрасту.

Терминал

curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "startDate=2026-08-18" -d "endDate=2026-08-20" \
  -d "adultCount=2" -d "childCount=1" -d "childAges[]=7" -d "language=en"

Что показывать на экране для каждого типа номера из ответа:

Поле	На экране
`name`, `images[]`, `detail`, `roomFeatures[]`	Карточка номера
`roomCount`	Сколько номеров осталось. 0 означает «нет в продаже» — причина в `roomRestrictionMessage`.
`accommodationTypes[].title`	Вариант питания (завтрак, полупансион…)
`accommodationTypes[].prices{}`	Варианты тарифа: стандартный и невозвратный

Ключи объекта prices имеют вид "<persons>-<1|0>". Суффикс 1 означает стандартный (возвратный) тариф, 0 — невозвратный; у невозвратного варианта есть nonRefundable: "[NR]". При цене за номер (priceType: 1) ключ — 1-1 / 1-0 независимо от количества гостей.

accommodationTypes[0].prices

{
    "2-1": {
        "total": 2,
        "title": 2,
        "nonRefundable": "",
        "price": "1930.00",
        "currency": "TRY",
        "id": "2/2",
        "prices": [
            {
                "price": "965.00",
                "tarih": "18.08.2026"
            },
            {
                "price": "965.00",
                "tarih": "19.08.2026"
            }
        ]
    },
    "2-0": {
        "total": 2,
        "title": 2,
        "nonRefundable": "[NR]",
        "price": "1737.00",
        "currency": "TRY",
        "id": "2-0/2",
        "prices": [
            {
                "price": "868.50",
                "tarih": "18.08.2026"
            },
            {
                "price": "868.50",
                "tarih": "19.08.2026"
            }
        ]
    }
}

3. Купоны и пакеты#

Если гость ввёл купон, проверьте его и примените скидку на своей стороне:

Терминал

curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"

Ответ · 200

{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

При change 0 значение rate — скидка в процентах (10%), при 1 — фиксированная сумма (10.00 в валюте отеля). Примените скидку к стоимости номера и передайте в бронировании итоговые суммы с учётом скидки.

Чтобы продавать дополнительные услуги, покажите список пакетов. Выбранные пакеты передаются в бронировании в extras[], а id пакета — в stockID. Итоговые суммы с учётом купонов и пакетов записываются в Total бронирования.

4. Этап оплаты#

Получите список типов оплаты, которые принимает отель, и действуйте в соответствии с выбором гостя. Для типа 10 (онлайн-оплата) запускается платёжная сессия и гость переходит к провайдеру; после оплаты он возвращается на ваш returnUrl. Все типы описаны в руководстве Процесс оплаты.

5. Передайте бронирование#

Когда результат оплаты известен, запишите бронирование в HMS. ID — уникальный код, который вы генерируете сами; сообщите этот же код гостю. ID типа номера и типа питания берутся из списка номеров.

Запрос

curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @booking.json

const booking = {
  hotelID: "1000",
  ID: orderNo,                      // ваш уникальный код бронирования
  type: "Book",
  createDateTime: new Date().toISOString(),
  checkinDate: "2026-08-18",
  checkoutDate: "2026-08-20",
  RoomStays: [{
    roomTypeID: "2", roomName: "Standard Room",
    ratePlanID: "2", ratePlanName: "Bed & Breakfast",
    type: "Book", NumberOfUnits: "1",
    checkinDate: "2026-08-18", checkoutDate: "2026-08-20",
    GuestCount: { adult: 2, child: 1 },
    PerDayRates: { currency: "TRY", PerDayRate: [
      { stayDate: "2026-08-18", baseRate: "965.00", hotelServiceFees: "0" },
      { stayDate: "2026-08-19", baseRate: "965.00", hotelServiceFees: "0" }
    ]},
    Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", currency: "TRY" }
  }],
  PrimaryGuests: [{ name: "Ayşe", surname: "Demir", PhoneNumber: "+905551112233", email: "[email protected]", CountryCode: "TR" }],
  ChildGuests: [{ age: 7 }],
  SpecialRequest: [{ text: "Late check-in, around 23:00." }],
  extras: [],
  Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", extraTotal: "0.00", currency: "TRY" }
};

const res = await fetch("https://test.hms.gen.tr/external/online/channel/booking", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.HMS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ BookingPushRQ: { Bookings: [booking] } })
});
const { BookingPushRS } = await res.json();
if (BookingPushRS.Error) throw new Error(BookingPushRS.Error);
const hmsId = BookingPushRS.BookingConfirmNumbers[0].HMS_ID;

$booking = [
    'hotelID'        => '1000',
    'ID'             => $orderNo,          // ваш уникальный код бронирования
    'type'           => 'Book',
    'createDateTime' => date('c'),
    'checkinDate'    => '2026-08-18',
    'checkoutDate'   => '2026-08-20',
    'RoomStays'      => [[
        'roomTypeID' => '2', 'roomName' => 'Standard Room',
        'ratePlanID' => '2', 'ratePlanName' => 'Bed & Breakfast',
        'type' => 'Book', 'NumberOfUnits' => '1',
        'checkinDate' => '2026-08-18', 'checkoutDate' => '2026-08-20',
        'GuestCount'  => ['adult' => 2, 'child' => 1],
        'PerDayRates' => ['currency' => 'TRY', 'PerDayRate' => [
            ['stayDate' => '2026-08-18', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
            ['stayDate' => '2026-08-19', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
        ]],
        'Total' => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'currency' => 'TRY'],
    ]],
    'PrimaryGuests'  => [['name' => 'Ayşe', 'surname' => 'Demir', 'PhoneNumber' => '+905551112233', 'email' => '[email protected]', 'CountryCode' => 'TR']],
    'ChildGuests'    => [['age' => 7]],
    'SpecialRequest' => [['text' => 'Late check-in, around 23:00.']],
    'extras'         => [],
    'Total'          => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'extraTotal' => '0.00', 'currency' => 'TRY'],
];

$ch = curl_init('https://test.hms.gen.tr/external/online/channel/booking');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('HMS_TOKEN'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['BookingPushRQ' => ['Bookings' => [$booking]]]),
]);
$rs = json_decode(curl_exec($ch), true)['BookingPushRS'];
if (isset($rs['Error'])) {
    throw new RuntimeException($rs['Error']);
}
$hmsId = $rs['BookingConfirmNumbers'][0]['HMS_ID'];

Ответ · 200

{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID — ID бронирования в HMS; сохраните его вместе со своей записью. Бронирование появится в панели управления в канале «Online», а HMS отправит гостю письмо с подтверждением в соответствии с настройками отеля.

Несколько номеров#

Если продано несколько номеров одного типа с одним и тем же типом питания, каждый номер — отдельный элемент RoomStays; NumberOfUnits равен "1" для первого, "2" для второго и так далее. Номера разных типов тоже передаются отдельными элементами. Total бронирования — это сумма по всем номерам и дополнительным услугам.

Изменение и отмена#

Отправьте бронирование повторно на тот же эндпоинт с тем же ID:

type: "Modify" — изменились даты, номера или данные гостей. Передайте бронирование целиком в текущем состоянии; HMS заменит им существующую запись.
type: "Cancel" — бронирование отменено. У номеров тоже указывается type: "Cancel".

Типичные ошибки#

Долгое кеширование списка номеров. Доступность и цены постоянно меняются; обновляйте список до того, как гость перейдёт к оплате.
Передача childCount, который отличается от длины childAges[]: сервер доверяет списку возрастов и молча меняет количество детей.
Передача собственных ID в roomTypeID / ratePlanID вместо ID из списка номеров: в ответ приходит Could not register.
Передача PaymentCard для типов оплаты, отличных от 9: данные карты без необходимости попадают в HMS.
Повтор после сетевой ошибки с другим ID: это создаёт дубликат бронирования. Повторяйте запрос с тем же ID.

Последнее обновление:: 21 сентября 2026 г.Нашли ошибку? Напишите нам