[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排。