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

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. .... //其他字段,可自行扩展
  12. }

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, //操作类型, 1app内跳转, 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. },
  16. "car" :{
  17. "id":1,
  18. "brand": "保时捷", //车辆品牌
  19. "model": "Panamera", //车辆型号
  20. },
  21. "record": {
  22. "id":1,
  23. "reaction_time": 500, //启动反应时间
  24. "elapsed_time": 12500, //04比赛完成时间
  25. "vehicle_speed": 230000 //尾速
  26. }
  27. },
  28. ......
  29. ]
  30. }
  31. }

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. }
添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注