2.3.2 订单创建

约 1258 字大约 4 分钟

2025-04-24

提示

必须。
klook目前单间订单最多支持8间房,如果接入方不支持单个订单多间房,请告知klook每张订单最多支持的房间数是多少,klook可以配置单间订单房间数对应的拆单系数
1. 接入方级别
2. 酒店级别
下单接口只有在超时的情况下,会有重试机制,接入方需要保证下单接口幂等性,即同一订单号的下单请求,如果接入方已经处理过了,则不需要重复处理，只需要返回klook订单对应数据即可

URL

接入方自行定义并提供给klook

入参

接口请求参数

字段	类型	是否必须	说明
`hotelId`	`String`	true	供应商酒店 id 1：部分托管供应商使用的是 klook 酒店为主，则此处使用 klook 酒店 id参考 `idType`
`hotelName`	`String`	false	酒店名称
`roomId`	`String`	true	供应商房型 id 1：部分托管供应商使用的是 klook 酒店为主，则此处使用 klook 酒店 id 参考 `idType`
`roomName`	`String`	false	房型名称
`ratePlanId`	`String`	true	Rateplan id 1：部分托管供应商使用的是 klook 酒店为主，则此处使用 klook 酒店 id 参考 `idType`
`ratePlanName`	`String`	false	ratePlan 名称
`orderCode`	`String`	true	klook 订单号全局唯一
`checkIn`	`String`	true	入住时间
`checkOut`	`String`	true	离店时间
`contact`	`Contact`	true	联系人信息
`specialRequest`	`String`	false	特殊要求
`occupancy`	`Occupancy`	true	房间入住信息单间入住信息
`rooms`	`List<Room>`	true	入住信息 list.size = room size .`当单次下单多间房时,入住人信息数量是可选的,最低是1位入住人,当客户只填了1位入住人信息时,那么每间房入住信息时相同的`
`price`	`Price`	true	价格信息
`payments`	`Payments`	false	支付方式

`Room`

字段	类型	是否必须	说明
`guests`	`list<Guest>`	true	入住人信息

`Guest`

字段	类型	是否必须	说明
`firstName`	`String`	true
`lastName`	`String`	true

`Occupancy`

字段	类型	是否必须	说明
`adultCount`	`Integer`	true
`childCount`	`Integer`	true
`childrenAges`	`list<integer>`	false	当儿童数不为 0 时

`Price`

字段	类型	是否必须	说明
`totalPrice`	`TotalPrice`	true	多房多晚总价
`perRoomDailyPrices`	`List<PerRoomDailyPrice>`	true	单房多晚价格明细
`other`	`Other`	false	其他

`TotalPrice`

字段	类型	是否必须	说明
`amountBeforeTax`	`String`	false	税前价
`amountAfterTax`	`String`	true	税后价如果有佣金，佣金会被扣除（可配置，默认扣除佣金）如果有折扣，折扣会被扣除
`currency`	`String`	true	币种

`PerRoomDailyPrice`

字段	类型	是否必须	说明
`amountBeforeTax`	`String`	false	税前价
`amountAfterTax`	`String`	true	税后价
`currency`	`String`	true	币种
`date`	`String`	true	日期 `YYYY-MM-DD`

`Other`

字段	类型	是否必须	说明
`promotion`	`Promotion`	false	促销

`Promotion`

字段	类型	是否必须	说明
`discount`	`String`	false	折扣金额
`desc`	`String`	false	促销描述
`currency`	`String`	true	币种

`Payments`

字段	类型	是否必须	说明
`payCard`	`PayCard`	false	支付卡,非必须,只有商户开启了vcc才有

`PayCard`

字段	类型	是否必须	说明
`cardType`	`String`	true	卡类型只有 MC
`number`	`String`	true	卡号
`securityCode`	`String`	true	安全码
`expirationYear`	`String`	true	过期时间年 22
`expirationMonth`	`String`	true	过期时间月 08
`currency`	`String`	true	币种
`amount`	`String`	true	金额单位：元保留最多 2 位小数

`Contact` 说明

字段	类型	是否必须	说明
`firstName`	`String`	true
`lastName`	`String`	true
`email`	`String`	true	邮箱
`phone`	`String`	true	电话

入参示例

示例

