12306数据接口API(草稿)

简化12306接口，规范属性名称，用于数据库设计，数据接口定义

数据定义

命名规则

该协议对12306原始数据的命名做了适当简化，例如原始passenger种的名字为passenger_name，现直接改为name。另外像原始数据种seat_no这种也直接做了简化，变成seat，seat_name不变。数据中有很多成对出现的属性比如type, type_name，都做了统一规范，第一个表示id，加上_name表示名称。

Passenger

乘客，联系人

属性名	类型	描述
key	String	id_type,id_no,name组成的唯一key
name	String	姓名
id_type	Int	证件类型
id_type_name	String	证件类型名称
id_no	String	证件号码
birthday	String	出生日期
sex	String	性别 M, F
sex_name	String	性别男，女
mobile	String	手机号
phone	String	电话号
email	String	电子邮件
address	String	地址
status	Int	核验状态{0:未知,1:已通过,2:未通过,3:待核验,4:未通过,5:请报验}
status_name	String	状态名称
status_detail	String	状态描述
type	Int	乘客类型
type_name	String	乘客类型名称
school_name	String	学校名称
school_code	String	学校代码
school_province	Int	学校省份
school_province_name	String	学校省份名称
school_department	String	院系
school_class	String	班级
school_id	String	学号
school_system	String	学制
school_enter_year	String	入学年份
school_preference_no	String	优惠卡号
school_preference_from_name	String	优惠出发地名称
school_preference_from	Int
school_preference_to_name	String	优惠目的地名称
school_preference_to	Int

{
	"name": "蔡箐",
	"id_type": "1",
	"id_no": "360702199203091322",
	"type": "3",
	"status": 1,
	"status_name": "预通过",
	"status_detail": "",
	"mobile": "13720067708",
	"address": "",
	"birthday": "2012-12-14",
	"id_type_name": "二代身份证",
	"type_name": "学生",
	"key": "1-360702199203091322-蔡箐",
	"self": false,
	"ticket_type_name": "学生票",
	"sex": "F",
	"sex_name": "女",
	"school_province": "11",
	"school_code": "10005",
	"school_id": "20012",
	"school_enter_year": "2014",
	"school_preference_no": "",
	"school_preference_to": "2006",
	"school_preference_from": "0039",
	"school_system": "3年制"
}

User

用户

用户信息扩展至乘客，包含乘客所有属性用户状态 {0:未知,1:已通过,2:未通过,3:待核验,4:未通过,5:请报验}

请报验：为港澳通行证，护照，台湾通行证用户，去车站审核后为“预通过”状态

属性名	类型	描述
id	String	(web)用户ID
login	String	注册时的用户名
activated	Bool	是否邮件激活
verified	Bool	是否手机验证
request_verify	Bool	请求手机核验，核验后才能买票
marked	Bool	是否被标记为第三方用户，需去火车站核验
....	Passenger	其它属性扩展至Passenger

{
	"activated": true,
	"status": "1",
	"login": "imhidden",
	"name": "张镇东",
	"id_type": "1",
	"id_no": "500235198610167533",
	"type": "1",
	"email": "[email protected]",
	"mobile": "13720067707",
	"verified": false,
	"id_type_name": "二代身份证",
	"type_name": "成人",
	"key": "1-500235198610167533-张镇东",
	"status_name": "未验证",
	"status_detail": "未验证",
	"phone": "",
	"sex": "M",
	"sex_name": "男",
	"school_system": "4年制",
	"school_preference_no": null,
	"ivr_passwd": "107105"
}

Station

车站

属性名	类型	描述
name	String	站点名称
code	String	车站编码例如：BJP
long	String	车站全拼 beijing
short	String	车站简拼 bj
half	String	例如：bji
time	String	开售时间例如：14:30

StopStation

列车停靠站

席位

属性名	类型	描述
name	String	站点名称
no	String	顺序编号例如：02
departure_time	String	出发时间例如：11:17
arrival_time	String	到达日期例如：15:20
duration	String	停留时间，例如：00:21，原为stopover_time
enabled	Bool	是否在所选的区间内

{
		"arrival_time": "12:02",
		"name": "通州西",
		"departure_time": "12:04",
		"duration": "2分钟",
		"no": "02",
		"enabled": true
}

Seat

席位

