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

Типичният процес за резервационна система: получавате токен, извеждате стаите за датите и броя гости, които гостът е търсил, прилагате избраната цена и евентуален купон, завършвате стъпката на плащане и записвате резервацията в 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 г.Открихте грешка? Пишете ни