[关闭]
@khan-lau 2017-04-11T23:42:19.000000Z 字数 11262 阅读 2808

Fast4ward接口协议

未分类

版本号: v0.9.7

1 协议约定

1.1 如果请求正确, 应返回数据类型

  1. --response
  2. result:{
  3.     "code":200
  4.     "message": "S_OK",
  5.     "data": {
  6.         "array":[]          //此处,根据需求返回不同类型数据.
  7.     }
  8. }

1.2 如果请求失败, 应返回数据类型

  1. --response
  2. {
  3.     "code":500,
  4.     "message": "FA_UNAUTHORIZED"  //见1.5 错误代码定义
  5. }

1.3 request

https://host:port/interface
其他协议字段使用 form 提交
通过https 协议保证安全性.
建议使用 Go Daddy Secure Certificate Authority - G2证书
禁止缓存的页面, 请求需携带If-Modified-Since:"GMT时间戳"
连接使用 tls 1.0+ 进行加密, 避开 ssl 的漏洞
token 有时效限制, 过期后返回对应err_code.(参考协议1.5)
login成功, header 中返回 cookie, 后续请求都需携带对应 cookie

1.4 编码集

协议中约定所有请求必须使用 utf8编码. 涉及 url-encode, 也需使用 utf8.
涉及分页的接口 暂定每页20条记录.

1.5 错误代码

Message字段

S_OK                          - 表示操作成功，同时返回对应的Session ID和用于cookie校验的值
FA_UNAUTHORIZED               - 表示用户名或者密码不匹配，或者用户不存在
FA_INVALID_VERIFY_CODE        - 校验码不正确 (备用)
FA_VERIFY_CODE_ERROR          - 获取校验码失败
FA_INVALID_VERIFY_COOKIE      - cookie不正确
FA_INVALID_TOKEN              - TOKEN不合法，通常是校验码已过期
FA_NEED_VERIFY_CODE           - 需要校验码 (备用)
FA_USER_LOCKED                - 用户处于锁定状态 (备用)
FA_USER_SUSPENDED             - 用户被禁用 (备用)
FA_USER_WRONG_STATUS          - 用户状态错误 (备用)
FA_DB_ERROR                   - 数据库异常
FA_PARAM_ERROR                - 参数异常
FA_DATA_NOT_FOUND             - 未找到结果
FA_USER_EXISTS                - 用户名或手机号重复
FA_ORDER_EXISTS               - 用户重复报名
FA_ORDER_FULL                 - 票已售完
FA_FEE_ZERO                   - 票价为0
FA_SIGN_ERROR                 - 签名错误

2 基础数据类型

2.1 新闻资讯

  1. "news":{
  2.     "id":51ul,              //ul代表unsigned long
  3.     "title":"新闻标题",
  4.     "memo":"简介",
  5.     "type":1,               //0为未知, 1为视频, 2为文本, 3为富文本
  6.     "date_time":1302455112, //发布时间, UTC时间戳
  7.     "res":"aaa.html"        //
  8.     "img":"http://fast4ward.cn/api/res/51.png", 
  9.     "img_w":480,
  10.     "img_h":320,
  11.     ....                    //其他字段,可自行扩展
  13. }

2.2 广告bannr

  1. "banner":{
  2.     "id":123ul,           //id
  3.     "img":"http://fast4ward.cn/res/banner/1.png",
  4.     "img_w":480,          //图片宽度
  5.     "img_h":320,          //图片高度
  6.     "operation":1,        //操作类型, 1为app内跳转, 2为应用外跳转, 3待扩展
  7.     "schema":"fw://main?aa=value&bb=value1"
  8.     ...                    //其他字段, 可自行扩展.
  9. }

