锦江酒店企业版直连常见问题集

订单、支付相关

• 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
}]

• 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天的房态返回了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
}

该酒店该房型的品牌协议价是与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
}]

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
}]

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

• 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
    }]
}

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：多人价是指一间房不同入住人数会有不同的价格，主要存在于部分高星系列酒店（例如丽笙品牌酒店），具体由酒店房态接口中的guest字段返回值体现：1:单人价，2:双人价，3:三人价，4:四人价等（如果为空或null表示该价格不是多人价），酒店房态接口会一并返回所有存在的多人价。多人价下单时，预订接口的guestsNum字段需传入对应的人数，而非多人价或活动价下单时不用填guestsNum字段。

接口访问相关

• 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未配置开通。