ขั้นตอนการจอง

ขั้นตอนทั่วไปของระบบจองห้องพักมีดังนี้ รับโทเค็น แสดงรายการห้องพักตามวันที่และจำนวนผู้เข้าพักที่ผู้เข้าพักค้นหา ใช้ราคาที่เลือกและคูปอง (ถ้ามี) ทำขั้นตอนการชำระเงินให้เสร็จ แล้วบันทึกการจองลงใน 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
การตอบกลับ · 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 เดิม