【磐河旅行】之酒店API接口对接实录

1、项目需求概述：

通过对接第三方磐河旅行的酒店API接口实现在我们的APP 、微信小程序、H5上可提供用户酒店查询、酒店预订、退订等功能。效果如下图：

2、酒店接口功能拆分

除了酒店静态数据字典（如酒店城市数据、酒店品牌数据等）接口主要分数据查询类和订单操作类共有7个接口方法。

酒店数据查询类接口有：酒店搜索接口、酒店详情接口、酒店房型及产品查询接口

酒店订单操作类接口有：下单接口、支付接口、订单取消接口、订单退订接口、订单详情接口。 （PS:磐河旅行开放平台的 订单取消接口和订单退订接口是同一个接口，统称订单取消接口,他们是根据当前订单状态判断 用户发起的是订单未支付时申请取消操作 还是 订单已确认时申请退订操作）。所以酒店API接口涉及的整体业务还是相对简单易懂的。

下图是磐河旅行的酒店在线文档 接口列表

这里需要补充的是除了以上查询类和订单类接口，磐河旅行还有一个订单状态变更推送接口，也就是说当订单状态发生变化时，他们会通过下单时我方传入的回调地址，把变更的订单号及状态回调推送通知给我们，此时我们拿到订单号后需要调用他们的酒店订单详情接口来同步我们的本地订单状态。

3、【磐河旅行】接口技术栈和闭坑方法总结

磐河旅行酒店API接口采用REST风格，对外暴露HTTP服务。如果没有特殊说明，磐河旅行分销开放平台API提供基于http协议，post方式，基于json格式的数据访问，数据编码为UTF-8。有两种调用方式：

1. 分销商主动发起，调用磐河旅行分销开放平台API的请求。

2. 磐河旅行分销开放平台发起，回调分销商系统的请求。（就是我刚上面说的订单状态变更推送接口）

闭坑方法之一：先用Postman调试，请求头部一律记得设置Content-Type:application/json

所以这里强烈推荐一个HTTP API接口免费调试工具：Postman。对接时强烈建议先通过Postman把接口调试通了，然后再coding到自己的代码中，这样可以排除因为自己写的http请求方法和请求方式等问题导致的接口调试失败。

（为了测试调用方便部分接口get/post都支持）但这里请求方式强烈建议一律用POST，(请求头部一律记得设置)Content-Type:application/json。磐河开放平台所有接口方法都支持这种请求方式，强烈建议，少走弯路。

闭坑方法之二：当没订单状态发生变更时没有收到回调时，请用postman自行模拟推送下。

首选确保下单时传入了正确的回调地址，其次确保我们预留的回调地址 外网是可以正常访问的，所以在遇到接受不到回调通知时，先排查下这两个问题，第二个问题用postman自己模拟推送下 看是否返回 HTTPStatus 200即可知晓。

闭坑方法之三：不是所有已确认状态的酒店订单都可以申请退订，至少需要满足两点条件，可以取消且在取消时限内。

订单详情接口中有返回取消政策类型和最晚免费取消时限。根据这两个字段判断

所以前端需要根据这两个字段 判断是否显示 退订 按钮。只有取消政策类型是 限时取消且当前时间小于 免费取消最晚时间内才可以申请退订。

4、上线前准备：

上线前可通过 磐河旅行分销后台 开启白名单，配置自己服务器IP。同时支付接口也有签名验证。所以需要保存和自己的appkey和秘钥

因为磐河旅行的支付方式是预充值，一单一结的，支付接口就是余额支付代扣接口。所以上线前需要确保酒店账户有足够余额，否则会导致下单支付失败。

通过磐河旅行分销后台可以配置，余额不足预警值，当余额低于我们设置的预警值时，磐河旅行会发送短信通知提醒我们。

订单确认成功通知短信，如果需要磐河旅行发送的话，需要联系他们免费开通，默认他们是不发送的，因为我们平台自己发送短信给客户的，所以就没有开启。