جریان رزرو

جریان معمول یک موتور رزرو: توکن بگیرید، اتاق‌ها را برای تاریخ‌ها و تعداد نفراتی که مهمان جست‌وجو کرده است فهرست کنید، نرخ انتخاب‌شده و کوپن احتمالی را اعمال کنید، مرحله پرداخت را کامل کنید و رزرو را با BookingPushRQ در HMS ثبت کنید. این راهنما هر مرحله را با درخواست‌ها و پاسخ‌های واقعی شرح می‌دهد.

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,                      // your unique booking code
  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,          // your unique booking code
    '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اشتباهی دیدید؟ به ما اطلاع دهید