火车票订票接口常见问题

  在开始开发前,建议您先移步 http://www.12306.cn/mormhweb/tlcs/ 了解铁路订票相关的的基本常识。


  由于火车票系统较为复杂,做出一个完整的产品,需要技术、客服、商务等人员的参与,所以目前仅对企业用户开放。

  开发一个火车票订票系统需要较多的软件开发经验,我们不建议初学者拿本项目作为练习,我们也不能为您提供全方位的指导,若您没有足够的自信和潜力还请三思。

  考虑到后期的运营、财务、维护等方面的问题,我们不建议您将该系统的开发通过外包完成。

  若在开发和运营中遇到问题,请先查阅本文档。


1、整个订票的流程是什么?

  • 查车站简码

    • 可通过https://www.juhe.cn/docs/api/id/173查询单个或全部车站的简码

    • 建议将车站简码缓存或存数据库,不必每次都查

    • 如果您确定某个车站存在,却查不到简码,请联系我们核实

  • 查余票

    • 注意:查余票功能与12306官网结果一致,比如查苏州到上海的火车,结果中会出现苏州到上海虹桥的车次

  • 提交订单

    • 提交订单的过程中,大多数用户都会遇到参数格式不对之类的问题,还请您多读、多理解官方文档中的说明

    • 务必注意:

    • 如果上一步查的是苏州到上海的余票

    • 根据实际情况决定选择苏州到上海虹桥这段乘车区间

    • 那么提交订单时请将乘车区间设为苏州到上海虹桥,而不是查余票时的苏州到上海

  • 提交成功后该如何知道这笔订单的处理状态?

    • 有两种方式:您主动查询(通过订单查询API https://www.juhe.cn/docs/api/id/173/aid/583)和我们推送(回调)给您,关于推送请阅读本文第19、20、21、22条

    • 订单状态为0:表示待处理,处理完会变成1(占座失败)或2(占座成功)

    • 请注意:提交订单成功不代表占座成功,提交订单成功后我们会立刻处理您的需求

    • 查看订单的处理结果,如果为失败(1),则此订单结束,请重新下单

    • 由于订单的处理结果不是立刻返回的,请您阅读本文第19、20、21、22条中关于推送的说明

  • 取消订单或者支付订单

    • 如果占座成功,可以在规定时间内(即在12306官网购票时的支付倒计时时间,目前是30分钟,按照12306的规定,可能会变)取消订单,关于支付的超时时间请阅读第5条

    • 或者请求支付订单(会从您的聚合余额中扣费,请保证余额充足,此处也请您好好想想如何扣除自己用户的费用,若想不明白请看第24条)

  • 退票

    • 如果出票成功,但是用户还未到火车站取票,可以通过我们的接口申请退票

    • 如果用户已取票且需要退票

    • 这时候用户已经拿到了纸质车票

    • 是无法在线退票的

    • 需要用户自行去火车站窗口处理

    • 这种方式需要您公司的客服来通知我们的客服去核实退款,核实无误后我们会将款项加到您的聚合账户中

    • 针对退票的问题,第16、17条有详细的说明

  • 请把以上内容再读三遍

2、我想测试一下买票,不是真的买,有测试环境吗?

  • 暂不提供测试环境,您可以先买票,再退票

  • 按照12306的相关规定,有些退票是不收取费用的 http://www.12306.cn/mormhweb/tlcs/201505/t20150512_16615.html

  • 一些比较便宜的车票可供您测试:

    • 1、车次6225,从哈尔滨东至滨江,硬座票价1元

    • 另外,如果您退掉这张车票,可能会发现退款为0.00元

    • 并不是没有退款

    • 而是手续费为2元,远大于票价的1元

    • 2、车次G7075,上海西至上海,二等座票价8.5元

3、从提交订单到完成订票需要多长时间?

    以下仅作参考,还请以实际情况为准

  • 提交订单到处理完占座:大多数处理时间在30秒内,少数1分钟左右

    • 特殊情况,火车票官方订票系统会在每天23点(也许以后会改)关闭,如您在23点左右提交订单,此订单可能要到第二天早上才能处理完成

  • 申请出票到出票成功:一般在30秒内

  • 线上申请退票到处理完线上退票:一般5分钟内

  • 告知聚合客服用户已线下退票到核实退票完毕:此流程人工完成,取决于您的客服和我们客服的对接速度

4、订单状态为下单失败,原因是什么?

  • 选择的车次不经过参数中的站点,如G101车次不经过北京站(经过北京南站),您却非要订北京站的票,请务必注意

  • 使用了不真实的身份证号

  • 未到起售时间

  • 行程冲突

  • 乘客身份信息未通过验证_订票失败......:证件号码错误;第一次在网上订票,请到火车站核验身份

  • XX_身份信息涉嫌被他人冒用......:请到火车站核验身份

  • 待您的系统开发完成后,订单失败的原因大多是订票用户的身份问题

  • 如有必要,请联系我们查询详细原因

5、多长时间不支付会超时?

6、订票完成后会有短信或者邮件通知吗?如何确定订票是成功的?

  • 我们为您提供火车票订票服务,并不与您的产品的用户接触

  • 订票成功后聚合不会发出任何通知,只会将您的订单状态改为成功状态

  • 当您查询订单(或通过推送),得知状态为出票成功时,即订票成功

  • 如实在需要确认,可打12306电话查询,但在12306网站是查不到的

    • 这是为什么?

    • 我们提供的是代购服务

    • B让A为其买一张火车票

    • A用自己的12306账号登录12306官网,为B购买车票

    • 这时候B是收不到通知的

  • 为了提供更好的用户体验,您可为自己的产品开发短信或邮件提醒功能,我们也同样提供了短信接口(需要您自己集成)

7、如何购买无座的票?

  • 不同于12306,在我们平台,无座票存在的唯一意义是:当最低座次票卖完时,用户若选择了该最低座次,出无座票

  • 所以无法指定购买无座票

  • 最低座次(有些车是二等座,有些是硬座)有座票没卖完,无论如何都不会出无座的票

  • 最低座次有座的票卖完,如果您接受自动抢无座票,则出无座票

8、我提交订单的时候要求硬座,怎么给我占到了无座?

  • 请先仔细阅读上一条

  • 当硬座(最低座次)卖完了,您还选硬座(最低座次),且接受自动抢无座票,就出无座票

  • 如果觉得不合适,可以申请取消订单

9、票量不足时会出现什么情况?

  • 假设您为两个乘客购买G123的二等座

  • 如果此时仅有1张无座,会返回占座失败,无余票

  • 如果此时有1张二等座、100张无座,那么占座结果可能是:1张二等座,1张无座;两张无座

10、购买儿童票需要身份证吗?儿童如何购买火车票?

  • http://www.12306.cn/mormhweb/tlcs/201505/t20150512_16607.html

  • http://www.12306.cn/mormhweb/tlcs/201505/t20150512_16608.html

  • 儿童有有效身份证件的,可用儿童证件购票;

  • 儿童没有有效身份证件的,用同行成年人身份信息(姓名、证件类型、证件号码均为同一成年人)购票

  • 一名成年人旅客可以免费携带一名身高不足1.2米的儿童。如果身高不足1.2米的儿童超过一名时,一名儿童免费,其他儿童请购买儿童票。儿童身高为1.2~1.5米的,请购买儿童票;超过1.5米的,请购买全价座票。

  • 成年人旅客持卧铺车票时,儿童可以与其共用一个卧铺,并按上述规定免费或购票。

11、退票的费用是多少?

12、儿童可以单独乘车吗?

  • 不可以

13、一个订单中有一个成人和一个儿童,成人退票后儿童不就单独乘车了?

  • 这个时候成人退票原则上是允许的,但是儿童能不能单独乘车就要看当地安检放不放行了

14、几个订单号的说明

  • orderid:您和聚合交互时使用的订单号,我们双方的客服通过此订单号进行交流

  • user_orderid:您自定义的订单号,具体用途由您决定,每个user_orderid应对应唯一orderid

  • ordernumber:12306的订单号,等同于我们在12306官网订票时的订单号,如果您的用户去火车站窗口查询订单信息,可能会被要求提供此订单号,注意和乘客信息中ticket_no的区别

  • ticket_no:车票号,一个ordernumber下可能会有多个ticket_no(多个乘客,每人对应一个ticket_no),线上退票时(退票针对乘客,不针对订单)会用到此车票号

  • 请将以上内容读三遍

15、关于硬卧的说明

  • 接口中会返回硬卧上、中、下铺的价格

  • 但订票时上、中、下铺是随机分配的

  • 所以对于硬卧,提交订单时座次设为硬卧(不区分上、中、下铺),价格设为余票接口中返回的yw_price的值

  • 占座成功后,会返回具体占到了上、中、下铺中的哪一个,以及准确的价格

16、关于退票的说明1

  • 退票分为两种方式

  • 线上退票(用户还未取票,自己点您产品上的某个按钮申请退票):通过我们提供的退票接口退票,全自动,处理速度较快,退款会及时退还到您的聚合账户

  • 线下退票(用户已经取票):

    • 用户自己持票去火车站窗口退票,这种方式火车站不会主动告诉我们用户已经退票

    • 所以需要您的用户主动告诉您的客服(一般通过QQ,具体方式由您定):我自己在火车站退票了,订单号是XXXX

    • 然后您的客服主动告诉聚合客服(一般通过QQ群):订单号XXXX已经线下退票,请核实退款

    • 聚合客服再去找12306核实退票信息

    • 无误后会将款项返还至您的聚合账户,并通知您的客服

    • 然后需要您的客服将款项退还给您的用户

    • 您的客服如何退款给您的用户由您自己决定

    • 过程比较繁琐,所以我们建议尽量避免线下退票

17、关于退票的说明2

  • 一个订单中可能有多个乘客,所以可能存在A乘客已经取票、B乘客已经退票的情况

  • 退票针对票(乘客),不针对订单

  • 退票的手续费由12306规定和收取,与你我无关

  • 钱从哪里来的,就回到哪里去

  • 请将以上内容读三遍

18、关于退款的说明

  • 订单详情中返回的refund_money字段是累积退款金额,比如

  • 一个订单中有乘客A和B,票价是5元

  • 那么订单总金额(orderamount)是10元

  • 乘客A退票,12306扣手续费2元,此时refund_money是3元

  • 乘客B退票,12306扣手续费2元,此时refund_money是6元

19、什么是推送?为什么要设置推送?

  • 您提交了一个订票请求

  • 我们不能马上告诉您这个请求的处理结果,而是需要一段时间来处理

  • 待我们处理完,会主动访问您提供的一个地址,并将最新的订单信息以post的形式传递过去

20、关于推送,您需要到   http://www.juhe.cn/docs/api/id/173/aid/687  配置三个回调地址

  • submit_callback(如:http://a.com/juheTrainTickets/submit_callback):

    提交订单后,订单处理完成会将订单信息推送到此地址

  • pay_callback(如:http://a.com/juheTrainTickets/pay_callback)

    请求出票(支付)后,处理完出票请求,会将订单信息推送到此地址

  • refund_callback(如:http://a.com/juheTrainTickets/refund_callback):

    有退票、改签等涉及到退款的事件发生时,会将订单信息推送到此地址

21、您对推送信息的处理

  • 处理完推送的信息,请输出:success(全小写,不要在success两侧加引号)

  • 若处理有误,您可输出调试信息

  • 我们会将您的输出记录下来

  • 若不输出success,会重试推送

  • 最多推送3次

  • 因为会多次推送,请在程序中做好判断,比如:

  • 只有刚提交的订单才能接受占座回调(submitCallback)

  • 只有待出票的订单才能接受出票回调(payCallback)

  • 等等

22、推送信息的格式

  • 推送的信息等同于查询订单接口返回的信息,请到 https://www.juhe.cn/docs/api/id/173/aid/583 查看各个字段的详细说明

  • 在订单发生变化时,我们会按照如下格式,将信息推送到您配置的地址

  • 请求方式:post

  • 推送的信息(仅用于说明,以您实际获取到的信息为准,以后可能会增加字段):

  • data={    
        "from_station_name":"苏州",   
        "from_station_code":"SZH",   
        "to_station_name":"上海",    
        "to_station_code":"SHH",   
        "train_date":"2015-09-25",    
        "orderid":"1442992371987",    
        "user_orderid":"",    
        "orderamount":null,   
         "ordernumber":null,    
         "checi":"C6207",   
         "msg":"乘客身份信息未通过验证_订票失败  添加乘客 未通过身份效验 方辉321201198610012345",    
         "status":"1",    
          "passengers":       
           [          
               {               
                   "passengerid":"1123",               
                   "passengersename":"方辉",              
                   "piaotype":"1",               
                   "piaotypename":"成人票",               
                   "passporttypeseid":"1",               
                   "passporttypeseidname":"二代身份证",               
                   "passportseno":"321201198610012345",                
                   "price":"763.5",               
                   "zwcode":"O",                
                   "zwname":"二等座"            
                }       
          ],    
          "refund_money":null,    
          "sign":"1e59b1821fcab4d9fb2a00d1112e9dbc"
    }
  • 其中:

  • sign=md5('juhe'+您的key+orderid+user_orderid)  /*加号只是为了告诉您这几个值需要连接起来,加号不是md5加密的内容*/
    from_station_name:出发站
    from_station_code:出发站简码
    to_station_name:到达站
    to_station_code:到达站简码
    train_date:出发日期
    orderid:您与聚合交互时的订单号
    user_orderid:您与用户交互时的订单号
    orderamount:订单总金额
    ordernumber:取票号
    checi:车次
    msg:订单的提示信息
    status:订单的状态码
    passengers:乘客信息
    refund_money:此订单累积退款金额

23、聚合是怎么扣的我的钱?

  • 您提交订单:此时不涉及到钱

  • 我们处理完此订单,处理结果为占座成功:此时不涉及到钱

  • 您通过我们的接口请求出票,我们尝试从您的聚合账户扣除订单的钱

  • 若您余额不足,请求出票后接口会立刻返回:您的余额不足,不能出票之类的提示

  • 若您余额充足,请求出票后接口会立刻返回:“已接收出票请求”或者“请求出票失败”

  • 如果是“请求出票失败”(注意是“请求出票失败”不是“出票失败”),这时候聚合会退回刚才扣的钱

  • 如果是“已接收出票请求”,接下来我们便会处理出票的请求(从付钱成功到出票成功需要一段时间)

  • 我们处理出票的结果是:出票成功或者出票失败

  • 当然,如果出票失败会给您退钱

  • 所以,请您务必想清楚如何扣自己用户的钱

24、我怎么扣我的用户的钱?

  • 我们仅提供订票的服务,不与您的用户接触

  • 我们只会扣除您在聚合预存的金额

  • 您如何扣自己用户的钱与我们无关

  • 但是知识是不分场合的,我们可以提供一些方案供您参考

    • 1.1、当您发现订单状态是占座成功待支付时,允许您的用户申请出票(付钱)

    • 1.2、引导您的用户付钱(通过支付宝、财付通、银联等)给您

    • 1.3、确定付钱成功后,向聚合申请出票

    • 1.4、若聚合返回申请出票失败,您还需要考虑如何给用户退钱

    • 2.1、或者采用更简单的预付费方案

    • 2.2、先让用户在您的平台存足够的钱

    • 2.3、用户申请出票后从其余额扣钱

    • 2.4、扣钱成功后再向聚合申请出票

25、我怎么知道占座成功还是失败?怎么知道出票成功还是失败?怎么知道......

  • 请花15分钟时间理解一下第一条

26、提供抢票服务吗?

  • 不提供

  • 准确的说,我们提供的是代购服务

27、只有占座成功(状态为2)的订单才可以支付,当前订单状态:0

  • 字面意思

28、聚合能不能帮我......

  • 不是所有的愿望都能得到满足

  • 这也是我们不断奋斗的原因

29、提交订单成功,程序自动排队,未获取到订单号,可能情况:1、占座失败;2:超过程序排队时间设定,还在排队中。

  • 此条信息表示处理占座信息失败

  • 若同意乘客再次下单,会提示:乘客已预定该车次

  • 遇到这种情况,请该乘客45分钟后再试

30、用户自己持票去火车站窗口退票,钱退到哪里去了?

  • 请再看一遍第17条关于线下退票的说明

  • 请记住:钱从哪里来的,就退到哪里去

31、订单1234567890123中不存在您提供的tickets参数中指定的可退的车票

  • 如果您非常确定是按照官网文档中指定的方式,并且传对了参数

  • 请读第14条,确认一下是否搞清楚了各个订单号的区别

32、关于提交订单时涉及到的免费出行险的说明(如在2017年8月8号后接入,请忽略此条)

  • 文档中已明确说明:该保险为可选内容

  • 若提供了需要保险的乘客的信息,且返回了保险的单号,平安保险相关人员会主动通过参数中传递的手机号联系该乘客

  • 有关于该保险的事项将由平安保险告知乘客

  • 如您需要了解详细信息,请联系客服

33、支付成功了,请求出票后发现出票失败

  • 已证实有极小概率出现此事件

  • 很有可能是支付时已经超时了

  • 如有必要请提供单号,联系客服

34、火车票线上提交退票请求,大概需要等多久可以退票成功

  • 请读第3条

35、某某票的票价是怎么规定的?退票的手续费是多少?......

36、关于订单详情中某张票的returntickets和refundTimeline字段的说明 

  • returntickets:受12306系统调整的影响,2016年2月1日后,此字段作废,但老用户不受影响

  • refundTimeline:记录这张车票的退款事件。

  • 比如:

  • 车票A是一张从北京到苏州的车票,并且已经出票成功

    • 乘客去火车站取此车票

    • 乘客决定改签,改为从北京到南京

    • 此时应有一笔退款(北京到苏州比北京到南京远)

    • refundTimeline里应该增加一条退款事件,大致内容为:线下改签退款

    • 后来,乘客去火车站退掉了这张北京到南京的车票

    • refundTimeline里应该增加一条退款事件,大致内容为:线下退票成功

  • 车票B是一张从北京到上海的车票,并且已经出票成功

    • 用户还没有到火车站取票

    • 用户申请在线退票

    • refundTimeline里应该增加一条退款事件,大致内容为:线上申请退票

    • 待聚合处理完此线上退票申请后

    • refundTimeline里应该增加一条退款事件,大致内容为:线上退票成功(也可能是失败)

  • 车票C是一张从北京到海口的车票,并且已经出票成功

    • 用户去火车站取票

    • 用户去火车站退票

    • 待聚合核实已经退票后

    • refundTimeline里应该增加一条退款事件,大致内容为:线下退票成功

37、我应该扣自己的用户多少钱?

  • 订单详情里orderamount字段即为该订单的总金额

38、XXX已订XX月XX日的G123的车票

  • 在提交此订单前,您预订了同一日期的火车车票

  • 一个人是不可能在同一时间乘坐两辆火车的

  • 所以下单失败

39、聚合的手续费与12306的手续费

  • 我们为您提供订票服务,需要按订单收取费用

  • 当您申请出票,且出票成功时,系统会自动扣除一个订单的手续费(具体每单的手续费多少请咨询客服)

  • 暂无其它需要扣“聚合手续费”的地方

  • 12306的手续费主要指退票的手续费,如果12306扣除了退票手续费,则退款金额会小于订单金额

40、我提交一张购买了两张票的订单后,有没有可能一个人占座失败,另一个人占座成功的?

  • 没有

41、请求出票回调,假如有一个乘客出票成功,有一个乘客出票失败,会有这样的情况吗

  • 没有

42、也是要么两张出票成功,两张出票失败是吗?

43、关于选座的说明

  • 一个乘客,想要编号为A的座位

    • choose_seats=1A

  • 一个乘客,想要编号为F的座位

    • choose_seats=1F

  • 两个乘客,想要邻近的AB两个座位

    • choose_seats=1A1B

  • 两个乘客,一个想要F,一个想要下一排的A

    • choose_seats=1F2A

  • 五个乘客,想坐一排

    • choose_seats=1A1B1D1E1F

  • 五个乘客,想占用两排

    • choose_seats=1B1D1E1F2A

    • choose_seats=1E1F2A2B2D

    不管多少个乘客,不允许占用3排。





登录 后可发表评论

    最新发布
    聚合数据©版权所有