属性名	类型	描述
name	String	席位名称例如：一等座
code	String	席位编码例如： M
amount	Int	余票数
price	Float	票价
discount	Bool	是否有折扣此参数暂时无效

	{
		"code": "3",
		"name": "硬卧",
		"amount": 53,
		"price": 54
	}

Train

属性名	类型	描述
code	String	车次
train_no	String	车次号
from	String	出发站Code
from_name	String	出发站名称
to	String	到达站Code
to_name	String	到达站名称
start	String	始发站Code
start_name	String	始发站名称
end	String	终点站Code
end_name	String	终点站名称
start_date	String	始发日期，可能和出发日期不一样例如：2015-07-20
departure_date	String	出发日期例如：2015-07-21
departure_time	String	出发时间例如：11:17
departure_at	String	出发时间例如：2015-07-21 11:17
arrival_date	String	到达日期例如：2015-07-22
arrival_time	String	到达时间例如：15:20
sale_date	String	开售日期例如：2015-07-22
sale_time	String	开售时间例如：15:20
duration	String	历时，例如：00:21，原为lishi
fastpass	Bool	暂未启用，支持二代身份证快速进出站，原为 is_support_card
token	String	预订令牌secretStr，移动端为location_code
class_name	String	类别名称，动车
maintaining	Bool	是否系统维护中
outage	Bool	列车是否停运
sale	Bool	是否已开售
last	Bool	是否有余票
orderable	Bool	是否可预订，无票，未到预订时间，系统维护，停运都不可预订
notice	String	不可预订时会有的提示信息
seats	[seat]	席位列表
stations	[StopStation]	列车停靠站

{
	"code": "K7711",
	"train_no": "24000K771109",
	"from": "BJP",
	"from_name": "北京",
	"to": "TAP",
	"to_name": "通州西",
	"start": "BJP",
	"end": "CDP",
	"start_date": "2015-09-08",
	"departure_time": "07:56",
	"departure_date": "2015-09-08",
	"departure_at": "2015-09-08 07:56",
	"arrival_time": "08:18",
	"duration": "00:22",
	"token": "P2#MjAxNTA5MDgjMDAjSzc3MTEjMDA6MjIjMDc6NTYjMjQwMDBLNzcxMTA5I0JKUCNUQVAjMDg6MTgj5YyX5LqsI+mAmuW3nuilvyMwMSMwMiMxMDAwODAwOTQ2MTAwMDgwMzQzMjMwMDU0MDAwNTMjUDIjMTQzOTE4NTA0ODk2MCMxNDM5MTY0ODAwMDAwI0MwMTRBODc1RUIyQkMzNUMwMTM4NUY2NjFCRkM0MTZCNzkxQTkxM0I1RDQ4QkVFMjU0ODA2MzI1",
	"arrival_date": "2015-09-08",
	"class_name": "快速",
	"orderable": true,
	"last": true,
	"seats": [{
		"code": "3",
		"name": "硬卧",
		"amount": 53,
		"price": 54
	}, {
		"code": "1",
		"name": "硬座",
		"amount": 946,
		"price": 8
	}, {
		"code": "1",
		"name": "无座",
		"amount": 432,
		"price": 8
	}],
	"seats_info": "100080094610008034323005400053"
}

Ticket

属性名	类型	描述
sequence_no	String	订单号
ticket_no	String	车票号
refund_no	String	退票号
reserve_at	String	预留时间
resignable	Bool	可改签
changeTSable	Bool	可改站
refundable	Bool	可退票
incomplete	Bool	未完成状态(支付中，改签中)
type	String	车票类型
type_name	String	类型名称
status	String	车票状态
status_name	String	状态名称，例：改签中
price	Float	价格
batch	String	批次号？
coach	String	车厢号
coach_name	String	车厢名
seat	String	座位号
seat_name	String	座位名
seat_type	Int	座位类型
seat_type_name	String	座位类型名称
train	Train	包含属性code, from, from_name, to, to_name, distance, departure_time, arrival_time
passenger	Passenger	包含属性name, id_type, id_type_name, id_no

状态对应表

a -> 已支付 b -> 已出票 c -> 已退票 d -> 已改签 e -> 改签中 f -> 改签票 j -> 改签待支付 i -> 待支付 m -> 已出站 s -> 变更到站待支付 q -> 变更到站中 p -> 已变更到站 r -> 变更到站票