2.3 车手

  1. "user":{
  2.     "id":33ul,                  //id
  3.     "user":"john117",           //登录用户名
  4.     "passwd":"qwer1234",        //登录密码
  5.     "true_name":"张三",         //姓名     
  6.     "nick":"skywalker",         //nickname 
  7.     "no":"001",                 //车手编号, 普通用户为null
  8.     "phone":"13801030311",      //电话号码 
  9.     "email":"a@b.com",          //邮箱     
  10.     "gender":0,                 //0:女, 1:男
  11.     "birthday":142132532234L    //生日, unix时间戳类型
  12.     "id_type":0,                //0:身份证, 1:驾驶证, 2:护照, 3:军官证, 4:港澳, 5:台湾, 6:学生证 
  13.     "id_card":"123524187455771234", //证件编号
  14.     "icon":"http://fast4ward.cn/res/adf.png",  //自定义头像
  15.     "detail":{
  16.         "id" : 1234,
  17.         "uid": 33ul,
  18.         "id_card" : "/upload/user/id_124325.png",
  19.         "driver_card":"/upload/user/driver_43251245.png",
  20.         "address":"湖南省长沙市xx区xx路xx号xxx",
  21.         "sns": "aabbcc"     //社交账号,暂时只支持微信
  22.     }
  23.     ....                   //其他字段, 可自行扩展.
  24. }

2.4 活动赛程

  1. "schedule" : {
  2.     "title":"培训",
  3.     "start":1468080000000, //unix毫秒时间戳 2016/07/10 00:00 
  4.     "end":1468166399999    // 2016/07/10 23:59
  5. }

2.5 活动

  1. "party":{
  2.     "id" : 123,  --id
  3.     "name" "平谷04加速赛",  //活动名称
  4.     "memo":"合法专业赛事",  //活动介绍
  5.     "area" "北京",          //比赛地点
  6.     "race_begin": 1468080000000, //开始时间 2016/07/10 00:00
  7.     "race_end": 1468166399999,   //结束时间
  8.     "sign_begin": 1468010000000, //报名开始时间
  9.     "sign_end": 1468010099999,  //报名截至时间 
  10.     "watchers": 400,  //可容纳观众数量,
  11.     "drivers": 100,   //可允许车手数量
  12.     "ticker":3000,    //门票价格, 单位为分
  13.     "fee": 30000,     //车手报名费用, 单位为分
  14.     "status": 0,      //是否有效, 0:无效, 1:有效
  15.     "contacts": "联系方式", 
  16.     "address": "平谷县航空中心",  //活动地点
  17.     "schedule":[           //活动日程表
  18.         schedule,          //见2.4
  19.         ....
  20.     ]
  21. }

2.6 赛车

  1. "car":{
  2.     "id" : 3ul,           //id
  3.     "user" : user,        //见协议2.3
  4.     "car_sn" : "321341",  //车架号
  5.     "brand" : "ford",     //品牌
  6.     "model" : "fiesta",   //型号
  7.     "is_turbo" : false,   //是否涡轮增压
  8.     "displacement": 150,  //排量, 1.5*100
  9.     "driver_type" : 0,    //驱动形式, 0"前驱", 1"后驱", 2"后置后驱", 3"四驱"
  10.     "group" : 1,          //比赛分组信息, 分组id, 详见2.11
  11.     "hp" : 120,           //马力
  12.     "icon":"http://fast4ward.cn/res/adf.png",  //自定义照片
  13.     ...                   //自行扩展
  14. }

2.7 比赛记录

  1. "record":{
  2.     "id":1231ul,            // 记录id
  3.     "user":user,            // 车手, 见2.3
  4.     "car":car,              // 车辆, 见2.6
  5.     "party":party,          // 记录产生的活动赛事, 见2.5
  6.     "date_time": 1304xxxx,  // UTC时间戳
  7.     "reaction_time" : 1.82f // reaction time 反应时间(绿灯亮 到离开起点的时间)
  8.     "FT60": 1.2f,           // 到60英尺时间
  9.     "FT330": 2.2f,          // 到330英尺时间
  10.     "FT660": 3.3f,          // 到660英尺时间
  11.     "Speed660":200.00f,     // 到660FT的冲线速度
  12.     "vehicle_speed": 220.00f, // 400米终点的冲线速度
  13.     "elapsed_time": 9.82f,     // 400时间
  14.     "photo": "/res/record/1231.png"  //成绩单
  15.     ....                 //  自行扩展
  16. }

2.8 品牌数据

  1. "brand":{
  2.     "id" : 123,
  3.     "brand": "Alfa Romeo",                //品牌
  4.     "chinese": "阿尔法罗密欧",            //品牌中文名
  5.     "index": "A",                         //中文拼音首字母
  6.     "flag": "1",                          //是否有效
  7.     "models":[ model, ...],               //见2.9
  8.     "icon": "/upload/car/logo213415.png"  //logo
  9. }

