Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
12306 API

12306数据接口API(草稿)

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

数据定义

命名规则

该协议对12306原始数据的命名做了适当简化,例如原始passenger种的名字为passenger_name,现直接改为name。 另外像原始数据种seat_no这种也直接做了简化,变成seatseat_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": "zzdhidden@gmail.com",
	"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。
	|			|

100 |network |网络请求出错 101 |encrypt |(mobile)加密请求失败 102 |decrypt |(mobile)解密请求失败 103 |network |(web)网络可能存在问题,请您重试一下! 104 |network |(web)(mobile)statusCode 404 Not Found | | 200 |unrecoverable |>=100 && < 200 的错误重复出现3次,转到200,接口错误重试失败,暂时无法恢复 201 |init |(mobile)初始化重试失败,初始化遇到任何错误就会重试3次,失败后报 201 错误 202 |blocked |用户被屏蔽 203 |illegal |出现非法请求

更多错误代码

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 支付成功后的订单详情

Flow

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.