火车票服务端集成总结

一、环境准备

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

2.短信接口；

3.支付接口。

二、买票流程

（参考聚合官方文档，火车票订票接口常见问题：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.儿童票

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