酒店客栈
未来酒店2.0商家对接文档
未来酒店2.0商家对接文档
点击查看未来酒店快速接入文档 (new)
本文档主要提供给商家对接阿里旅行未来酒店2.0，描述实现未来酒店相关功能服务对接，商家需要实现的主要功能以及如何与阿里旅行平台交互，为商家对接提供参考。未来酒店服务提供用户更快捷，方便，炫酷的体验，极大提升酒店竞争力。如提前开发票，在线选房，智能门锁，在线客房服务等等功能。
目前一期要求对接的功能有：在线选房、在线开发票、水单、智能门锁等功能，其余功能与对于的阿里技术支持或者产品沟通的为准。
一、未来酒店2.0功能场景
未来酒店2.0主要需要实现阿里旅行平台与PMS的直连交互，实现用户与PMS/前台的在线交互。
二、产品整理交互图
三、PMS功能升级
- PMS获取到酒店在平台请求后，需要保存记录请求，建议保存如下信息：
- 请求ID
- 请求类型
- 要求动作
- 操作内容
- 请求时间
- 等。
- 定时调用阿里旅行平台请求列表查询TOP接口更新酒店请求列表并同步到各台PMS。
- 当请求处理状态有变化时，可以更新本地请求记录。如前台认领了请求，前台处理了请求等。
4.2.1 消息提醒
当代办事项在一定时间内仍无人认领或处理，则可以定时消息弹出提醒
4.2.2 代办事项浮框
为了能让前台时刻查看酒店具体代办事项列表，同时更醒目，希望在PMS主界面上能有个代办事项展示，一直进行展示：
- 能够及时同步到代办事项列表，并更新到该展示页上。如有新的代办事项，代办事项有状态变更等。
- 对已经完成的代办事项可以从展示页中移除。
- 至少能展示：代办事项操作类型，哪个房间，需要完成时间，状态，操作等。
- 能高亮有多少个待办事项需要处理，并能根据变化而变化
- 能展示处理代办事项有相关奖励文案
- 可以通过点击代办事项跳转进入详细代办事项列表
代办事项浮框示范
详细代办事项列表页示范
4.2.3请求处理反馈
当请求/代办事项被认领或完成，或系统自动完成处理后，需要调用阿里旅行处理反馈TOP接口返回。
4.2.4请求列表查询
PMS能定时从平台主动同步平台请求列表，通过调用阿里旅行请求列表查询TOP接口查询，并及时更新到酒店代办事项列表中。
四、未来酒店2.0技术对接概要
1、涉及的4个接口文档列表
由于需求还在不断整理完善中，请以线上实时结果为准（大的变更一般会通知商家）。
1、订单信息更新接口 （商家需要实现此服务，后文简称update接口）
//open.alitrip.com/docs/doc.htm?&docType=1&articleId=104398
2、酒店业务信息查询接口——（商家需要实现此服务，后文简称queryOutInfo接口）
//open.alitrip.com/docs/doc.htm?&docType=1&articleId=104586
3、TOP接口(put)——订单信息上传更新接口(商家调用，后文简称put接口）
//open.taobao.com/doc2/apiDetail.htm?apiId=26546
4、TOP接口(get)——请求数据查询获取接口(商家调用，后文简称get接口)
//open.taobao.com/doc2/apiDetail.htm?apiId=26560
5、[附件]Top接口（get&put）附加文档简绍 (context描述)
//open.alitrip.com/docs/doc.htm?&docType=1&articleId=104397
2、商家对接流程
推荐对接方案：
为了更好的用户体验，原则上要求商家以上四个接口全部对接。
两个商家调用接口，1：put接口用于商家主动上行推送数据；2：get接口用于商家主动从阿里平台拉取数据。
两个需要商家实现的服务，1:update接口，用于接受阿里平台的下行数据请求（选房、开发票、任务取消、开门请求、房间断电、梯控等）；2：queryOutInfo接口，用于提供给阿里平台进行主动查询商家数据（任务处理结果、选房结果、水单查询等）
如果业务实现上确实有困难的商家，通过双方沟通后，可以仅仅对接（get\put）两个接口，来实现未来酒店2.0的所有需求。
接口数据交互图：
五、在线选房
1、场景描述
用户可以通过阿里旅行APP在线进行房间的选择（类似机票选座，或者电影院选座的功能）。
2、数据交互
2.0 阿里平台调用“酒店信息查询接口” （operateType=10），进行房态信息的查询，商家系统返回酒店的房态信息（具体格式参见接口文档定义）。
2.1 用户下单成功后，在线浏览酒店的楼层结构图（内容由第三方CP提供、高德提供位置服务），查看可选房间情况，然后选择自己钟爱的房间号。
2.2 阿里平台收到用户选房请求后，调用“订单信息更新接口”（operateType=3）,向商家下发选房请求
2.3 商家系统受到来自阿里平台的选房请求后，进行酒店本地房态更新，然后返回结果（选择成功或者选择失败）
2.4 如果此次选房失败，用户可以重新选择别的房间。
2.5 选择房间后，如果结果没有正常返回，阿里平台可以调用“酒店信息查询接口”，进行任务结果查询（operateType=104）。商家系统返回查询结果。
2.6 酒店PMS（或者商家系统）当酒店房态信息发生变化的时候，需要实时的主动上传房态信息（operateType=23）到阿里平台。（通过调用TOP的put接口实现）
2.7 酒店PMS 可以通过阿里的top接口，get接口以及put接口与阿里系统进行直连数据交互。
通过调用get接口，来获取用户的选房请求（operateType=3），然后调用put接口进行选房结果确认（operateType=26）
六、在线预约发票、水单
1. 场景描述
- 用户通过阿里旅行预订信用住订单成功，通过阿里旅行APP进入订单详情页，操作预约发票，设置发票抬头，领取时间，领取方式等。提交预约。
- 发票预约请求下传/同步至酒店PMS系统，PMS系统接收预约请求展示/提示至前台代办事项。
- 前台认领任务，打印发票。操作成结请求处理
- PMS同步请求处理状态至阿里旅行，阿里旅行通知给客人发票已准备就绪。
2. 接口数据交互
2.1 B/S或者云PMS方案：
- 阿里平台收到用户预约发票请求后，调用“订单信息更新接口”（operateType=1）,向商家下发预约发票请求，接口详情
- 酒店系统接收到预约发票请求后，进行提示/待办事项处理，详见上问三、PMS功能升级
- 当预约发票请求状态有发生变化时，如已认领，已开票等，调用阿里旅行PUT TOP接口进行结果同步，接口详情
2.2 C/SPMS 或者单通道通信PMS方案：
- 高频率定时从阿里旅行平台获取请求列表，通过调用阿里旅行GET TOP接口. 接口详情。
- 酒店系统获取请求列表后，判断请求类型是否为预约发票请求，预约发票请求协议定义详情，如果是预约发票请求，则处理提示/代办事项，详见上问三、PMS功能升级
- 当预约发票请求状态有发生变化时，如已认领，已开票等，调用阿里旅行PUT TOP接口进行结果同步，接口详情
七、智能门锁（自助开门、自助断电、自助乘梯）
交互机制类似，详情参见接口文档定义
1. 场景描述
- 用户预订信用住订单成功。
- 用户到酒店前台成功办理入住手续。
1.1 自助乘梯
- 用户可以无需领取房卡，通过阿里旅行APP进入订单详情页，操作自助乘梯。
- 阿里旅行接收用户操作后，同步乘梯请求至PMS。
- PMS校验是否满足乘梯条件，满足，则调用门锁云服务进行乘梯操作。
- 此时，电梯将自动选择该用户入住房间所在楼层。
1.2 自助开门
- 用户可以无需领取房卡，通过阿里旅行APP进入订单详情页，操作自助开门。
- 阿里旅行接收用户操作后，同步开门请求至PMS。
- PMS校验是否满足开锁条件，满足，则调用门锁云服务进行开锁操作。
- 此时，房门将自动打开，并自动通电
1.2 自助断电
- 用户可以无需领取房卡，通过阿里旅行APP进入订单详情页，操作自助断电。
- 阿里旅行接收用户操作后，同步断电请求至PMS。
- PMS校验是否满足开锁条件，满足，则调用门锁云服务进行断电操作。
- 此时，房间将断电。
2. 接口数据交互
2.1 B/S或者云PMS方案：
- 阿里平台收到用户自助乘梯、自助开门、自住断电请求后，调用“订单信息更新接口”（operateType=7/6/8）,向商家下发请求，接口详情
- 酒店系统接收到自助乘梯，自助开门，自助断电请求后，系统自动处理请求，判断是否满足操纵条件。
- 如果满足条件，则调用智能门锁云服务进行操作门，梯，电等。
- 系统同步返回处理结果。
2.2 C/SPMS 或者单通道通信PMS方案：
- 高频率定时从阿里旅行平台获取请求列表，通过调用阿里旅行GET TOP接口. 接口详情。
- 酒店系统获取请求列表后，判断请求类型是否为自助乘梯、自助开门、自助断电请求，智能门锁请求协议定义详情，如果是，则系统自动处理请求，判断是否满足操纵条件。如果满足条件，则调用智能门锁云服务进行操作门，梯，电等。
- 最终调用阿里旅行PUT TOP接口进行结果同步，接口详情
八、任务认领机制
阿里平台的各个接口支持幂等调用，商家需要考虑酒店前台，多个台电脑（多个CS架构的PMS）之间的任务并发问题。如果需要人工介入处理，或者可能发生并发处理的地方。在处理任务前可以通过调用put接口，进行任务认领（operateType=30），此时阿里系统保证同一时刻并发调用的仅有一个请求可以认领成功。建议每个任务处理前进行认领操作，但不强求必须这么做。
