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

购书系统协议文档

购物车协议


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

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 发票管理.

发票抬头管理

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