{
		"sequence_no": "E504413982",
		"ticket_no": "E504413982040101",
		"reserve_at": "2015-08-04 10:09:36",
		"resignable": false,
		"refundable": false,
		"type": "1",
		"type_name": "成人票",
		"status": "c",
		"status_name": "已退票",
		"price": "4.00",
		"batch": "5",
		"coach": "04",
		"coach_name": "04",
		"seat": "0101",
		"seat_name": "101号",
		"seat_type": "1",
		"seat_type_name": "硬座",
		"refund_no": "业务流水号:2E504413982005005101120336",
		"train": {
			"code": "6461",
			"from": "BJP",
			"from_name": "北京",
			"to": "TAP",
			"to_name": "通州西",
			"distance": "18",
			"arrival_time": "12:02",
			"departure_time": "11:41",
			"departure_date": "2015-09-02",
			"departure_at": "2015-09-02 11:41",
			"arrival_date": "2015-09-02"
		},
		"passenger": {
			"name": "张镇东",
			"id_no": "500235198610167533",
			"id_type": "1",
			"id_type_name": "二代身份证",
			"key": "1-二代身份证-500235198610167533"
		},
		"title": "张镇东 - 04车101号(硬座)",
		"detail": "二代身份证, 成人票, ¥4.00"
	}

Order

属性名	类型	描述
sequence_no	String	订单号
order_at	String	下单时间
status	Int	0:已完成, 1:下单, 2:改签, 3:改站, 4:排队中
pay_mode	String	Y:需要支付,N:无需支付,T:有退款
expired_at	String	支付过期时间
new_price	Float	重新支付票价
refund_price	Float	票款差价
refund_rate	Float	退票费率%
refund_cost	Float	退票费
refund_fact	Float	实际退款
price	Float	车票总价
amount	Int	车票张数
warning	String	提醒，比如是无座票，或者两张票不同车厢
expired	Bool	是否过期，已出票
history	Bool	是否来自历史订单
tickets	[Ticket]	车票列表

{
	"sequence_no": "E569095069",
	"order_at": "2015-06-16 15:44:56",
	"amount": "4",
	"history": true,
	"tickets": [....],
	"price": "20.00",
	"expired_at": "2015-06-16 16:30:33",
	"passengers": ["张镇东:已退票", "张彬:已退票"],
	"summary": "张镇东:已退票  张彬:已退票",
	"status": 0,
	"refund_price": "0.00",
	"new_price": "0.00",
	"pay_mode": "N",
}

排队中的订单参数

属性名	类型	描述
status	Int	等于4
train	Train	车次
passengers	[Passenger]	乘客列表
request_at	String	申请时间：2016-03-28 12:30:57
wait	String	预计等待时间，例如：15分钟
tour_flag	String	gc:改签,dc:预定
wait_time	Int	预计等待时间，返回实际秒数

{
  "orders": [
      {
          "status": 4,
          "wait": "4秒",
          "wait_time": 4,
          "request_at": "2016-03-28 12:30:57",
          "wait_count": 0,
          "train": {
              "code": "C7118",
              "from": "SZQ",
              "from_name": "深圳",
              "to": "GZQ",
              "to_name": "广州",
              "departure_date": "2016-03-28",
              "departure_time": "13:07",
              "departure_at": "2016-03-28 13:07"
          },
          "passengers": [
              {
                  "name": "王浩",
                  "id_type_name": "二代身份证",
                  "ticket_type_name": "成人票",
                  "seat_type": "M",
                  "seat_type_name": "一等座"
              }
          ]
      }
  	]
 }

Bank

属性名	类型	描述
code	String
name	String
desc	String
request	String

{
	"name": "支付宝",
	"code": "33000010",
	"request": {method: "POST", url: "", form: ""},
	"id": "alipayClient",
	"desc": "支付宝钱包支付，退票及时到账"
}

接口规范

一个api请求分请求参数params和数据返回结果result两个部分

简单示例

login({ login: "haha", password: "ppp" })
//error result => { error: {message: "密码错误"}, response: { status: 200, headers: {} } }
//success result => { error: null, data: {success: true, user: {name: "Jack"} }, response: {status: 200, headers: {}} }

params