2.9 车辆型号

  1. "model":{
  2.     "id" : 4235,
  3.     "brand_id": 123,                      //品牌id
  4.     "model": "ALFA 147",                  //型号名称
  5.     "flag": "1",                          //是否有效
  6.     "icon": "/upload/car/photo213415.png" //车型照片
  7. }

2.10 订单

  1. "order" : {
  2.     "id": 1,
  3.     "order_id" : "2f2341321b342523",     //uuid1编码
  4.     "produce_type":0,                    //产品id, 0:门票; 1:报名费
  5.     "pay_type":0,                        //支付渠道id, 0:微信, 1:支付宝, 2:快钱, 3:银联
  6.     "fee":300,                           //支付金额 单位(分)
  7.     "join_type": "",                     //用户身份, null或""为个人, 否则为所属机构名称
  8.     "descript": "无改动"                 //改装描述
  9. }

2.11 比赛分组信息

  1. "group": {
  2.     "id": 1,                  //编号
  3.     "name": "A1组-前驱钢炮组",//分组中文名
  4.     "english": "A1",          //分组英文名
  5.     "index": 0,               //排序索引
  6.     "flag": true              //是否有效的标记
  7. }

3 接口说明

3.1 init

初始化接口

注意事项: 该接口 response 时需要 set-cookie,并在 http header 中返回对应的 cookie, 鉴权成功后, 后续接口提交请求时, 必须在 header 中携带该cookie.

URL:
https://host:port/init

参数

Name Description
limit Optional 首页获取的资讯记录数量, 默认为18

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "page":0,
  6.         "pages":1,
  7.         "BannerArray":[],
  8.         "NewsArray":[]
  9.     }
  10. }

请求失败

  1. {
  2.     "code":500
  3.     "message": "FA_INVALID_VERIFY_COOKIE"  //见1.5 错误代码定义
  4. }

3.2 鉴权接口 login

鉴权接口.

URL:
https://host:port/login

参数

Name Description
user 用户id
passwd md5(user:passwd:timestamp)
timestamp 1970至今的秒数*1000

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "token"           : <string> 
  6.     }
  7. }

请求失败

  1. {
  2.     "code":500
  3.     "message": "FA_UNAUTHORIZED"  //见1.5 错误代码定义
  4. }

3.2.1 基本流程

init接口会提供在header中提供名为fast4ward.sid的cookie, 后续接口调用请求需携带该cookie.

Created with Raphaël 2.1.2ServerServerBrowserBrowserInit auth_cookiesaved auth_cookielogin with http cookie headerretrun tokenrest_passwd with http cookie header and tokenget_news with http cookie header

3.3 取消鉴权接口 unlogin

取消鉴权

URL:
https://host:port/unlogin

数参

Name Description
user 用户id
token token

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK"
  4. }

请求失败

  1. {
  2.     "code":500,
  3.     "message": "FA_UNAUTHORIZED",
  4. }

3.4 用户注册

新增用户

URL:
https://host:port/reg

参数

Name Description
user_name 用户名, 此处参数名 并非user
passwd 密码
true_name Optional 真名
nick Optional 昵称
phone 国内手机号
verify_code 短信校码验
email Optional 邮箱
gender Optional 性别
id_type Optional 身份证件类别 0:身份证, 1:驾驶证, 2:护照, 3:军官证, 4:港澳, 5:台湾, 6:学生证
id_card Optional 身份证件号码
file Optional 照片信息, 文件类型

* 注意: 该接口必须以multipart/form-data方式提交

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "user" : user --见协议2.3
  6.     }
  7. }

3.5 用户注册信息修改

修改用户信息

URL:
https://host:port/update_driver

参数

Name Description
user user account
token token
id user id
passwd Optional 密码
true_name Optional 真名
nick Optional 昵称
email Optional 邮箱
gender Optional 性别
id_type Optional 身份证件类别 0:身份证, 1:驾驶证, 2:护照, 3:军官证, 4:港澳, 5:台湾, 6:学生证
id_card Optional 身份证件号码
file Optional 照片信息, 文件类型

* 注意: 该接口必须以multipart/form-data方式提交

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "user" : user --见协议2.3
  6.     }
  7. }

3.6 重置密码

修改密码
URL:
https://host:port/reset_passwd

参数

Name Description
phone 国内手机号
passwd 密码
verify_code 短信校码验