{
    "base": {
        "requestAgent": "KLOOK",
        "openApiSign": "301e4cfefbc376c4f4c4dac8b096efcdee47810c2a3627b29b2d3a66b8ae04af27f4ff38c4a8d40dff48f6729fe0d7959fdd90f1848f25c595b574872b8ec69a",
        "requestId": "xxxxx111bbbbbcccc",
        "requestTime": "2025-11-28T12:06:15.890+08:00"
    },
    "requestData": {
        "hotelId": " ",
        "hotelName": "",
        "roomId": " ",
        "roomName": "",
        "ratePlanId": " ",
        "ratePlanName": "",
        "orderCode": " ",
        "checkIn": " ",
        "checkOut": " ",
        "contact": {
            "firstName": " ",
            "lastName": " ",
            "email": " ",
            "phone": " "
        },
        "specialRequest": " ",
        "occupancy": {
            "adultCount": 0,
            "childCount": 0,
            "childrenAges": [
                0
            ]
        },
        "rooms": [
            {
                "guests": [
                    {
                        "firstName": " ",
                        "lastName": " "
                    }
                ]
            },
          {
              "guests": [
                  {
                    "firstName": " ",
                    "lastName": " "
                  }
            ]
          }
        ],
        "price": {
            "totalPrice": {
                "amountBeforeTax": "1",
                "amountAfterTax": "106",
                "currency": ""
            },
            "perRoomDailyPrices": [
                {
                    "date": "2025-10-01",
                    "amountBeforeTax": "21.22",
                    "amountAfterTax": "25",
                    "currency": ""
                },
                {
                  "date": "2025-10-02",
                  "amountBeforeTax": "23.22",
                  "amountAfterTax": "28",
                  "currency": ""
                }
            ],
            "other": {
                "promotion": {
                    "discount": "25.28",
                    "currency": "",
                    "desc": "促销描述"
                }
            }
        },
        "payments": {
            "payCard": {
                "cardType": "",
                "number": "",
                "securityCode": "",
                "expirationYear": "",
                "expirationMonth": "",
                "currency": "",
                "amount": ""
            }
        }
    }
}

Curl示例说明

curl --location 'https://www.test.dddd/test/booking' \
--header 'Content-Type: application/json' \
--data-raw '{
    "base": {
        "requestAgent": "KLOOK",
        "openApiSign": "301e4cfefbc376c4f4c4dac8b096efcdee47810c2a3627b29b2d3a66b8ae04af27f4ff38c4a8d40dff48f67",
        "requestId": "747BAA04B9B642C08E1C2FAD352A0A42",
        "requestTime": "2025-05-13T19:46:18.849+08:00"
    },
    "requestData": {
        "checkIn": "2025-05-26",
        "checkOut": "2025-05-28",
        "contact": {
            "email": "operator@klook.com",
            "firstName": "test",
            "lastName": "li",
            "phone": "852 800931187"
        },
        "hotelId": "3969",
        "hotelName": "HoteliersGuru Test hotel 1",
        "occupancy": {
            "adultCount": 2,
            "childCount": 1,
            "childrenAges": [
                8
            ]
        },
        "orderCode": "FRN448811",
        "payments": {
            "payCard": {
                "amount": "MC",
                "cardType": "MC",
                "currency": "USD",
                "expirationMonth": "05",
                "expirationYear": "27",
                "number": "5329594705169154",
                "securityCode": "225"
            }
        },
        "price": {
            "perRoomDailyPrices": [
                {
                    "amountAfterTax": "180.000000",
                    "amountBeforeTax": "165.5000000",
                    "currency": "USD",
                    "date": "2025-05-26"
                },
                {
                    "amountAfterTax": "200.00",
                    "amountBeforeTax": "105.50",
                    "currency": "USD",
                    "date": "2025-05-27"
                }
            ],
            "totalPrice": {
                "amountAfterTax": "1140.000000",
                "amountBeforeTax": "813.0000000",
                "currency": "USD"
            }
        },
        "ratePlanId": "10483045",
        "ratePlanName": "meal + free cancel",
        "roomId": "5120",
        "roomName": "Standard room（Mezzanine, Street view, Balcony）",
        "rooms": [
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            },
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            },
            {
                "guests": [
                    {
                        "firstName": "test",
                        "lastName": "li"
                    }
                ]
            }
        ],
        "specialRequest": ""
    }
}'

出参

字段	类型	是否必须	说明
`success`	`boolean`	true	是否成功，`true`：成功，`false`：失败。当 `false` 时，`error` 需要返回错误信息
`error`	`String`	false	错误信息
`result`	`String`	false	结果

`error`

字段	类型	是否必须	说明
`code`	`String`	true	错误码
`message`	`String`	false	错误信息

`result`

字段	类型	是否必须	说明
`supplierOrderCode`	`String`	true	供应商订单号
`supplierConfirmCode`	`String`	false	供应商确认号
`hotelConfirmCode`	`String`	false	酒店确认号，如果有多个逗号分割
`status`	`String`	true	订单状态见字典订单状态 `orderStatus`

出参示例

{
    "success": true, // 当false时。error需要返回错误信息
    "error": {
        "code": "",
        "message": ""
    },
    "result": {
        "supplierOrderCode": "",
        "supplierConfirmCode": "",
        "hotelConfirmCode": "",
        "status": ""
    }
}

1. 开始使用

2. 接口文档

2.1 基础结构

2.2 推送接口

2.3 标准接口

3. 资料中心

4. FAQ

2.3.2 订单创建

URL

入参

接口请求参数

`Room`

`Guest`

`Occupancy`

`Price`

`TotalPrice`

`PerRoomDailyPrice`

`Other`

`Promotion`

`Payments`

`PayCard`

`Contact` 说明

入参示例

出参

`error`

`result`

出参示例