火车票接口开发

最新推荐文章于 2022-08-21 05:07:51 发布

小明帝

最新推荐文章于 2022-08-21 05:07:51 发布

阅读量1.6k

点赞数 1

文章标签：火车票聚合数据火车票订单第三方火车票接口火车票接口开发

本文链接：https://blog.csdn.net/qq_40977382/article/details/80745199

版权

一、环境准备

1.聚合的火车票订票接口；

2.短信接口；

3.支付接口；

4.订单异常补偿。

二、买票流程

（参考聚合官方文档，火车票订票接口常见问题：https://code.juhe.cn/docs/201 ，此文档开发前必读）

1.官方解说

查车站简码
- 可通过https://www.juhe.cn/docs/api/id/173查询单个或全部车站的简码
- 建议将车站简码缓存或存数据库，不必每次都查
- 如果您确定某个车站存在，却查不到简码，请联系我们核实
查余票
- 注意：查余票功能与12306官网结果一致，比如查苏州到上海的火车，结果中会出现苏州到上海虹桥的车次
提交订单
- 提交订单的过程中，大多数用户都会遇到参数格式不对之类的问题，还请您多读、多理解官方文档中的说明
- 务必注意：
- 如果上一步查的是苏州到上海的余票
- 根据实际情况决定选择苏州到上海虹桥这段乘车区间
- 那么提交订单时请将乘车区间设为苏州到上海虹桥，而不是查余票时的苏州到上海
提交成功后该如何知道这笔订单的处理状态？
- 有两种方式：您主动查询（通过订单查询API https://www.juhe.cn/docs/api/id/173/aid/583）和我们推送（回调）给您
- 订单状态为0：表示待处理，处理完会变成1（占座失败）或2（占座成功）
- 请注意：提交订单成功不代表占座成功，提交订单成功后我们会立刻处理您的需求
- 查看订单的处理结果，如果为失败（1），则此订单结束，请重新下单
- 由于订单的处理结果不是立刻返回的，需要依赖于回调
取消订单或者支付订单
- 如果占座成功，可以在规定时间内（即在12306官网购票时的支付倒计时时间，目前是30分钟，按照12306的规定，可能会变）取消订单
- 或者请求支付订单（会从您的聚合余额中扣费，请保证余额充足，此处也请您好好想想如何扣除自己用户的费用）
退票
- 如果出票成功，但是用户还未到火车站取票，可以通过我们的接口申请退票
- 如果用户已取票且需要退票
- 这时候用户已经拿到了纸质车票
- 是无法在线退票的
- 需要用户自行去火车站窗口处理
- 这种方式需要您公司的客服来通知我们的客服去核实退款，核实无误后我们会将款项加到您的聚合账户中

2.个人理解

简码 --> 查询 --> 提交订单 --> 回调（占座成功、占座失败），大多数处理时间在30秒内，少数1分钟左右（官方解释，以实际情况为准） --> 占座成功待支付的订单，支付请求出票 --> 回调（出票成功、出票失败） --> 出票成功的订单，未线下取票，时间允许范围内可以申请退票 --> 回调（退票成功、退票失败）

三、功能集成流程

1.查车站简码

简码基本上是固定的，可以将车站简码缓存至数据库。

2.查余票

https://www.juhe.cn/docs/api/id/173/aid/580

官方文档很详细，每个产品的查询方式是不同的，有可能有组合筛选，需要注意出发日期就是查询日期，会查询到满足条件的所有车次。

3.提交订单

https://www.juhe.cn/docs/api/id/173/aid/581

一个订单最多可以有五个乘客，乘客信息必须经过12306验证，才可以占座成功。需要注意的是，儿童票联系人信息，如果儿童有身份证信息，可以使用，如果没有，使用大人的姓名和身份证号码，只需要票类型是儿童票就可以。不过要等到回调的时候才可以拿到儿童的具体票价。

4.占座成功的异步回调

https://www.juhe.cn/docs/api/id/173/aid/687

三个回调函数的配置都是在同一个界面，可以使用此地址提供的API测试工具配置，具体内容根据自己开发的服务器地址去配置，不清楚可以参考开发前必读文档。

所有回调的参数都是一个JSON格式的字符串，参数名：data。所有的回调都是返回success字符串，聚合才不会再次回调，否则总共回调三次。回调方法签名验证格式：

sign=md5('juhe'+您的key+orderid+user_orderid)  /*加号只是为了告诉您这几个值需要连接起来，加号不是md5加密的内容*/

5.请求出票（自己的支付接口，支付成功后同步调用请求出票）

https://www.juhe.cn/docs/api/id/173/aid/582

请求出票聚合会扣款，但是是聚合余额的金额，结果也是依赖于异步回调，出票成功后，基本上用户的需求就完结了。但是出票失败的情况，需要考虑如何给用户退款，正常情况下，占座成功后请求出票都会成功（不过也有例外）。

需要注意的是，占座成功的订单，半个小时后，需要自己请求取消待支付订单接口，因为在当前情况下，订单保留半个小时是正常逻辑。

6.线上退票

https://www.juhe.cn/docs/api/id/173/aid/639

出票成功的订单，满足条件可以申请线上退票，退票支持按照乘客进行退票，一个订单中有多个乘客的时候，其中一个退票不影响其他乘客的票。

四、常见问题列表

1.儿童票

儿童票联系人信息，如果儿童有身份证信息可以使用，认证即可使用。如果没有，使用大人的姓名和身份证号码，只需要票类型是儿童票就可以。不过要等到回调的时候才可以拿到儿童的具体票价。

2.请求第三方接口失败怎么办？

若采用的是同步请求机制，请求第三方接口失败【这里的失败是指：第三方没有接收到请求】，那么这个请求是无效的。

个人建议：采用异步请求的方式请求第三方接口。先将请求存放至redis或者RabbitMQ中，然后去请求聚合数据。在这里，尽量把自己的业务和请求第三方的接口区分开来，以此来减少第三方接口的数据造成的影响。还有，尽量使用自己的订单id，不要使用聚合的订单id。

3.第三方接口回调异常怎么办？

聚合火车票接口的回调时间一般在30秒左右，少数在一分钟左右。所以在占座请求、出票请求和退票请求成功后，需要设置接口回调的时间（个人建议90秒）。如果超过回调时间，建议把自己的订单状态直接置为失败（毕竟用户也不能等待太久，这种情况极少出现【但是在高考那两天，不知道怎么回事，下了好几个单子，聚合后台的订单状态一直是处理中，持续了两个小时左右。】），然后再定时请求该订单的订单状态（个人建议定时时间5秒）。若订单状态为占座成功，则调用取消订单接口取消该订单；若订单状态为占座失败，则无需处理；若订单状态仍为处理中，则定时任务继续执行。