[TOC] 在开始开发前，建议您先移步 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、多长时间不支付会超时？ 该项由12306规定，请参考 http://www.12306.cn/mormhweb/kyfw/question/201505/t20150511_16455.html 目前是30分钟 当订单超时后，12306不会主动告诉我们该订单已超时 所以您不申请支付，订单会一直处于待支付状态 超时后您申请支付，会提示出票失败已超时等类似信息 ## 6、订票完成后会有短信或者邮件通知吗？如何确定订票是成功的？ 我们为您提供火车票订票服务，并不与您的产品的用户接触 订票成功后聚合不会发出任何通知，只会将您的订单状态改为成功状态 当您查询订单（或通过推送），得知状态为出票成功时，即订票成功 如实在需要确认，可打12306电话查询，但在12306网站是查不到的 这是为什么？ 我们提供的是代购服务 B让A为其买一张火车票 A用自己的12306账号登录12306官网，为B购买车票 这时候B是收不到通知的 为了提供更好的用户体验，您可为自己的产品开发短信或邮件提醒功能，我们也同样提供了短信接口（需要您自己集成） https://www.juhe.cn/docs/api/id/54 ## 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、退票的费用是多少？ http://www.12306.cn/mormhweb/tlcs/201505/t20150512_16615.html 退票的费用由12306规定和收取 您买一张2元的票，退掉，发现您的余额并没增加，并不是因为没退钱 而是2元还不够扣退票的手续费 ## 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、某某票的票价是怎么规定的？退票的手续费是多少？...... 请查阅http://www.12306.cn/mormhweb/tlcs/ 如不能解决，请咨询12306 ## 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排。