* 注意: 该接口必须以multipart/form-data方式提交

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {}
  5. }

3.7 获取用户信息

查询指定用户信息

URL:
https://host:port/user_info

参数

Name Description
user 用户名
token token
id 需获取的user id

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "user" : user --见协议2.3
  6.     }
  7. }

3.8 获取用户所有车辆

查询指定用户名下所有车辆信息

URL:
https://host:port/get_cars

参数

Name Description
uid 需获取的user id

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "array" : [
  6.             car, 
  7.             ....
  8.         ]
  9.     }
  10. }

3.9 获取资讯列表

分页获取资讯列表

URL:
https://host:port/get_news

参数

Name Description
sid Optional http header auth_cookie
offset Optional 分页偏移量, 与limit组合使用
limit Optional 当页记录数
order Optional 按新闻录入时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             news,   --news定义见协议 2.1
  9.             news,
  10.             ......
  11.         ]
  12.     }
  13. }

3.10 获取广告列表

获取广告列表

URL:
https://host:port/get_banner

参数

Name Description
sid Optional http header auth_cookie

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "array":[
  6.             banner,   --banner定义见协议 2.2
  7.             banner,
  8.             ......
  9.         ]
  10.     }
  11. }

3.11 获取赛事活动列表

分页获取赛事活动数据

URL:
https://host:port/get_party

参数

Name Description
sid Optional http header auth_cookie
offset Optional 分页偏移量, 与limit组合使用, 如offset limit都为空, 则不分页
limit Optional 当页记录数
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             party,   //party 定义见协议 2.5
  9.             party,
  10.             ......
  11.         ]
  12.     }
  13. }

3.12 获取车辆品牌列表

获取车牌品牌数据

URL:
https://host:port/get_brand

参数

Name Description
sid Optional http header auth_cookie
offset Optional 分页偏移量, 与limit组合使用, 如offset limit都为空, 则不分页
limit Optional 当页记录数
order Optional 按活动开始时间排序, desc, asc, 默认asc
search Optional 搜索条件, 根据条件从品牌, 中文名, 索引中检索

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             brand,   //party 定义见协议 2.8
  9.             brand,
  10.             ......
  11.         ]
  12.     }
  13. }

3.13 获取对应品牌的车型列表

查询某个品牌下对应车型

URL:
https://host:port/get_model

参数

Name Description
sid Optional http header auth_cookie
brand_id 车辆品牌id
offset Optional 分页偏移量, 与limit组合使用, 如offset limit都为空, 则不分页
limit Optional 当页记录数
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             model,   //model 定义见协议 2.9
  9.             model,
  10.             ......
  11.         ]
  12.     }
  13. }

3.14 获取对应品牌车型树状表

获取品牌车型树状结构数据

URL:
https://host:port/get_brand_tree

参数

Name Description
sid Optional http header auth_cookie
offset Optional 分页偏移量, 与limit组合使用, 如offset limit都为空, 则不分页
limit Optional 当页记录数
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             brand,   //brand 定义见协议 2.8
  9.             brand,
  10.             ......
  11.         ]
  12.     }
  13. }

3.15 获取比赛分组列表

获取品牌车型树状结构数据

URL:
https://host:port/get_group

参数

Name Description
search Optional 检索关键字,检索name, english内容

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "array":[
  6.             group,   //brand 定义见协议 2.11
  7.             group,
  8.             ......
  9.         ]
  10.     }
  11. }

3.16 获取排行榜信息

获取各种类型比赛排行榜信息

URL:
https://host:port/get_board

参数

Name Description
sid Optional http header auth_cookie
mode Optional 默认为总榜, brand: 品牌榜, party: 单场比赛排行
pid Optional 赛事活动id, 与mode=party选项组合使用
brand Optional 车辆品牌中文, 与mode=brand选项组合使用
model Optional 车辆型号, 与mode=brand选项 ,brand参数组合使用
offset Optional 分页偏移量, 与limit组合使用, 如offset limit都为空, 则不分页
limit Optional 当页记录数
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "offset" : 0,  //分页偏移量, 透传
  6.         "total" : 5,   //共5条记录. 
  7.         "array":[
  8.             {
  9.                 "no": 1,                     //名次
  10.                 "driver":{
  11.                     "id" : 5,
  12.                     "user": "khan",              //用户名
  13.                     "true_name": "khan.lau",     //姓名
  14.                     "nick": "khan.lau",          //昵称
  15.                 },
  17.                 "car" :{
  18.                     "id":1,
  19.                     "brand": "保时捷",           //车辆品牌
  20.                     "model": "Panamera",         //车辆型号
  21.                 },
  22.                 "record": {
  23.                     "id":1,
  24.                     "reaction_time": 500,        //启动反应时间
  25.                     "elapsed_time": 12500,       //04比赛完成时间
  26.                     "vehicle_speed": 230000      //尾速
  27.                 }
  28.             },   
  29.             ......
  30.         ]
  31.     }
  32. }

