Đặt phòng

Phòng, gói ăn và giá mà khách đã chọn được gửi đến HMS theo cấu trúc BookingPushRQ. Cùng endpoint này cũng xử lý việc hủy và sửa đổi khi bạn gửi type là Cancel hoặc Modify. Xem hướng dẫn Luồng đặt phòng để biết toàn bộ quy trình.

POST/external/online/channel/bookingGửi đặt phòng (BookingPushRQ)

Gửi đặt phòng (BookingPushRQ)#

POST/external/online/channel/booking

Xác thực: Authorization: Bearer · Nội dung: application/json

Ghi một hoặc nhiều đặt phòng vào HMS. ID là mã đặt phòng duy nhất do phía bạn tạo; gửi Modify với cùng ID sẽ cập nhật bản ghi, gửi Cancel sẽ hủy bản ghi. Khi bán nhiều phòng cùng loại phòng và gói ăn, mỗi phòng là một mục RoomStays riêng với NumberOfUnits 1, 2, 3…

Với hình thức thanh toán thẻ tín dụng (9), thông tin thẻ được đặt trong PaymentCard; bỏ trường này với các hình thức thanh toán khác. Khi xử lý dữ liệu thẻ, bạn thuộc phạm vi áp dụng của PCI DSS.

Nội dung yêu cầu

BookingPushRQ.Bookings[]object[]bắt buộc
Danh sách đặt phòng. Thường chỉ có một mục.
hotelIDstringbắt buộc
ID khách sạn.
IDstringbắt buộc
Mã đặt phòng duy nhất trong hệ thống của bạn. Cũng được lưu làm số voucher.
typestringbắt buộc
Loại thao tác.
BookModifyCancel
createDateTimedatetime
Thời điểm tạo đặt phòng (ISO 8601).
checkinDate / checkoutDatedatebắt buộc
Ngày nhận phòng và trả phòng, YYYY-MM-DD.
RoomStays[]object[]bắt buộc
Các phòng đã bán.
roomTypeIDstringbắt buộc
items[].id từ danh sách phòng.
roomNamestring
Tên loại phòng (để tham khảo).
ratePlanIDstringbắt buộc
accommodationTypes[].id từ danh sách phòng.
ratePlanNamestring
Tên gói ăn (để tham khảo).
typestring
Loại thao tác cho phòng.
BookModifyCancel
NumberOfUnitsstringbắt buộc
Thứ tự các phòng cùng loại phòng/gói ăn: 1, 2, 3…
checkinDate / checkoutDatedatebắt buộc
Ngày nhận phòng và trả phòng của phòng.
GuestCountobjectbắt buộc
Số lượng adult và child.
PerDayRatesobject
currency và PerDayRate[]: stayDate, baseRate, hotelServiceFees.
Totalobjectbắt buộc
Tổng tiền phòng: amountAfterTaxes, amountOfTaxes, currency.
PaymentCardobject
Chỉ dùng cho hình thức thanh toán 9 (thẻ tín dụng). CardHolder{fullname, address, country, city}, cardNumber, expireDate (MMYY), cardCode, seriesCode (CVV).
PrimaryGuests[]object[]bắt buộc
Khách chính: name, surname, PhoneNumber, email, CountryCode.
ChildGuests[]object[]
Trẻ em. age là bắt buộc; name, surname, year, date, detail là tùy chọn.
SpecialRequest[]object[]
Ghi chú của khách và điều kiện hủy: text. Được nối vào phần ghi chú của đặt phòng.
extras[]object[]
Dịch vụ bổ sung/gói dịch vụ đã bán: name, note, person, piece, price, priceMode, priceTotal, stockID (id từ danh sách gói dịch vụ).
Totalobjectbắt buộc
Tổng cộng: amountAfterTaxes, amountOfTaxes, extraTotal, currency.

Phản hồi

200 Đối tượng BookingPushRS. Khi thành công có Success: true và ID đặt phòng trong HMS (HMS_ID); khi thất bại có thông báo Error và BookingConfirmNumbers[].Error[].

Phản hồi lỗi

  • 200 Error: No available data could be found. (01, nội dung trống hoặc không phân tích được) · Hotel registration not found on HMS. (02, khách sạn chưa liên kết với kênh trực tuyến) · Could not register. · Failed to parse information.
Yêu cầu
curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "BookingPushRQ": {
        "Bookings": [
            {
                "hotelID": "1000",
                "ID": "4811174883",
                "type": "Book",
                "createDateTime": "2026-08-01T08:32:11:293Z",
                "checkinDate": "2026-08-18",
                "checkoutDate": "2026-08-20",
                "RoomStays": [
                    {
                        "roomTypeID": "2",
                        "roomName": "Phòng Tiêu chuẩn",
                        "ratePlanID": "2",
                        "ratePlanName": "Bao gồm bữa sáng",
                        "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": "Nhận phòng muộn, khoảng 23:00."
                    }
                ],
                "extras": [
                    {
                        "name": "Bữa tối",
                        "note": "",
                        "person": 2,
                        "piece": 1,
                        "price": "400.00",
                        "priceMode": null,
                        "priceTotal": "400.00",
                        "stockID": 12
                    }
                ],
                "Total": {
                    "amountAfterTaxes": "2330.00",
                    "amountOfTaxes": "211.82",
                    "extraTotal": "400.00",
                    "currency": "TRY"
                }
            }
        ]
    }
}'
Phản hồi · 200
{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}
Phản hồi · 200 (lỗi)
{
    "BookingPushRS": {
        "Error": "Hotel registration not found on HMS.",
        "BookingConfirmNumbers": [
            {
                "bookingID": null,
                "bookingType": null,
                "confirmTime": 1755500000,
                "Error": [
                    {
                        "code": "02",
                        "text": "Hotel registration not found on HMS."
                    }
                ]
            }
        ]
    }
}
Cập nhật lần cuối: 21 tháng 9, 2026Phát hiện lỗi? Hãy cho chúng tôi biết