# 锦江酒店企业版直连常见问题集
# 订单、支付相关
- Q1：目前最大连住天数是多少天
A1：目前可预订的最大入住天数不能超过30天。
- Q2：下单为什么会提示请先解绑后再绑定
A2：如果预订人已绑定在其他企业（基于预订人手机号检查），需先解绑原来的企业再下单。
- Q3：订单状态（orderState）有哪几种
A3：订单状态 1：预订成功、2：已取消、3：预订未到、4：已入住、5：已完成。订单创建成功其状态为1，取消后变成2 ，入住后变成4，离店后变成5，到付单过了保留时间客人未到店过后会处理为3，预付单客人未到店其状态可能是3也可能是5（视店员操作结果）。2/3/5为订单的终结状态。
- Q4：预订人证件和入住人证件是否必填
A4：非必填，如果是非企业活动价（productType=4）的价格，对证件是要求是非必填，入住人到酒店前台会再登记入住人证件。如果填写证件信息一定要真实，保证该证件属于预订人/入住人。活动价的入住人证件信息是必填的，如果本人预订本人入住的活动价是必须填写预订人证件信息。
- Q5：普通企业月结和托管方企业月结API上使用是否有区别
A5：没有，托管方企业月结和普通企业月结差别在于每月5号出账单的归属主体的区别，在API使用上是完全一样的。
- Q6：预付价和到付价是否都是一样
A6：预付价和到付价会存在不相同的情况，保存数据时要分开字段存储。
- Q7：下单接口（postOrder）中的totalRate字段是纯房金还是含其它费用
A7：纯房金，通过实际间夜和预付价advanceRate/到付价spotRate计算出来即可
- Q8：下单接口中的feeRate其他费用字段是什么含义
A8：酒店房态接口中有advanceFeeRate预付其他费用，该字段如果数值不为空则在下预付单时需使用。对于预付单，feeRate传入值为结合advanceFeeRate和预订间夜数的计算结果，对于到付单暂时不用传入feeRate。
- Q9：活动价的预订限制是针对单天还是整单
A9：是对整单做的预订限制。
- Q10：取消订单返回“该订单处于非预订状态，不能取消”是什么原因
A10：订单已经不是预订成功状态（orderState=1），或者在PMS系统里门店人员刚把订单操作为其它状态。
- Q11：订单怎么判断取消成功
A11：msgCode=0 取消成功 或者msgCode=10219 存在罚金并有偿取消成功，message会正确提示退回的金额。
- Q12：什么时候需要用到支付接口
A12：目前支付接口支持微信和支付宝支付，使用场景是到付单转预付。到付单可以到店支付或者线上到付转预付，到付单成单后调用支付接口支付。
- Q13：支付接口如何使用
A13：如果要使用微信支付，payType传2，返回值里组成微信付款二维码展示。如果要支付宝支付，payType传3，返回值参数组成表单唤起支付宝收银台界面。支付后调用支付查询接口查询订单的支付状态即可。
- Q14：预付支付储值,月结还需要调支付接口吗
A14：不需要，储值和月结只需要在下单时候准确填写payType即可。下单时候会在成单后自动从储值账户扣减或者从企业月结额度扣减。
- Q15：如何获取订单的真实结算金额
A15：两种途径：第一种是通过订单账单查询接口获取，第二种是到锦江酒店企业版PC官网https://biz.bestwehotel.com/中对应的功能模块查询储值支付对账、月结支付对账。
# 酒店信息、房态相关
- 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
}]
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
}
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官网展示的一样，改房型下有两个价格提供到客户进行选择
目前价格商品类型有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
}
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
}]
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
}]
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
}]
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
}]
}
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：对接方请求所有查询类接口时，应控制同时执行的线程数，避免并发数偏多。其中，请求酒店房态查询接口/hotel/getHotelRoomStatus 的线程数建议不超过10，其它每个查询接口的线程数建议不超过5。 调用接口如果遇到此返回：{"msgCode":-6000,"message":"接口当前访问数过多，请稍后再试或降低访问频率。","result":null,"errors":null} 表示触及接口限流设置，此时请对接方先行检查该接口的请求线程数和每天的总请求量（推荐酒店房态查询不超过50万次/天，其它查询类接口总合计不超过20万次/天），若检查结果正常可反馈锦江对接人。
- Q2：定时获取酒店房态建议用什么样的机制？
A2：可分日期从酒店房态接口（/hotel/getHotelRoomStatus）获取，例如近7天的房态每家店间隔30-60分钟获取1次； 近8-21天的房态每家店间隔60-120分钟获取1次，21-45天的房态可每家店间隔8-12小时获取1次，45天之后的房态每家店每天获取1次。在酒店维度也可以按常订和不常订区分获取频率。 对接方根据自身情况设计酒店房态数据同步机制，如果有特殊情况可联系协商。
- Q3：接口返回 “xxx.xxx.xxx.xxx(具体ip) not in XX（具体appid） white list”
A3：请检查自身服务器出口ip是否与提供给锦江的一致。
- Q4：接口返回 “null 403 app null can't access matching routes”
A4：可能的原因：请求头参数fizz-appid（或appid）未正确设值、或当前appid未配置开通。