3.17 报名

活动报名接口

URL:
https://host:port/order

参数

Name Description
sid http header auth_cookie
user 用户名
token token
pid 活动场次id
true_name 真实姓名
phone 联系电话
produce_type watch:门票, join:车手报名费
pay_type wepay:微信支付, alipay:支付宝, quickplay:快钱, uniplay:银联
id_type Optional 身份证件类别, join类型时必填, 0:身份证, 1:驾驶证, 2:护照, 3:军官证, 4:港澳, 5:台湾, 6:学生证
id_card Optional 身份证件号码, join类型时必填
email Optional 邮箱, join类型时必填
address Optional 联系地址, join类型时必填
sns Optional 微信号, join类型时必填
join_type Optional 车手身份, null或""为个人, 否则为所属机构名称, join类型时必填
cid Optional 参赛车辆id, watch类型时, 必须为空, join类型时, cid为空或为空字符串, 则新增车辆, 忽略brand, model, 否则为参赛车辆id
brand Optional 报名车辆, join类型并且cid为空时必填
model Optional 报名车辆型号, join类型并且cid为空时必填
car_sn Optional 报名车辆车架号, join类型并且cid为空时必填
hp Optional 报名车辆功率, 单位为马力, join类型并且cid为空时必填
is_turbo Optional 是否为涡轮增压, boolean型, join类型并且cid为空时必填
displacement Optional 排量, 单位为L*100, join类型并且cid为空时必填
driver_type Optional 驱动形式, 0"前驱", 1"后驱", 2"后置后驱", 3"四驱", join类型并且cid为空时必填
group Optional 比赛分组id, 见2.11, join类型必填
descript Optional 改装描述
file Optional 身份证照片与驾驶证照片, 文件类型, join类型必填, 身份证文件名必须固定为:id_card, 驾驶证文件名必须固定为:driver_card

* 注意: 该接口必须以multipart/form-data方式提交
* 如果使用已存在车辆cid报名, 同时又提供了brand model car_sn hp is_turbo displacement driver_type 则修改车辆信息, 如果未使用已存在车辆cid, 则brand model car_sn hp is_turbo displacement driver_type为必填字段.

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "order" : order
  6.     }
  7. }

3.18 微信支付

微信支付接口

URL:
https://host:port/wxpay

参数

Name Description
sid http header auth_cookie
user 用户名
token token
oid 订单表id

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "pay" : {
  6.             "prepay_id" : "3f234axxxxx"
  7.         }
  8.     }
  9. }

3.19 支付宝支付

支付宝支付接口

URL:
https://host:port/alipay

参数

Name Description
sid http header auth_cookie
user 用户名
token token
oid 订单表id

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "res" : "签名字符串"
  6.     }
  7. }

3.20 获取有效的比赛场次

比赛场次检索接口

URL:
https://host:port/daemon/filtered_party

参数

Name Description
search Optional 活动截止时间戳
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "array":[
  6.             Party,  //party 定义见协议 2.5
  7.             ......
  8.         ]
  9.     }
  10. }

3.21 获取指定场次的车手信息

指定比赛参与车手检索接口

URL:
https://host:port/daemon/filtered_driver

参数

Name Description
search 活动场次id
order Optional 按活动开始时间排序, desc, asc, 默认asc

response
请求成功:

  1. {
  2.     "code": 200,
  3.     "message": "S_OK",
  4.     "data": {
  5.         "array":[
  6.             {
  7.                 "id": 123ul,     //order id
  8.                 "pid": 12ul,     //party id
  9.                 "cid": 1ul,      //car id
  10.                 "user" : Driver  //Driver 定义见协议 2.3
  11.             },
  12.             ......
  13.         ]
  14.     }
  15. }
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注