数据请求参数为一个字典，定义该api包含的条件。例如登录api请求参数： { login: "haha", password: "ppp" }

result

数据返回为一个字典，包括错误信息error, 数据data, 原始HTTP头信息response

error

接回提交如果发生错误，则返回一个错误消息，没有错误时error为null，如果有，error为一个字典，包含错误详情message和错误码code。

{ message: "需要登录才能操作", code: -1 }

属性名	类型	描述
message	String	如果有错误，返回错误消息
code	Int	错误类型

错误码code

接回会根据不同的错误情况，返回不同的code。

提交的数据有误，code为0 ~ 100(多个接口可能都产生的错误), 1000 ~ (具体单个接口的自定义错误) 这类错误只需要修改提交参数即可恢复正常

HTTP本地请求网络错误，code为100 ~ 199 网络通讯正常后可恢复，可先尝试切换接口

接口在关键接口重现该错误2次后返回 code 200 接口类错误

接口异常类错误，code为200 ~ 299 暂时不可恢复类错误，需要切换接口

自定义的错误码如下：

类型		描述
0	unknown	未知错误，程序返回
1	not_logged	需要登录才能操作，但未登录，或者异地登录，本次登录实效
2	not_init	(mobile)需要初始化才能操作，接口会自动完成重新初始化，重试3次后还有错误报200错误
3	timefix	(mobile)本地时间和服务器时间不匹配，程序自动修正，重新提交即可
4	captcha	验证码输入错误
5	inactive	该用户未激活
6	system_error	system error.
7	frequency	您的操作频率过快，请稍候重试。 - 访问频率过快，请稍后重试！
8	busy	系统忙，请稍后重试 - (checkpay)系统繁忙 - (mobile)系统忙，请稍后再试。 - 系统忙,请稍后重试
9	maintaining	系统维护中【在：23:00-24:00时间段内只支持用户支付】，购票请稍候访问，谢谢！
10	busy	(web)网络繁忙
11	runtime	(mobile)Runtime error
20	stop	该用户已被暂停使用，乘车人可凭购票登记的有效身份证件到车站办理换票、乘车、改签和退票业务，车票详情请查阅购票时使用的邮箱，如有疑问请拨打铁路客户服务电话010-12306。

	|			|

更多错误代码

data

为一个字典，需要的数据解析结果直接放在该字典中。例如：{ success: true }，{ trains: [] }

response

原始HTTP头信息可以获取headers以及cookie信息

属性名	类型	描述
status	Int	HTTP状态
statusMessage	String	HTTP状态信息
headers	Object	HTTP头
cookies	[Cookie]	Cookie信息

Cookie

属性名	类型	描述
name	String
value	String
domain	String
path	String
expiresDate	Int	返回10位的time interval
sessionOnly	Bool
secure	Bool

初始化API

.init

.captcha

参数params

属性名	类型	描述
method	String	方式[signin, order, resetPassword, user, signup]
token	String	train token,iOS api需要

返回数据data

属性名	类型	描述
image	String	base64编码图片数据

.checkCaptcha

只有web接口使用

属性名	类型	描述
method	String	方式[signin, order, signup]
code	String	验证码

错误返回到error中

用户信息管理

.checkLoginName

(web)检查用户是否被占用

.signup

参数params

属性名	类型	描述
...	User	注册的用户信息
password	String	注册密码
mobile_code	String	手机短信验证码

返回数据data

属性名	类型	描述
message	String

.signin

参数params

属性名	类型	描述
login	String	登录名/手机号/邮箱
password	String	密码
code	String	验证码web接口使用

返回数据data

属性名	类型	描述
user	User	登录用户部分信息

登录失败返回error

.signout

退出

.user

获取用户信息

返回数据data

属性名	类型	描述
user	User

.updateUser

更新用户信息

参数params

属性名	类型	描述
...	User	变更的user属性
code	String	验证码(mobile)使用，如果没有code，并且提供了自动解验证码的方法，会自动解验证码

未核验(status != 1)的用户可更新身份信息name,id_type,id_no

.resendEmail

重发激活邮件暂只有web端有这个接口

.mobileCode

获取手机验证码

参数params

属性名	类型	描述
mobile	String	手机号（更改手机号时需要）
method	String	类别[mobile, email, password, signup, resetPassword]

