ขั้นตอนการจอง
ขั้นตอนทั่วไปของระบบจองห้องพักมีดังนี้ รับโทเค็น แสดงรายการห้องพักตามวันที่และจำนวนผู้เข้าพักที่ผู้เข้าพักค้นหา ใช้ราคาที่เลือกและคูปอง (ถ้ามี) ทำขั้นตอนการชำระเงินให้เสร็จ แล้วบันทึกการจองลงใน HMS ด้วย BookingPushRQ คู่มือนี้อธิบายแต่ละขั้นตอนพร้อมคำขอและการตอบกลับจริง
/external/public/login/external/online/roomTypecoupon/search · stock/packagespayment/type/{type}channel/booking1. รับโทเค็น#
เข้าสู่ระบบหนึ่งครั้งเมื่อเซิร์ฟเวอร์เริ่มทำงานหรือเมื่อโทเค็นหมดอายุ และจัดเก็บโทเค็นไว้คู่กับ 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 ไม่ว่าจะมีผู้เข้าพักกี่คน
{
"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"{
"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.jsonconst 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'];{
"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เดิม