[关闭]
@khan-lau 2015-06-16T13:53:19.000000Z 字数 3086 阅读 2169

购书系统协议文档

购物车协议

1 协议约定

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

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

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

  1. --response
  2. {
  3.     "ret": "err_code",
  4.     "error": "err_message"
  5. }

1.3 request

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

1.4 编码集

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

1.5 错误代码

ret字段

S_OK                          - 表示操作成功，同时返回对应的Session ID和用于cookie校验的值
FA_UNAUTHORIZED               - 表示用户名或者密码不匹配，或者用户不存在
FA_INVALID_VERIFY_CODE        - 校验码不正确 (备用)
FA_INVALID_SESSION            - Session不合法，通常是校验码已过期
FA_NEED_VERIFY_CODE           - 需要校验码 (备用)
FA_USER_LOCKED                - 用户处于锁定状态 (备用)
FA_USER_SUSPENDED             - 用户被禁用 (备用)
FA_USER_WRONG_STATUS          - 用户状态错误 (备用)

2 基础数据类型

2.1 商品信息

  1. "book":{
  2.     "id":51ul,              //ul代表unsigned long
  3.     "name":"erlang语言入门",
  4.     "memo":"简介",
  5.     "type":1,               //1为普通商品, 2为购物卡
  6.     "class":23,             //商品分类, 如: 计算机类, 文学类 
  7.     "price":25.5f,          //价格, 如果价格为负, 则表示从总价中减去的金额, 以实现优惠, 折扣, 和虚拟支付. 
  8.     "from":书店id,          //见协议2.3
  9.     "num" : 56,             //数量.  在商品展示时, 当做库存数量
  10.     ....                    //其他字段,可自行扩展
  12. }

2.2 书店信息

  1. "store":{
  2.     "id":123ul, 
  3.     "name":"新华书店",
  4.     "memo":"介绍",
  5.     ...                    //其他字段, 可自行扩展.
  6. }

2.3 商品分类

  1. "class":{
  2.     "id":33,
  3.     "name":"文学类",
  4.     "memo":"古典, 现代",
  5.     ....                   //其他字段, 可自行扩展.
  6. }

2.4 订单

  1. "order":{
  2.     "num" : 3,            //在购物车中, 当做交易商品的数量
  3.     "book" : book,        //见协议2.1
  4.     "istax" : true,       //是否已开具发票
  5.     ...                   //自行扩展
  6. }

2.5 储值卡, 或折扣卡, 或会员等级折扣之类影响支付的虚拟财物

  1. "card":{
  2.     "id":1231,           // id
  3.     "name":"1345-123-444-151", //卡号
  4.     "money":15.34,         //  代币金额, 支付时, 总价中减去该金额
  5.     "memo": "",
  6.     ....                 //  自行扩展
  7. }

接口说明

3.1 鉴权接口 login

鉴权接口.

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

URL:
https://url:port/login

参数

Name Description
sid token
user 用户id
passwd 密码

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3.     "data": {
  4.         "sid"           : <string> 
  5.     }
  6. }

请求失败

  1. {
  2.     "ret": "FA_UNAUTHORIZED",
  3.     "error": "用户名或者密码不匹配"
  4. }

3.2 取消鉴权接口 unlogin

取消鉴权

URL:
https://url:port/unlogin

参数

Name Description
sid token

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3. }

请求失败

  1. {
  2.     "ret": "FA_UNAUTHORIZED",
  3.     "error": "用户名或者密码不匹配"
  4. }

3.3 查询商品列表

根据关键字查询商品列表

URL:
https://url:port/searchBooks

参数

Name Description
sid token
class Optional 商品分类id (见协议2.3)
keyword Optional 搜索关键字, 可用空格区分多关键字
num Optional 商品数量 >= num, 可用于限定是否显示无库存商品
page Optional 页码

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3.     "data": {
  4.         "page" : 0,  //当前为第一页
  5.         "count" : 5, //共5页. 
  6.         "books":[
  7.             book,   --book定义见协议 2.1
  8.             book,
  9.             ......
  10.         ]
  11.     }
  12. }

3.4 购物车

3.4.1 加入购物车

将商品加入购物车

URL:
https://url:port/addCart

参数

Name Description
sid token
bookId 商品id (见协议2.1)
num Optional 商品数量, 默认为1

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3. }

3.4.2 从购物车删除商品或减少商品数量

将商品移出购物车

URL:
https://url:port/delCart

参数

Name Description
sid token
bookId 商品id (见协议2.1)
num Optional 商品数量, 默认为1

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3. }

3.4.3 搜索购物车

''' 可存本地 '''
''' 如需服务器存储 再订协议 '''

3.5 历史订单

根据关键字查询历史订单列表

URL:
https://url:port/searchHistory

参数

Name Description
sid token
keyword Optional 搜索关键字, 可用空格区分多关键字
page Optional 页码

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3.     "data": {
  4.         "page" : 0,  //当前为第一页
  5.         "count" : 5, //共5页. 
  6.         "orders":[
  7.             order,   --order定义见协议 2.4
  8.             order,
  9.             ......
  10.         ]
  11.     }
  12. }

3.6 获取用户储值卡

完成支付.

URL:
https://url:port/getCard

参数

Name Description
sid token

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3.     "data": {
  4.         "cards":[
  5.             card,   --card定义见协议 2.5
  6.             card,
  7.             ......
  8.         ]
  9.     }
  10. }

3.7 支付

完成支付.

注意事项, 支付时, cards 金额汇总 - orders 价格汇总 , 结果 == 0 , 直接完成支付, 进入配送流程
结果 > 0 , 存储余额, 多种虚拟支付手段的支付比例, 和运营人员商议.
结果 < 0 , 进入真实货币支付流程.

URL:
https://url:port/pay

参数

Name Description
sid token
orders 订单(order)数组 (见协议2.1)
cards 购物卡(card)数组 (见协议2.5)
reciver 收货人信息

response
请求成功:

  1. {
  2.     "ret": "S_OK",
  3. }

3.8 用户信息管理

3.8.1 收货信息管理

包含真实姓名, 收货地址, 邮编, 电话.

3.8.2 实名认证管理

身份证号. 身份证照片管理

3.8.3 发票管理.

发票抬头管理

添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注