# WeHotel直连常见问题集

本问题集是针对用户调用商业商旅的API服务和嵌入自有系统时,提供常见问题集供用户快速解决问题。

# 订单相关

Q1:目前最大连住天数是多少天

A1:目前可预订的最大入住天数不能超过15天。

Q2:下单为什么会提示请先解绑后再绑定

A2:原因是取决于下单的bookMobile预订人手机号,该预订人已绑定在其他企业,需先解绑原来的企业再下单。

Q3:订单状态(orderState)有哪几种,怎么扭转订单状态,是否实时

A3:订单状态只有1:预订成功2:已取消3:预订未到4:已入住5:已完成。订单详情接口的订单状态变更是实时的,订单无论到付还是预付刚生成就是1,预订完成,入住后就变成4已入住,离店后就变成5 已完成,生成后要取消订单就变成2 已取消,支付方式为到付预订了人没到,保留时间过后会处理为3,预订未到,预付未到有的门店会操作到已完成或者预定未到,具体看门店人员的操作。

Q4:订单状态的最终状态有哪几个

A4:2:已取消3:预订未到 5:已完成

Q5:订单支付方式有哪些

A5:订单的支付方式有到付和预付(月结,储值).到付payType是0,储值支付1,月结支付payType是2,请准确根据支付方式传值。

Q6:预订人证件和入住人证件是否必填

A6:非必填,如果是非企业活动价(productType=4)的价格,对证件是要求是非必填,入住人到酒店前台会再登记入住人证件。如果填写证件一定要真实,保证该证件属于预订人/入住人。活动价的入住人证件信息是必填的,如果本人预订本人入住的活动价是必须填写预订人证件信息。

Q7:普通企业月结和托管方企业月结API上使用是否有区别

A7:没有,托管方企业月结和普通企业月结差别在于每月5号出账单的归属主体的区别,在API使用上是完全一样的

Q8 :预付价和到付价是否都是一样

A8 :预付价和到付价会存在不相同的情况,设计时要分开存储,兼容不一致的情况

Q9 :postOrder下单接口的totalRate字段是纯房金还是含其它费用

A9 :纯房金,通过实际间夜和预付价advanceRate/到付价spotRate计算出来即可

Q10 :下单接口postOrder中的feeRate其他费用字段是什么

A10 :可以到看酒店房态接口中有advanceFeeRate预付其他费用,如果酒店房态接口返回该字段不为null,并且下单时预付的支付方式(储值或月结),因为advanceFeeRate是单间夜的,所以调用下单接口时应按实际预订间夜和advanceFeeRate计算后传到postOrder的feeRate字段。到付目前没有其他费用,所以到付单的feeRate不用传入。

Q11 :可以简述一下下单的流程吗

A11

第一步:

调用真实房态信息接口,获取对应的价格类型,核对库存quota是否>预订库存,金额是否相当

第二步:

调用下单postOrder接口进行下单,返回orderCode即为创单成功。下单失败建议重试三次,因为有业务因素创单失败或者网络因素导致接口未能正常响应,重试请求接口请求参数必须一样。因为一个externalId只会生成一张wehotel的单,所以不用担心重复订单的产生。若重试创单失败,应记录失败的下单日志,及时向wehotel技术人员进行反馈

第三步:

调用查询订单信息接口进行订单核单和订单信息的记录。

Q12 :取消订单返回{msgCode:-300,message:该订单处于非预订状态,不能取消,请联系客服。,result:null,errors:null,bizId:null}是什么情况

A12:订单在orderState=1预订成功状态才能取消,若订单已经处于已取消,入住,完成状态时候是不能再取消的。

Q13 :订单怎么判断取消成功

A13:msgCode=0 取消成功 或者msgCode=10219 存在罚金并有偿取消成功,message会正确提示退回的金额

Q14 :下单提示{msgCode:-10290,message:3016-需要提供营业日价格,result:{orderCode:null,orderState:null},errors:null,bizId:PP_1722561119_1600912699301_384304767}是什么意思。

A14:一般是预订入住离店的营业日单天或者连住多天中存在某天没有房态的情况,或者下单的productCode传错值

Q15 :下单提示{msgCode:-10213,message:-10213-1: 房价有误,请刷新后 重下订单,result:{orderCode:null,orderState:null},errors:null,bizId:PP_1722561120_1600912745262_170252110}是什么意思