当method为signup时，其他参数和 signup 保持一致当method为resetPassword时，需要参数id_type, id_no, code 当method为email时，需要参数email

.updatePassword

更新密码

参数params

属性名	类型	描述
old_password	String	原密码
password	String	新密码
mobile_code	String	手机验证码

.updateMobile

更新或者验证手机号

参数params

属性名	类型	描述
mobile	String	新手机号
mobile_code	String	手机验证码

.updateEmail

更新邮箱

参数params

属性名	类型	描述
email	String	新邮箱
password	String	登录密码
mobile_code	String	手机验证码

.resetPassword

重置密码

分邮件方式和手机找回方式手机验证码方式找回需要手机已认证通过

参数params

属性名	类型	描述
method	String	重置方式[email, mobile]
id_type	String	证件类型
id_no	String	证件号码
code	String	验证码
email	String	注册邮箱，email方式
mobile	String	手机号，mobile方式
password	String	新密码，mobile方式

返回数据data

属性名	类型	描述
message	String	提交成功提示信息

乘客管理

.passengers

获取所有乘客信息

无需参数

返回数据data

属性名	类型	描述
passengers	[Passenger]	乘客列表

.passenger

获取单个乘客信息

参数params

属性名	类型	描述
key	String	passenger key
type	String	passenger type

返回数据data

属性名	类型	描述
passenger	Passenger

.createPassenger

创建乘客

参数params

属性名	类型	描述
...	Passenger	扩展至passenger

.updatePassenger

更新单个乘客信息

参数params

属性名	类型	描述
key	String	原来passenger key
...	Passenger	变更的passenger属性

.deletePassenger

删除单个乘客

参数params

属性名	类型	描述
key	String	passenger key
type	String	passenger type,iOS api需要，不然查不出学校信息

车次查询

.stations

获取所有车站数据

返回数据data

属性名	类型	描述
stations	[Station]

.trains

查询车次，票价，余票信息

web端，如果查询超过60天，从余票接口查询数据

参数params

属性名	类型	描述
date	String	时间，2016-07-20
student	Bool	是否查学生票
from	Station	出发站，会用到code,name
to	Station	到达站

返回数据data

属性名	类型	描述
trains	[Train]

.trainDetail

查询车次的停靠站时刻表等详细信息

参数params

属性名	类型	描述
date	String	(mobile)列车从查询站开始时间，2016-07-20
start_date	String	(web)列车从始发站始发事件，2016-07-20
train_no	String	车次号
code	String	车次
from	String	出发站 code
to	String	到达站 code

返回数据data

属性名	类型	描述
train	Train	stations,code
train.stations	[StopStation]

.checkDelay

正晚点查询

参数params

属性名	类型	描述
date	String	时间，2016-07-20
code	String	车次code
to	String	目的地车站code
to_name	String	目的地车站名称

返回数据data

属性名	类型	描述
message	String

订单管理

.requestOrder

申请订单

web接口需要提交数据，根据返回结果解析seats，passengers 移动端无需提交数据，根据train获得seats，根据order获得passengers

参数params

属性名	类型	描述
train	Train	车次，带有token
date	String	时间，2016-07-20
student	Bool	是否预订学生票
from	Station	出发站，会用到code,name
to	Station	到达站
tour_flag	String	状态，dc预订，gc改签
order	Order	改签时需要传入改签的订单

返回数据data

属性名	类型	描述
passengers	[Passenger]	可选的乘客列表，改签时返回选择改签的乘客
seats	[Seat]	可选的座位
warning	String	注意事项，例如：该列车不能退票
other	Object	(web only)提供async,token,purpose_codes, key_check_isChange, leftTicketStr, train_location给confirmOrder使用

mobile接口改签时，passenger中需要带有batch,seat,coach参数

.confirmOrder

确认订单

参数params

属性名	类型	描述
train	Train	车次，带有token
date	String	时间，2016-07-20
student	Bool	是否预订学生票
from	Station	出发站，会用到code,name
to	Station	到达站
tour_flag	String	状态，dc预订，gc改签
change_station	Bool	是否改站
order	Order	改签时需要传入改签的订单
passengers	[Passenger]	所选的联系人列表，需要补全ticket_type, seat_type参数
code	String	验证码
other	Object	(web only)通过requestOrder获取

