مسار الحجز

المسار المعتاد لمحرك الحجز: احصل على رمز مميز، واعرض الغرف للتواريخ وعدد النزلاء الذي بحث عنه النزيل، وطبّق السعر المختار وأي قسيمة خصم، وأكمل خطوة الدفع، ثم سجّل الحجز في 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هل وجدت خطأً؟ أخبرنا