Q15:传入的下单的订单价格不正确,请核对一下是否与真实房态的价格一致

Q16 :活动价的预订限制是针对单天还是整单

A16:针对下单而言,是对整单做的预订限制

Q17:如何对接订单的真实结算金额

A17:目前直连接口API暂时未对接真实结算金额,只有查询订单信息接口的realPayRate订单金额字段。储值支付对账请登录企业商旅PC企业版https://biz.bestwehotel.com/ (opens new window)到企业账户模块进行储值的核对,月结支付对账以每月5号的企业月结账单为准。

Q18:下单出现:绑定失败:该会员账号绑定了多个手机号,请使用第一手机号进行企业绑定

A18:这个会员有多个注册手机,找客服可以解绑。

Q19:下单返回:{msgCode:-10222,message:预订失败,扣除储值失败[请求收银台支付异常[510-4:您本月可用额度不足以支付本次消费,请联系管理员调整额度或选择前台支付。]]。,result:{orderCode:null,orderState:null},errors:null,bizId:PP_1722561121_1615121531414_207672717}

A19:额度不够,请检查企业储值。

# 支付相关

Q1:预付支付储值,月结还需要调支付接口吗

A1:不需要,储值和月结只需要在下单时候准确填写payType即可。下单时候会在成单后自动从储值账户扣减或者从企业月结额度扣减

Q2:什么时候需要用到支付接口

A2:目前支付接口支持微信和支付宝支付,使用场景是到付单转预付。到付单可以到店支付或者线上到付转预付,到付单成单后调用支付接口支付。

Q3:支付接口如何使用

A3:如果要使用微信支付,payType传2,返回值里组成微信付款二维码展示。如果要支付宝支付,payType传3,返回值参数组成表单唤起支付宝收银台界面。支付后调用支付查询接口查询订单的支付状态即可。

Q4:到付单是否有担保

A4:到付单没有担保

# 酒店信息、房态相关

Q1:roomTypeCode和sCode哪一个才是房型编号

A1:房型编号以roomTypeCode为准

Q2:怎么看该酒店支持什么支付方式

A2:具体看房态接口supportPay字段,如果supportPay: [0, 1]同时支持预付和到付,supportPay: [0]仅支持到付,supportPay: [1]仅支持预付

Q3:为什么查询的酒店没有房态

A3:查看酒店基本信息接口,status酒店状态是否为1开业,还有bookFlag是否为1(支持预订),只有status为1和bookFlag为1的酒店存在房态,如果满足条件还是没有房态,可反馈给wehotel的销售或者运营跟进。

Q4:查询酒店房态接口返回房态是按当天开始算,还是第二天开始算

A4:按当天营业日算,假如endOfDay传的是2021-01-23,days传的是2.返回的就是2021-01-23和2021-01-24两天的房态

Q5 :酒店房态接口中哪个是与wehotel的交易价,哪个是原价

A5 :rackRate门市价是原价,交易价要看预订方式是到付还是预付,如果到付交易价取的是spotRate,预付交易价为advanceRate。

Q6:酒店是用什么地图坐标的

A6:具体支持什么坐标请通过酒店基本信息接口的mapInfo数组节点查询,会支持1-4种地图坐标,本系统一般都是百度地图坐标,根据mapType坐标类型(0 百度 1 Google 2 腾讯 3 高德)来判断

例子:

mapInfo: [{
    lag: 31.24301361814939,
    lng: 121.488952570621,
    mapType: 0
}]
1
2
3
4
5

Q7 :酒店房态接口的返回数据库结构是怎样的,是否每个酒店每个房型只有一个价格

A7

举个例子:查询某一酒店的OSST房型,查询营业日为2021-01-23,days为2的两天(01-23,01-24)房态

