火车票抢票API 根据乘客的车次与座席要求快速订票出票:https://www.juhe.cn/docs/api/id/257
1.站站查询
接口地址:http://v.juhe.cn/grabTicket/action/search.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/search.php?from=苏州&to=昆山&date=20161130&type=1&key=你申请的key
接口备注:根据发车站、到达站、发车日期等条件查询所有符合条件的车次信息、票价、剩余票量等信息
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
key | string | 是 | 您申请的key | |
from | string | 是 | 出发地(中文或拼音) | |
to | string | 是 | 目的地(中文或拼音) | |
date | string | 是 | 发车日期,如:20161130 | |
type | int | 否 | 票种类型 ,为空则默认为1 , 1:正常票 2:学生票(暂不支持下单) |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
返回字段及相关数据字典见json示例 |
JSON返回示例:
{ "reason": "0", "result": { "queryKey": "6d31300d58be4d239af4039c71ddc313", //下单接口使用queryKey(重要) "fromStation": "上海西", "fromStationCode": "shanghaixi", "toStation": "苏州园区", "toStationCode": "suzhouyuanqu", "trainDate": "20150514", "pageIndex": 0, "pageSize": 0, "totalCount": 1, "totalSize": 0, "trains": [ { "serialNumber": 1, "trainNo": "G7066", "fromTime": "09:02", //从该站发车时间 "toTime": "09:00", //到达该站时间(如果是首发站则没有到达时间) "fromStation": "上海西", "fromStationCode": "shanghaixi", "toStation": "苏州园区", "toStationCode": "suzhouyuanqu", "runTimeSpan": "28", //历时(分钟) "fromPassType": 1, //发站类别(始、过) 0:始发 1:路过 "toPassType": 1, //到站类别(过、终) 2:终点 1:路过 "bookState": 1, //可预订级别(0:不可预订 1:可预订 2:全部不可预订 3:发车前半小时车次不可预订) "trainClass": "GD" "tickets": { "secondseat": { "seatName": "二等座", "price": 29.5, "seatState": 1, // 0:不可预定 1:可预定 "seats": "490" //余票数量 "upPrice":1029.5,//商铺价格,若无则为0 "midPrice":0,//中铺价格,若无则为0 "downPrice":1075.5//下铺价格,若无则为0 }, "firstseat": { "seatName": "一等座", "price": 49.5, "seatState": 1, "seats": "28", "upPrice":1029.5, "midPrice":0, "downPrice":1075.5 }, "businessseat": { "seatName": "商务座", "price": 99.5, "seatState": 1, "seats": "10", "upPrice":1029.5, "midPrice":0, "downPrice":1075.5 }, "softsleeperdown":{ "seatName":"软卧", "price":1075.5, "seatState":0, "seats":"0", "upPrice":1029.5, "midPrice":0, "downPrice":1075.5 } }, "miles": 0, "pullInByIdCard": 1, "note": "" } ], "froms": [ { "station": "上海西", "location": "" } ], "tos": [ { "station": "苏州园区", "location": "" } ] }, "error_code": 0 }
2.创建抢票单
接口地址:http://v.juhe.cn/grabTicket/action/submitOrder.php
支持格式:json
请求方式:post
请求示例:http://v.juhe.cn/grabTicket/action/submitOrder.php
接口备注:建议先配置回调地址。须知: 1、抢票单仅支持占座和出票合并通知; 2、距离发车时间太近无法抢票,建议距离发车前3小时以上的车次才可创建抢票单;3、在抢票有效时间内会持续抢票,抢票成功后直接出票并推送回调; 4、正在抢票中的订单可以取消,取消后不可再次开启;5、抢票有效时间内未抢到票会主动推送抢票单过期;6、选择备选车次、备选坐席、购买保险等均可提高抢票成功率
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
key | string | 是 | 你申请的key | |
queryKey | string | 是 | QueryKey(注意:这里的querykey一定要与你站站查询的querykey对应) | |
outOrderNo | string | 是 | 外部订单号(6-32位数字英文字母组合) | |
ticketModel | int | 否 | 0:代购模式;1:自购模式(用户使用自己的12306账号进行购买,可以在自己的12306账号下查询所购买车票) | |
accountNo | string | 否 | 12306帐号 | |
accountPwd | string | 否 | 12306密码 | |
trainNo | string | 是 | 车次号 ,如:G7211,如果有多车次请用英文中竖线隔开 | |
seatClassCode | string | 是 | 座席代号,如:firstseat,若有多坐席,请用英文中竖线隔开 | |
mainTrainNo | string | 是 | 主车次,如:G7211,多车次或多坐席时必须指定 | |
mainSeatClass | string | 是 | 主坐席,如:secondseat,多车次或多坐席时必须指定 | |
fromStation | string | 是 | 出发车站名称,中文(请一定要与你站站查询的结果里面的对应车次的fromStation对应) | |
toStation | string | 是 | 到达车站名称,中文(请一定要与你站站查询的结果里面的对应车次的toStation对应) | |
departDate | string | 是 | 发车日期(如果下单成功就可能出票,如果是测试,请至少预定20天以后的票,如果出票成功,请及时退票,具体扣除费用规则请查看12306官网)(如:2016-12-01) 如果选择单车次或者多车次多坐席的时候要传主车次的具体发车时间,(如:2016-12-01 12:00),参数值必须与querykey里的值保持一致 | |
closeTime | string | 是 | 抢票截止时间(格式如:2016-12-01 18:00:00) | |
acceptNoSeat | string | 是 | 是否接受无座,0:不接受 1:接受 | |
person | string | 是 | 联系人姓名 | |
cellphone | string | 是 | 联系人手机 | |
string | 否 | 联系人邮箱 | ||
passengers | json数组 | 是 | 乘客信息(每个订单最多五位乘客),格式如:[{"passengerName": "乘客姓名", "passengerType": "乘客类型 1:成人 2:儿童 3:学生票 4:残军票(暂不支持学生票和残军票)","idCardType": "证件类型 0:身份证 1:护照 2:台胞证 3:港澳通行证", "idCardNo": "证件号码","birthday": "生日" },{"passengerName": "XXX","passengerType": "1","idCardType": "0","idCardNo": "XXXXXXXXXXXXXXXXXXXXXXXXX","birthday": "1989-02-18"}] | |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
见json示例 |
JSON返回示例:
{ "reason": "success", "result": { "orderNo": "TFT583U752U210D284004800356",//内部订单号 "outOrderNo": "2016113001"//订单号(用户自定义) }, "error_code": 0 }
3.订单详情
接口地址:http://v.juhe.cn/grabTicket/action/orderDetail.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/orderDetail.php?outOrderNo=123456&key=你申请的key
接口备注:查询订单的详细信息、车票状态、以及车票号等
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
key | string | 是 | 你申请的key | |
outOrderNo | string | 是 | 订单号 | |
issue | int | 否 | 0:未出票 1:已经出票,默认0(如果订单还未出票则不需要此参数,否则传1,退票时候需要传passengerId,可以通过输入此参数查询,未出票也可以加入此参数,若加上此参数则没有抢票的状态) |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
见json示例 |
JSON返回示例:
未出票(不传issue参数)json示例: ---------------------------------------- { "reason": "success", "result": { "status": "U", "fromStation": "苏州", "toStation": "昆山", "departDate": "2016-12-30T02:29:00", "orderNo": "TFT583U2D6U21011A3068416353", "trainNo": "Z175", "seatClass": "硬座", "passengers": [ { "passengerName": "魏XX", "passengerType": 1, "certificateNo": "320382XXXXXXX3916", "ticketPrice": 0 } ], "phone": "1599XXXXXXX", "mainTrainNo": "", "failMsg": "乘客身份信息未通过验证_订票失败 添加乘客 未通过身份效验 XXX 320382XXXXXXX3916 ", "mainSeatClass": "", "grabEndTime": "2016-11-30T18:00:00" }, "error_code": 0 } 已出票(加issue参数)json示例: ---------------------------------------- { "reason": "success", "result": { "orderNo": "FT584505292101648041264455", "outOrderNo": "2016120501", "trainNo": "K8371", "trainDate": "2016-12-29", "fromStation": "苏州", "toStation": "昆山", "departureTime": "2016-12-29 03:34:00", "arrivalTime": "2016-12-29 03:58:00", "orderState": "已出票", "orderStateCode": "F", "failureReason": "", "bookTime": "2016-12-05 14:11:52",//可忽略 "payTime": "2016-12-05 14:13:13",//可忽略 "issueTime": "2016-12-05 14:13:13", "payType": "暂存单支付",//可忽略 "orderPrice": "9.00", "ticketNo": "E345091034", "placeTime": "2016-12-05 14:12:29",//可忽略 "payStatus": "0",//可忽略 "payInfo": "",//可忽略 "passengers": [ { "passengerId": "623838773", "passengerName": "XXX", "passengerType": "1", "idType": "1", "idCard": "XXXXXXXXXXXXXXXXXX", "birthday": "1976-06-13", "seatClass": "hardseat", "seatClassName": "硬座", "seatNo": "07车厢,009号", "pTicketNo": "E3450910341070009", "ticketStateCode": "F", "ticketState": "已出票", "ticketPrice": "9.00", "insureUnitPrice": "0.00",//可忽略 "insureState": null,//可忽略 "insureBillNo": null//可忽略 } ], "contactInfo": { "person": "1599****577", "cellphone": "1599****577", "email": "" }, "postalInfo": {//可忽略 "person": null, "cellphone": null, "province": null, "city": null, "district": null, "address": null, "zip": null }, "juheServiceFee": "8" }, "error_code": 0 }
4.取消订单
接口地址:http://v.juhe.cn/grabTicket/action/cancelOrder.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/cancelOrder.php?outOrderNo=123456&key=你申请的key
接口备注:正在抢票中的订单可以取消,取消后的订单不再抢票; 取消前提: 1、订单还未抢到票; 2、抢票单未过期;
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
outOrderNo | string | 是 | 订单号 | |
key | string | 是 | 您申请的key |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
见json示例 |
JSON返回示例:
取消失败: { "reason": "抢票取消失败", "result": null, "error_code": 223801 } 取消成功: { "reason": "success", "result": { "orderNo": "TFT583U7A64210D1BB016912627" }, "error_code": 0 }
5.申请退票
接口地址:http://v.juhe.cn/grabTicket/action/applyRefundOrder.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/applyRefundOrder.php
接口备注:对已出票的订单发起退票请求,只支持每次申请1名乘客退票,接口返回申请结果,实际退票结果通过消息推送进行异步通知; 退票成功后会自动给用户退保,无需分销商主动申请,退保结果通过消息推送进行异步通知;
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
key | string | 是 | 你申请的key | |
outOrderNo | string | 是 | 订单号 | |
passengerId | string | 是 | 乘客id |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
见json示例 |
JSON返回示例:
失败: { "reason": "参数错误:订单号或passengerId不存在", "result": null, "error_code": 223804 } 成功: { "reason": "success", "result": { "orderNo": "TFT583U7D552101629055112720", "passengerId": "615151438" }, "error_code": 0 }
6.配置回调地址
接口地址:http://v.juhe.cn/grabTicket/action/addCallbackUrl.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/addCallbackUrl.php?url=xxxx&type=1&key=您申请的key
接口备注:配置回调地址,如果出票失败,可以通过订单详情查看失败原因
调用样例及调试工具:
API测试工具
请求参数说明:
名称 | 类型 | 必填 | 说明 | |
---|---|---|---|---|
key | string | 是 | 你申请的key | |
url | string | 是 | 回调地址 | |
type | string | 是 | 回调类型(1:占座和出票结果合并推送(包含成功和失败); 2:退票退款推送 ;3:抢票过期推送 ) |
返回参数说明:
名称 | 类型 | 说明 | |
---|---|---|---|
见json示例 |
JSON返回示例:
配置成功json示例: ---------------------------------------- { "error_code": 0, "reason": "success", "data": null } 出票成功推送示例: ---------------------------------------- { "orderNo": "TFT583U7D552101629055112720", "outOrderNo": "2016113006", "msgCode": "100",//详见下方字段说明 "msgInfo": "出票成功", "fromStationCode": "226", "toStationCode": "226", "departureTime": "2016-12-29 02:29:00",//发车时间 "arrivalTime": "2016-12-29 02:53:00",//到达时间 "trainNo": "Z175", "ticketNo": "E566781381",//票号 "orderAmount": "9.00",//订单价格 "fromStation": "苏州", "toStation": "昆山", "issueTime": "2016-11-30 15:21:53",//出票时间 "mailCharge": "0.00",//邮寄费用,可忽略 "msgDetail": null,//msgDetail有值时表示该失败原因针对这些乘客,格式:姓名|证件号,姓名|证件号 "passengers": [ { "passengerName": "奥巴马", "passengerType": "1", "cardType": "1", "cardNo": "xxxxxxxxxxxxxxx", "passengerId": "615151438", "seatClass": "1", "seatNo": "02车厢,007号", "price": "9.00", "pTicketNo": "E5667813811020007", "serviceCharge": "0", "insuranceCharge": "0.00" } ], "isChangedOrder": "0", "originalOrderNo": "", "changedType": "", "serviceCharge": "", "changePriceDiff": "", "juheServiceFee": "8" } 出票失败推送示例: ---------------------------------------- { "orderNo": "TFT583U752U210D284004800356", "outOrderNo": "2016113001", "msgCode": "101",//详见下方 "msgInfo": "出票失败", "fromStationCode": null, "toStationCode": null, "departureTime": null, "arrivalTime": null, "trainNo": null, "ticketNo": null, "orderAmount": null, "fromStation": null, "toStation": null, "issueTime": "", "mailCharge": null, "msgDetail": null, "passengers": [ { "passengerName": "张三", "passengerType": "1", "cardType": "1", "cardNo": "XXXXXXXXXX", "passengerId": "123",//退票时候需要此字段 "seatClass": "1", "seatNo": "", "price": "100.00", "pTicketNo": "", "serviceCharge": "0", "insuranceCharge": "0.00" } ], "isChangedOrder": "0", "originalOrderNo": "", "changedType": "", "serviceCharge": "", "changePriceDiff": "", "juheServiceFee": "0" } 订单过期推送示例: ---------------------------------------- { "msgCode": "101", "msgInfo": "抢票单过期", "orderNo": "TFT583U7C4921011A3062532520", "outOrderNo": "2016113005" } 退款成功推送示例: ---------------------------------------- { "orderNo": "TFT583U7D552101629055112720", "outOrderNo": "2016113006", "refundTime": "2016-11-30 15:32:00", "refundPrice": "9.00", "refundType": "online", "passengers": [ { "passengerId": "615151438", "pTicketNo": "E5667813811020007", "passengerName": "奥巴马", "passengerType": "1", "cardType": "1", "cardNo": "", "refundPrice": "9.00" } ], "msgCode": "100", "msgInfo": "线上退票成功" } 退款失败推送示例: ---------------------------------------- { "msgCode": "101", "msgInfo": "参数无效", "orderNo": "FT123456789", "outOrderNo": "XXXXXX", "refundTime": "2016-06-22 09:56:16", "refundPrice": "0.00", "refundType": "online", "passengers": [ { "passengerId": "123", "passengerName": "张三", "passengerType": "1", "cardType": "1", "cardNo": "", "refundPrice": "0.00", "pTicketNo": "E1234567890001" } ] }
7.数据字典
接口地址:http://v.juhe.cn/grabTicket/action/dataDictionary.php
支持格式:json
请求方式:get post
请求示例:http://v.juhe.cn/grabTicket/action/dataDictionary.php?key=你申请的key
接口备注:返回接口相关的字段使用场景及含义
调用样例及调试工具:
API测试工具
JSON返回示例:
{ "reason": "success", "result": { "tips": [ "抢票单暂时不可以购买保险", "抢票单目前最多支持五名乘客", "抢票单目前暂不支持学生票和残军票", "选择备选车次、备选坐席等均可提高抢票成功率", "申请退票流程是针对订单中的车票而非针对订单", "申请退票只支持单张车票,如多人退票需每张车票单独申请", "测试单请创建发车日期在20天以后的,因为会产生真实的费用", "在抢票有效时间内会持续抢票,抢票成功后直接出票并回调给用户", "抢票有效时间内未抢到票,我们会主动推送抢票单过期信息", "正在抢票中的订单可以取消,取消后不可再次开启。建议您不要轻易取消抢票", "抢票单默认使用合并推送,用户需要提供占座和出票合并网关以便正常接收到数据", "距离发车时间太近无法抢票,建议用户限制距离发车前3小时以上的车次才可创建抢票单", "抢票单的订单状态可以调用订单详情接口查看,抢票成功后更为详尽的订单信息可调用订单详情接口获取,此时需要加上issue参数" ], "idType": { "msg": "证件类型,一般用在创建订单的idType字段", "data": { "1": "身份证", "2": "护照", "3": "台胞证", "4": "港澳通行证" } }, "passengerType": { "msg": "乘客类型,一般用在创建订单的passengerType字段", "data": { "1": "成人", "2": "儿童", "3": "学生票", "4": "残军票" } }, "refundType": { "msg": "退款类型,一般用在退款结果推送接口", "data": { "0": "change:改签差价退款", "1": "repeatpay:重复支付退款", "2": "delaypay:延迟支付退款", "online": "线上退票退款", "offline": "车站退票退款", "issuefail": "出票失败退款", "other": "其他原因退款" } }, "seatClass": { "msg": "一般用在回调出票成功后的passengers数组中的seatClass中", "data": { "1": "硬座", "2": "软座", "3": "一等座", "4": "二等座", "5": "硬卧上铺", "6": "硬卧", "7": "硬卧下铺", "8": "软卧上铺", "9": "软卧", "10": "无座", "11": "商务座", "12": "特等座", "13": "其它", "14": "高级软卧", "15": "动卧上铺", "16": "动卧下铺", "17": "高级动卧上铺", "18": "高级动卧下铺", "33": "一等软座", "44": "二等软座" } }, "seatClassCode": { "msg": "一般用在站站查询返回的json数据及创建订单时候的seatClassCode和mainSeatClass字段", "data": { "hardseat": "硬座", "softseat": "软座", "firstseat": "一等座", "secondseat": "二等座", "hardsleeperup": "硬卧上铺", "hardsleepermid": "硬卧中铺", "hardsleeperdown": "硬卧下铺", "softsleeperup": "软卧上铺", "softsleeperdown": "软卧下铺", "noseat": "无座", "businessseat": "商务座", "specialseat": "特等座", "advancedsoftsleeper": "高级软卧", "otherseat": "其他" } }, "trainClass": { "msg": "一般用在站站查询返回的json数据中的trains数组中的trainClass字段", "data": { "C": "城际高速", "D": "动车组", "KT": "空调特快", "KKS": "空调快速", "KPK": "空调普快", "KPM": "空调普慢", "KS": "快速", "PK": "普快", "PM": "普慢", "XGZ": "香港直通车", "Z": "直达特快", "GD": "高速动车" } }, "ticketStateCode": { "msg": "一般用在订单详情接口返回json数据中的passengers数组中的ticketStateCode字段(如无,请忽略)", "data": { "N": "未出票", "F": "已出票", "C": "退票中", "T": "已退票", "O": "退票失败", "Y": "改签中", "G": "已改签" } }, "orderStatus": { "msg": "一般用在订单详情接口返回的json数据中的grabOrderDetailInfo中的status字段", "data": { "N": "抢票单已创建", "B": "未到开抢时间", "D": "抢票中", "F": "抢票成功(出票成功)", "U": "出票失败", "O": "已过期", "C": "已取消", "T": "已退票", "E": "已改签" } }, "msgCode": { "msg": "一般用在回调接口中(所有的回调的接口),所有的状态都是有可能返回的", "data": { "100": "请求成功", "101": "参数无效", "102": "签名验证失败", "103": "该IP没有权限访问此接口", "104": "请求过于频繁,请稍后重试", "105": "没有权限访问此接口", "201": "该订单不存在", "202": "当前订单状态不允许执行此操作", "203": "当前时间不支持此服务", "204": "坐席无效", "205": "发车日期无效", "206": "取消次数过多,取消请求已锁定", "207": "订单已过期", "208": "车次号无效", "209": "该坐席已售完", "210": "该账号有未完成的订单,无法继续执行此操作", "211": "分销商身份验证无效", "212": "该订单未付款,无法出票", "213": "坐席价格错误", "214": "占座排队中,请等待占座结果", "215": "站站查询结果已过期,请重新查询", "216": "距离发车时间太近,无法执行此操作", "217": "实际占座为无座,乘客制定不接受无座", "218": "测试订单不允许预定20天以内发车的车次", "219": "抢票单已达预约上限", "220": "抢票单乘客数,车次数,坐席数超过配置上限", "221": "抢票取消失败", "222": "抢票功能关闭", "301": "该订单中无此乘客", "302": "乘客身份信息涉嫌被他人冒用", "303": "当前车票状态不允许执行此操作", "304": "乘客信息不正确", "305": "乘客已预订过与该行程有冲突的车票", "306": "乘客已被法院依法限制高消费", "307": "乘客已预订过该车次,无法重复预订", "308": "乘客身份信息未通过验证", "309": "出票5分钟内无法提交退票", "310": "距离发车时间太近,无法申请退票", "311": "订单中包含儿童票,如需退票请先退儿童票", "312": "不支持网上退票", "313": "订单中包含儿童票,该乘客无法改签", "314": "距离发车时间太近,无法改签", "315": "要改签的车次不在预售期内,无法改签", "316": "该订单不支持改签", "317": "改签次数过多,改签请求已锁定", "318": "当天取消改签次数过多,取消请求已锁定", "319": "购保失败", "320": "退保失败", "401": "购票所使用的12306账号未进行手机核验", "402": "购票所使用的12306账号被封,无法执行此操作", "403": "12306账号登录失败", "404": "12306账号尚未激活,请用注册时的邮箱激活后重试", "405": "12306账号未通过身份信息核验,请核验后重试", "406": "12306账号已被锁定", "407": "登录验证码错误", "408": "12306账号格式不正确", "409": "12306账号常用联系人已达上限,无法继续添加", "410": "当日获取短信验证码次数已达上限", "411": "邮箱已被注册", "412": "用户名已被注册", "413": "手机号码已被注册", "414": "证件号码已被注册", "415": "12306账号不可用", "416": "手机号或证件号码不正确", "417": "该联系人已存在", "999": "未知的失败原因" } } }, "error_code": 0 }