返回数据data

属性名	类型	描述
order	Order
order.other	Object	web接口使用。提供orderRequestDTOJson,parOrderDTOJson属性给取消订单，提供oldTicketDTOJson,parOrderDTOJson,batch_no给改签时使用

.cancelOrder

取消订单

参数params

属性名	类型	描述
order	Order	订单详情

.incompleteOrders

返回数据data

属性名	类型	描述
orders	[Order]

获取所有未完成订单

.incompleteOrder

获取单个未完成订单

参数params

属性名	类型	描述
sequence_no	String	订单号
status	String	order status

返回数据data

属性名	类型	描述
order	Order	订单

.orders

获取未出行订单列表，分页保存未发车的订单

参数params

属性名	类型	描述
page	Int	页码，1开始

返回数据data

属性名	类型	描述
orders	[Order]
more	Bool	是否还有更多

.order

获取订单单个订单信息

参数params

属性名	类型	描述
sequence_no	String
history	Bool	(mobile)订单是否来自历史订单 `order.history`

返回数据data

属性名	类型	描述
order	Order

.historyOrders

获取历史订单列表，分页历史订单保存已发车的订单，不能删除，只保存乘车日期近一个月的订单

参数params

属性名	类型	描述
page	Int	页码，1开始

返回数据data

属性名	类型	描述
orders	[Order]
more	Bool	是否还有更多

.orderDetail

获取订单跟踪，退款跟踪

参数params

属性名	类型	描述
sequence_no	String
history	Bool	(mobile)订单是否来自历史订单 `order.history`

返回数据data

属性名	类型	描述
details	Array	[{title:"", desc:""}]
refund_details	Array

.requestResign

申请改签，改站

参数params

属性名	类型	描述
order	Order	将要改签的票放入 `order.tickets`
change_station	Bool	变更车站

返回数据data

属性名	类型	描述
from	Station	code,name
to	Station	code,name
date	String	默认预订日期
max_date	String	最大预订日期

.confirmResign

确认改签，改站

参数params

属性名	类型	描述
order	Order

返回数据data

属性名	类型	描述
success	Bool	是否支付成功
order	Order	支付成功后的订单详情

.requestRefund

申请退票

参数params

属性名	类型	描述
ticket	Ticket

返回数据data

属性名	类型	描述
message	String	退款消息
return_price	Float
return_cost	Float
rate	Float

.confirmRefund

确认退票

参数params

属性名	类型	描述
ticket	Ticket

订单支付

.banks

获取银行列表

参数params

属性名	类型	描述
order	Order	订单
unionpay	Bool	支持银联客服端
alipayqr	Bool	支持支付宝钱包

返回数据data

属性名	类型	描述
banks	[Bank]

.bank

获取银行信息

如果没有 return_scheme 直接返回url参数

参数params

属性名	类型	描述
bank	Bank	通过banks获得的bank信息
return_scheme	String	alipayqr需要的返回app的url scheme

返回数据data

属性名	类型	描述
bank	Bank	返回bank的其它参数
bank.html	String
bank.baseURL	String
bank.request	Object	{url, form}
bank.app_url	Object	{url, params}

.checkPay

检测订单是否支付

参数params

属性名	类型	描述
sequence_no	String	订单号

返回数据data

属性名	类型	描述
success	Bool	是否支付成功
order	Order	支付成功后的订单详情

jerrylau91/api.md

12306数据接口API(草稿)

数据定义

Passenger

User

Station

StopStation

Seat

Train

Ticket

Order

Bank

接口规范

params

result

error

data

response

Cookie

初始化API

.init

.captcha

.checkCaptcha

用户信息管理

.checkLoginName

.signup

.signin

.signout

.user

.updateUser

.resendEmail

.mobileCode

.updatePassword

.updateMobile

.updateEmail

.resetPassword

乘客管理

.passengers

.passenger

.createPassenger

.updatePassenger

.deletePassenger

车次查询

.stations

.trains

.trainDetail

.checkDelay

订单管理

.requestOrder

.confirmOrder

.cancelOrder

.incompleteOrders

.incompleteOrder

.orders

.order

.historyOrders

.orderDetail

.requestResign

.confirmResign

.requestRefund

.confirmRefund

订单支付

.banks

.bank

.checkPay