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

Типовий процес для модуля бронювання: отримати токен, отримати список номерів на дати й кількість гостей, які шукав гість, застосувати вибраний тариф і купон (якщо є), пройти крок оплати та записати бронювання в HMS за допомогою BookingPushRQ. У цьому посібнику кожен крок розібрано на реальних запитах і відповідях.

1Вхід/external/public/login

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

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

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

5Передаванняchannel/booking

1. Отримайте токен#

Виконуйте вхід один раз — під час запуску сервера або коли строк дії токена закінчується — і зберігайте токен разом з ідентифікатором готелю. Докладніше: Автентифікація.

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 — унікальний код, який генеруєте ви; повідомте цей самий код гостеві. Ідентифікатори типу номера й типу харчування беруться зі списку номерів.

Запит

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 — ідентифікатор бронювання в HMS; збережіть його разом із власним записом. Бронювання з’являється в панелі в каналі «Online», а HMS надсилає гостеві лист-підтвердження відповідно до налаштувань готелю.

Кілька номерів#

Якщо продано кілька номерів одного типу з тим самим типом харчування, кожен номер є окремим елементом RoomStays; NumberOfUnits дорівнює "1" для першого, "2" для другого і так далі. Різні типи номерів теж є окремими елементами. Total бронювання — це сума за всі номери й додаткові послуги.

Зміни й скасування#

Надішліть бронювання повторно на той самий ендпоінт із тим самим ID:

type: "Modify" — змінилися дати, номери або дані гостя. Надішліть повне бронювання в його поточному стані; HMS замінить ним наявний запис.
type: "Cancel" — бронювання скасовано. Номери також містять type: "Cancel".

Типові помилки#

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

Останнє оновлення: 21 вересня 2026 р.Знайшли помилку? Повідомте нам