{
    msgCode: 0,
    message: 成功,
    result: {
        roomTypeList: [{
            productList: [{
                quota: 28,
                endOfDay: 1611331200000,
                rackRate: 373,
                spotRate: 317,
                advanceRate: 317,
                spotBreakfastCount: 2,
                advanceBreakfastCount: 2,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-23 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-23 18:00:01,
                        end: 2021-01-24 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: j20136662,
                productName: 品牌协议价,
                productType: 2,
                protocolType: 2,
                freeCancelTime: 1611396000000,
                supportPay: [0, 1],
                hasEffiveTime: true,
                startTime: 1529942400000,
                endTime: 1861891199000,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }, {
                quota: 28,
                endOfDay: 1611331200000,
                rackRate: 373,
                spotRate: 298,
                advanceRate: 298,
                spotBreakfastCount: 2,
                advanceBreakfastCount: 2,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-23 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-23 18:00:01,
                        end: 2021-01-24 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: CORLJIN,
                productName: 平台协议价,
                productType: 3,
                protocolType: null,
                freeCancelTime: 1611396000000,
                supportPay: [0, 1],
                hasEffiveTime: false,
                startTime: null,
                endTime: null,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }, {
                quota: 28,
                endOfDay: 1611417600000,
                rackRate: 373,
                spotRate: 317,
                advanceRate: 317,
                spotBreakfastCount: 2,
                advanceBreakfastCount: 2,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-24 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-24 18:00:01,
                        end: 2021-01-25 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: j20136662,
                productName: 品牌协议价,
                productType: 2,
                protocolType: 2,
                freeCancelTime: 1611482400000,
                supportPay: [0, 1],
                hasEffiveTime: true,
                startTime: 1529942400000,
                endTime: 1861891199000,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }, {
                quota: 28,
                endOfDay: 1611417600000,
                rackRate: 373,
                spotRate: 298,
                advanceRate: 298,
                spotBreakfastCount: 2,
                advanceBreakfastCount: 2,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-24 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-24 18:00:01,
                        end: 2021-01-25 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: CORLJIN,
                productName: 平台协议价,
                productType: 3,
                protocolType: null,
                freeCancelTime: 1611482400000,
                supportPay: [0, 1],
                hasEffiveTime: false,
                startTime: null,
                endTime: null,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }],
            roomTypeCode: OSST,
            roomTypeName: 精致双床房
        }]
    },
    errors: null,
    bizId: PP\_1722561121\_1600912774077\_512960849
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

解读:

从返回的结果集可以看出查询2天的房态返回了productList的长度为4而不是2,其中2条是endOfDay(1611331200000),另外2条是endOfDay(1611417600000)的,可能会有疑问为什么同一天下有2条数据,因为可以看到同一天(endOfDay)下有两个不同的productCode,代表着有两个不同的价格类型,平台协议价和品牌协议价,所有每天都有两个价格,所以查询两天返回了4条数据。

如下图商旅PC官网展示的一样,改房型下有两个价格提供到客户进行选择 Alt text

目前价格商品类型有0 本店协议价1 批量分店品牌协议价2 组合品牌协议价3 平台协议价4 企业活动价,最多可能一个房型下有5种类型的价格。目前本系统是将用户能享的所有价格进行输出,没有做择优的规则,需要客户进行相应的业务处理。同理要下该房型的哪个价格进行下单,假如要下品牌协议价,就要把获取的productCode:j20136662传入postOrder下单接口的productCode参数中。

Q8 :每间酒店的productCode是否都是固定一样的

A8 :每间酒店的productCode都是会有几率不一样的

{
    msgCode: 0,
    message: 成功,
    result: {
        roomTypeList: [{
            productList: [{
                quota: 2,
                endOfDay: 1611331200000,
                rackRate: 229,
                spotRate: 195,
                advanceRate: 195,
                spotBreakfastCount: 0,
                advanceBreakfastCount: 0,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-23 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-23 18:00:01,
                        end: 2021-01-24 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: j20076499,
                productName: 品牌协议价,
                productType: 2,
                protocolType: 2,
                freeCancelTime: 1611396000000,
                supportPay: [0, 1],
                hasEffiveTime: true,
                startTime: 1529942400000,
                endTime: 1861891199000,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }, {
                quota: 2,
                endOfDay: 1611331200000,
                rackRate: 229,
                spotRate: 183,
                advanceRate: 183,
                spotBreakfastCount: 0,
                advanceBreakfastCount: 0,
                cancelRule: {
                    supportCancel: 2,
                    cancelPenaltyList: [{
                        start: 1970-01-01 08:00:00,
                        end: 2021-01-23 18:00:00,
                        cancelType: 0,
                        type: null,
                        value: null
                    }, {
                        start: 2021-01-23 18:00:01,
                        end: 2021-01-24 12:00:00,
                        cancelType: 1,
                        type: 0,
                        value: 1
                    }],
                    newCancelPenaltyList: null
                },
                productCode: CORLJIN,
                productName: 平台协议价,
                productType: 3,
                protocolType: null,
                freeCancelTime: 1611396000000,
                supportPay: [0, 1],
                hasEffiveTime: false,
                startTime: null,
                endTime: null,
                advanceFeeRate: null,
                spotFeeRate: null,
                guests: null,
                bookRule: null
            }],
            roomTypeCode: SIRA,
            roomTypeName: 单人房A
        }]
    },
    errors: null,
    bizId: PP\_1722561119\_1600912699301\_513075614
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

该酒店该房型的品牌协议价是与Q7中的productCode是不一样的,所以要下什么价格,必须准确在下单接口传入正确的productCode。否则下单会报错

Q9 :每个价格是否有有效期限制

A9 :有的价格是永久有效的,有的价格是属于有时间有效期限制的,房态接口返回字段hasEffiveTime为true就是有生效时间限制,反之为false就属于永久有效。如果为true有生效时间限制的时候,查看startTime和endTime字段,要预订的入住营业日至离店营业日必须在startTime-endTime之间才能使用该价格。

Q10 :如何判断该房型没有房态

A10 :字段quota=0或者当前营业日下没有数据返回

Q11 :价格是否含早,多少早是由业务决定还是以接口决定

A11 :是否含早由接口字段到付早餐数spotBreakfastCount和预付早餐数advanceBreakfastCount字段解决,早餐枚举值为null/0,1,2。null/0为无早,1为单早,2为双早

Q12 :如何解析wehotel的取消规则

A12 :按newCancelPenaltyList》cancelPenaltyList:》freeCancelTime节点顺序进行解析,如果第一个节点newCancelPenaltyList不为null,取newCancelPenaltyList进行解析,为null则取cancelPenaltyList进行解析,如果cancelPenaltyList为null取freeCancelTime进行解析。

Q13 :如何理解newCancelPenaltyList节点的取消规则

A13 :目前引用newCancelPenaltyList有两种数据结构

维也纳常用数据结构

例子:

newCancelPenaltyList: [{
    cancelType: 0,
    type: null,
    value: null,
    minCount: 0,
    maxCount: 3,
    startHour: null,
    endHour: 6
}, {
    cancelType: 1,
    type: 0,
    value: 1,
    minCount: 0,
    maxCount: 3,
    startHour: 6,
    endHour: null
}, {
    cancelType: 0,
    type: null,
    value: null,
    minCount: 3,
    maxCount: null,
    startHour: null,
    endHour: 30
}, {
    cancelType: 1,
    type: 0,
    value: 1,
    minCount: 3,
    maxCount: null,
    startHour: 30,
    endHour: null
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

cancelType是分免费取消和有偿取消,hour从24小时开始减的意思是就是假如你预订今天,就是今天的24点-6,今天的18点,如果30就是24-30就是前一天的18点。

maxCount 3 就是取消的间如果小于3间,就当天18点前可以免费取消。超过18点有偿取消。如果大于3间,就要前一天18点前免费取消,超过了就是有偿取消。例子:如果type是0就是房晚,value值是1是1房晚。

如果是1百分数,value是20,代表20%。这只是例子,实际以我们返回的参数为准

欢朋希尔顿常用取消规则结构

newCancelPenaltyList: [{
    cancelType: 0,
    type: null,
    value: null,
    minCount: null,
    maxCount: null,
    startHour: null,
    endHour: 6
}, {
    cancelType: 1,
    type: 1,
    value: 100,
    minCount: null,
    maxCount: null,
    startHour: 6,
    endHour: null
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

计算规则与第一点维也纳一样,少了间数的条件,意思是预订营业日18点前免费取消,18点后有偿取消,罚金形式100%房金。这只是例子,实际以我们返回的参数为准

丽笙常用取消规则结构

newCancelPenaltyList: [{
    cancelType: 1,
    type: 0,
    value: 1,
    minCount: 0,
    maxCount: 0,
    startHour: 48,
    endHour: 0
}, {
    cancelType: 1,
    type: 0,
    value: 1,
    minCount: 0,
    maxCount: 0,
    startHour: 0,
    endHour: 0
}, {
    cancelType: 0,
    type: ,
    value: ,
    minCount: 0,
    maxCount: 0,
    startHour: 0,
    endHour: 48
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

计算方式同维也纳和欢朋希尔顿一样,少了简数的条件,假如预订是2021年1月23日的房态,以上解析为在01月22日 0点前可免费取消,01月22日 0点-01月24日0点取消,收取1晚房费罚金,01月24日0点后取消,收取1晚房费罚金

Q14 :如何理解cancelPenaltyList节点的取消规则

A14

锦江系常用取消规则数据结构例子:

cancelRule: {
    supportCancel: 2,
    cancelPenaltyList: [{
        start: 1970-01-01 08:00:00,
        end: 2021-01-22 18:00:00,
        cancelType: 0,
        type: null,
        value: null
    }, {
        start: 2021-01-22 18:00:01,
        end: 2021-01-23 12:00:00,
        cancelType: 1,
        type: 0,
        value: 1
    }]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

cancelType是分免费取消和有偿取消,解析为在2021-01-22 18:00:00之前免费取消,在2021-01-22 18:00:01之后有偿取消,罚金为1房晚。

Q15 :如何理解freeCancelTime节点的取消规则

A15 :在freeCancelTime之前是免费取消,在freeCancelTime之后是不能取消

Q16 :如果预订多天的取消规则怎么取

A16 :取第一天的取消规则即可

Q17 :房型编号roomTypeCode是否唯一

A17:房型编号roomTypeCode对一间酒店而言是唯一的,同一门店下的房型编号不会重复

Q18 :房态落地如何存储应该怎么存储?

A18:房态变化规律是越接近今天的营业日变化的越大,可以理解为未来0-3天的变化是最大的,越往后变化的速度会越来越低,建议不要房态一起全量同步,应该根据时间条件来控制同步速率。开发分段式房态同步计划,并进行正确展示。同步计划建议,以当前营业日进行计算,当天-未来3天1小时同步一次,4-10天3小时同步一次,10天-20天6小时同步一次,阶梯式更新

Q19 :目前房态可查询最大的天数是多少?

A19:目前是业务上房态维护最大是90天

Q20 :酒店基本静态信息应该怎么存储?

A20:酒店列表,酒店基本信息,酒店房型,酒店图片等静态信息变更的频率比较少,建议可24-72小时间距同步一次

Q21 :查询房态信息接口不传priceType =2是否会返回企业活动价

A21:不会,之后传priceType =2才会返回企业活动价,看需求接入

Q22 :什么是单人价,什么是双人价

A22:目前单人价和双人价的业务规则只存在丽笙系列的酒店,如何判断丽笙系列的酒店,查询酒店信息接口,若sourceType: Radisson,就证明该酒店是丽笙酒店,房态信息接口guest字段返回1就是单人价,返回2就是双人价,目前业务是允许同一价格商品类型同时存在单人价和双人价,例同样是同房型的平台协议价,但是会有单人价和双人价同时返回的情况,预订了单人价是只能单人入住,双人价允许2人或者到房型人数上限入住。该业务只存在于丽笙酒店

# 接入相关

Q1 :目前接口是否对请求频率有所限制

A1:查询建议:查询10天内的房态时,每家分店最多可30分钟查询一次,查询11-30天内的房态时,每家分店最多可60分钟查询一次,查询31-60天内的房态时,每家分店最多可半天查询一次,查询61-90天内的房态时,每家分店最多一天查询一次。如果有特殊的频率要求,请联系协商

Q2: 直连接口返回route which match current request can't be access by client app, or is not exposed to current gateway group

A2: 原因可能是:

  1. 检查http请求头中appid或者(fizz-appid)是否正确传送。
  2. WH暂未开通此appid或者此appid暂未绑定到网关。

Q3 : 直连接口返回 xxx.xxx.xxx.xxx(具体ip) not in XX(具体appid) white list

A3 :检查自身服务器出口ip是否与提供给WH的一致。

Q4:接口返回{code:6001,msg:当前访问人数较多,请稍后再试。}

A4:当前访问接口次数较多,请降低访问频率。