[关闭]
@lina 2020-08-04T11:53:00.000000Z 字数 7892 阅读 365

秒达云快递 小程序1.0 接口文档

列表项
秒云达 1.0 小程序

1、项目约定

1.1 基本约定

1.1.1 API Base Url

1.1.2 鉴权字段(身份标识)

  • X-auth-token : [string] 登录后获取的 token 信息, 取window.token 请求头带此字段
  • X-org-code : [string]https://www.zybuluo.com/mdeditor# 机构表识字段,所有请求均需要此字段，取window.orgCode 请求头带此字段
  • X-location : [string] 坐标 lng-lat 请求头带此字段
  • X-unique-key : [string] 服务端下发的标识，取window.uniqueKey 请求头带此字段
  • X-city : [string] 所在城市名称 请求头带此字段
  • X-platform-code : [string] 平台标识字段,所有请求均需要此字段，取window.platformCode 请求头带此字段

1.1.3 HTTP请求中字段要求

  • POST请求Content-Type为：Content-Type:application/x-www-form-urlencoded
  • 文件上传时Content-Type为：Content-Type:multipart/form-data
  • 对于：Content-Type:application/json：Content-Type:application/xml不保证完全支持，请谨慎使用

1.2 通用接口

1.2.1 通用接口URL

1.2.2 上传图片

通用图片上传文件服务

请求URL

POST
/imgupload

请求参数

  • file : 文件

响应

  1. {
  2.     error_code: 0,
  3.     data: {
  4.         url: 'http://xxx'
  5.     }
  6. }
  • url : [string] 文件的访问URL

1.2.3 验证码图片

注：请求图片时，需解析图片的cookie，不然无法认证

GET
/captcha

1.2.4 发送短信

POST
/verifycode

请求参数

  • captcha_code : [string] 图形验证码
  • phone : [string] 手机号

响应

  1. {
  2.     error_code: 0,
  3.     data: {
  4.     }
  5. }

1.3 通用响应字段

1.3.1 状态字段

  • error_code: [int] 服务器状态码，0 为正常状态，异常状态待定。
  • error_message：[string] 错误信息，但 error_code 不为 0 时返回

1.3.2 数据字段

  • data: [object] 数据字段，所有响应数据都在此字段中
  • list: [array]，当返回数据为列表时会将数据放在该字段

1.3.3 分页字段

  • page: [object] 分页信息，当返回数组数据时会携带该字段
    • current_page: [int] 当前页码，默认为1
    • total_page: [int] 总页数
    • page_size: [int] 每页数量：本项目常用page_size==10

示例

  1. {
  2.     error_code: 0,
  3.     data: {
  4.         key: value,
  5.         list: [{
  6.             key: value
  7.         }],
  8.         page {
  9.         }
  10.     }
  11. }

2、数据结构

2.1 常用字段含义

2.1.1 性别字段

sex:[int]

0: 未知
1: 男
2: 女

2.1.2 审核状态

verify_status:[int]

0: 审核中
1: 通过
2: 驳回

2.1.3 是否启用状态

status: [int]

0:未启用
1:启用

2.1.3 订单状态

status: [int]

0:待抢单
1:已抢单
2:已拒绝

2.2 核心结构

2.2.1 用户基本信息

  1. {
  2.     id: 123,
  3.     nick_name: '梦里花落知多少',
  4.     real_name: 'xx',
  5.     phone: '15500000000',
  6.     sex: 1,
  7.     avatars: 'http://image.com/1.jpeg',
  8.     id_number: 110101198803031321,
  9.     bank_number: '7112312321',
  10.     id_card_front: 'url',
  11.     id_card_back: 'url',
  12.     sign_photo: 'url',
  13.     company_id: 12,
  14.     region_id: 12,
  15.     bus_quarter_id: 23,
  16.     department_id: 12,
  17.     bus_depart_id: 12
  18. }
  • id: [int] 用户ID
  • nick_name: [string] 用户名
  • phone: [string] 用户手机
  • avatars: [string] 头像
  • real_name: [string] 姓名
  • sex: [integer] 性别
  • id_number: [string] 身份证号
  • bank_number: [string] 银行卡号
  • bank_name: [string] 银行名称
  • id_card_front: [string] 身份证正面照片url
  • id_card_back: [string] 身份证反面照片url
  • sign_photo: [string] 签字照片
  • company_id: [int] 快递公司id
  • region_id: [int] 大区id
  • bus_quarter_id: [int] 营业区id
  • department_id: [int] 分部id，可能为空
  • bus_depart_id: [int] 营业部id

2.2.2 首页数据（4月28号修改）

  1. {
  2.     @用户基本信息,
  3.     token: 'ssadaf',
  4.     last_month_income: 7777.23,
  5.     total_income: 121323.23,
  6.     bonus_left: 12.22, // 可提现奖励金数
  7.     undo_order: [
  8.         @待抢订单
  9.     ],
  10.     company:{
  11.         @快递公司
  12.     },
  13.     region: {
  14.         @大区
  15.     },
  16.     bus_quarter: {
  17.         @营业区
  18.     },
  19.     department: {
  20.         @分部
  21.     },
  22.     bus_depart: {
  23.         @营业部
  24.     }
  25. }
  • @用户基本信息
  • token: [string] 下发的token，需要每次请求带上
  • last_month_income: [float] 上月收入
  • total_income: [float] 总收入
  • undo_order: [array] 待抢订单列表
  • company: [string] 快递公司信息
  • region: [string] 大区信息
  • bus_quarter: [obj] 营业区信息
  • department: [obj] 分部信息（可能为null）
  • bus_depart: [string] 营业部信息

2.2.3 订单信息

  1. {
  2.     id: 12,
  3.     courier_id: 1232,
  4.     remark: '中关村南大街',
  5.     start_time: '7112312321',
  6.     end_time: 7777.23,
  7.     status: 0,
  8.     company:{
  9.         @快递公司
  10.     },
  11.     region: {
  12.         @大区
  13.     },
  14.     bus_quarter: {
  15.         @营业区
  16.     },
  17.     department: {
  18.         @分部
  19.     },
  20.     bus_depart: {
  21.         @营业部
  22.     }
  23. }
  • id: [int] 订单ID
  • courier_id: [string] 快递员用户id
  • remark: [string] 线路备注
  • start_time: [date] 开始时间
  • end_time: [date] 结束时间
  • status: [integer] 订单状态
  • company: [obj] 快递公司信息
  • region: [obj] 大区信息
  • bus_quarter: [obj] 营业区信息
  • department: [obj] 分部信息（可能为null）
  • bus_depart: [obj] 营业部信息

2.2.4 公司、大区、营业区等

公司

  1. {
  2.     id: 12,
  3.     company_name: 1232,
  4.     contact_name: '中关村南大街',
  5.     contact_phone: '7112312321',
  6.     status: 0,
  7.     province_id: 0,
  8.     province_name: 0,
  9.     city_id: 0,
  10.     city_name: 0,
  11.     county_id: 0,
  12.     county_name: 0,
  13.     addr: 0,
  14. }
  • id: [int] 公司ID
  • company_name: [string] 公司名称
  • contact_name: [string] 联系人姓名
  • contact_phone: [string] 联系人电话
  • status: [int] 启用弃用状态
  • province_id: [string] 省份id
  • province_name: [string] 省份名称
  • city_id: [string] 城市id
  • city_name: [string] 城市名称
  • county_id: [string] 区县id
  • county_name: [string] 区县名称
  • addr: [string] 具体地址

其他的看数据库吧，就不一一写出来，字段基本都一样的

2.2.5 分部和营业部

分部相对于公司等，多个一个后台管理用户对象

  1. {
  2.     id: 12,
  3.     department_name: 1232,
  4.     contact_name: '中关村南大街',
  5.     contact_phone: '7112312321',
  6.     status: 0,
  7.     province_id: 0,
  8.     province_name: 0,
  9.     city_id: 0,
  10.     city_name: 0,
  11.     county_id: 0,
  12.     county_name: 0,
  13.     addr: 0,
  14.     user: {
  15.         username: 'xxx'
  16.     }
  17. }
  • id: [int] 分部ID
  • department_name: [string] 分部名称
  • contact_name: [string] 联系人姓名
  • contact_phone: [string] 联系人电话
  • status: [int] 启用弃用状态
  • province_id: [string] 省份id
  • province_name: [string] 省份名称
  • city_id: [string] 城市id
  • city_name: [string] 城市名称
  • county_id: [string] 区县id
  • county_name: [string] 区县名称
  • addr: [string] 具体地址
  • user: [obj] 后台管理对象

营业部就不列出来，字段基本都一样的

3、接口列表

3.1 用户类接口

3.1.0 签署协议接口 （新增）

请求URL

POST
/ExtsignSelf

请求参数

open_id

响应

  2. @签署合同页面

3.1.1 认证注册接口 (v2.0添加推荐用户introduce_token）

请求URL

POST
/register

请求参数

  • photo: [string] 手机号码 【必填】
  • real_name: [string] 真实姓名【必填】
  • verify_code: [string] 验证码 【必填】
  • id_card_front: [string] 身份证正面照片url【必填】
  • id_card_back: [string] 身份证反面照片url【必填】
  • id_number: [string] 身份证号【必填】
  • bank_name: [string] 银行名称【必填】
  • bank_number: [string] 银行卡号号【必填】
  • sign_photo: [string] 签字照片【必填】
  • company_id: [int] 快递公司id【必填】
  • region_id: [int] 大区id【必填】
  • bus_quarter_id: [int] 营业区id【必填】
  • bus_depart_id: [int] 营业部id【必填】
  • token: [string] token【必填】
  • raw_data: wx.getUserInfo返回值
  • iv: wx.getUserInfo返回值
  • signature: wx.getUserInfo返回值
  • encrypted_data: wx.getUserInfo返回值
  • introduce_token: 推荐人的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         @首页数据
  5.     },
  6.     "error_message": ""
  7. }

3.1.2 个人资料接口 (首页数据接口）

请求URL

GET
/user/info

请求参数

header中X-auth-token为下发的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         @首页数据
  5.     },
  6.     "error_message": ""
  7. }

3.1.3 订单列表接口

请求URL

GET
/order

请求参数

header中X-auth-token为下发的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data":[
  4.             @订单信息
  5.     ],
  6.     "error_message": ""
  7. }

3.1.4 收入明细列表接口

请求URL

POST
/income

请求参数

header中X-auth-token为下发的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         "data": {
  5.             "2018-10": [@收入信息],
  6.             "2018-09": [@收入信息],
  7.         },
  8.         "undraw": {
  9.             "2018-10-01": 10000, //未提现的单子，总金额
  10.             "2018-10-16": 10000, //未提现的单子，总金额
  11.         },
  12.         "courier": {
  13.             @快递员信息（包括银行卡等信息）
  14.         }
  15.     },
  16.     "error_message": ""
  17. }

3.1.5 所有公司、大区、营业区接口（用于表单选择）

请求URL

GET
/company
/region?company_id=1
/bus_quarter?company_id=1&region_id=1
/bus_depart?company_id=1&region_id=1&bus_quarter_id=1

请求参数

分别获取公司、大区、营业部、营业区，需要带上各自参数

响应

  1. {
  2.     "error_code": 0,
  3.     "data":[
  4.         @公司、大区、营业部、营业区
  5.     ],
  6.     "error_message": ""
  7. }

3.1.6 财务提现

请求URL

PUT
/income/all

请求参数

  • sign_photo: [string]签名图片
  • undraw_arr: [array]未提现财务，为3.1.4接口中下发的undraw的时间数组

响应

  1. {
  2.     "error_code": 0,
  3.     "data": null,
  4.     "error_message": ""
  5. }

3.1.7 用户未抢订单列表接口

请求URL

GET
/undoOrder

请求参数

header中X-auth-token为下发的token
page：页码

响应

  1. {
  2.     "error_code": 0,
  3.     "data":[
  4.         "list":[
  5.             @未抢订单信息
  6.         ],
  7.         "totle":@数据条数
  8.     ],
  9.     "error_message": ""
  10. }

4.1 微信小程序接口

4.1.1 微信小程序登陆接口

注：此接口有两种返回值,根据响应值的不同，做出相应的操作

请求URL

GET
/weixin/login

请求参数

  • code: 通过wx.login获取【必填】

响应
注：当用户第一次进入程序时，接口返回session_token，小程序将此值存入strorage。然后调用wx.getUserInfo（withCredentials需传true）后，调用过3.1.1接口获取用户token
跳转到认证注册页面

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         'session_token':'aaaa'
  5.     },
  6.     "error_message": ""
  7. }

响应
注：当后台识别登陆用户后，直接返回用户信息（含token）

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         @首页信息
  5.     },
  6.     "error_message": ""
  7. }

4.1.2 小程序发送短信接口

注：小程序特殊处理

请求URL

POST
/miniprogram/verifycode

请求参数

  • phone: phone【必填】
  • token: token【必填】

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.     },
  5.     "error_message": ""
  6. }

5 银行卡号判断接口

请求URL

POST
/bank_judge

请求参数

  • bank_num: [string]【必填】

响应
相应的银行名称，和该银行卡号是否合法

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         "bank_name": "招商银行",
  5.         "is_valid": true  // 不合法则返回false
  6.     },
  7.     "error_message": ""
  8. }

6 签到逻辑（8月3号新增）

6.1 签到接口

必须当日推荐抢单后才能调用

请求URL（请求头需要有token信息）

POST
/checkin

请求参数

  • X-location : [string] 坐标 lng-lat 请求头带此字段
  • clock_in_addr 签到地址

响应
签到成功时，data里返回红包的数值，data为空时，则为领取红包失败。

  1. {
  2.     "error_code": 0,
  3.     "data": 1.22,
  4.     "error_message": "签到成功"
  5. }

6.2 获取当日推荐订单

请求URL（请求头需要有token信息）

GET
/order_today

请求参数

无

  1. {
  2.     "error_code": 0,
  3.     "data": {
  4.         // 当日订单信息
  5.     },
  6.     "error_message": "签到成功"
  7. }

6.3 其他订单（还是原来那个接口/undoOrder）

返回的data里多返回了一个own_list（只有第一页返回，其他时为空数组），表示自己待抢单的，不包括今天推荐订单

6.4 签到是否处于有效范围

请求URL（请求头需要有token信息）

GET
/checkin/is_valid

请求参数

  • X-location : [string] 坐标 lng-lat 请求头带此字段
  1. {
  2.     "error_code": 0,
  3.     "data": true, // true表示有效，false表示无效
  4.     "error_message": "签到成功"
  5. }

6.5 财务收入（按月分页）

请求URL（请求头需要有token信息），原来的/income接口不再下发每日数据

GET
/income_by_month

请求参数

  • month_time : [string] 月份，例如2019-01
  • pageSize : [integer] 分页，默认10
  • page : [integer] 当前页数，默认1
  1. {
  2.     "error_code": 0,
  3.     "data": {
  4.         "list": [{
  5.             "id": 71,
  6.             "courier_id": 229,
  7.             "status": 1,
  8.             "amount": 600, // 当日收入，已经计算过了
  9.             "month_time": "2019-01-07 00:00:00",
  10.             "available_withdraw": "0.00",
  11.             "cur_month_already_withdraw": "600.00",
  12.             "cur_month_remain_withdraw": "3500.00",
  13.             "star": 4,
  14.             "order_desc": "第7次，80个包裹，其中10个重型包裹，超长包裹13，超长距离包裹5个。",
  15.             "bus_require": "妙衡公司",
  16.             "sign_photo": "http://api.ztb.alpha.flashdiet.cn/uploads/2019-01/784631547027035.png",
  17.             "sign_time": "2019-01-09 17:43:56",
  18.             "liability_compensation": null,
  19.             "platform_award": null
  20.         }],
  21.         "total": 25,
  22.         "total_page": 3,
  23.     }
  24.     "error_message": "签到成功"
  25. }

6.6 获取法大大身份证照片（原来的身份证图片不需要上传了）

根据courier中下发的fdd_head_photo来获取具体的图片，

GET
/fdd_head_photo/{uuid}

请求参数

  • uuid : [string] 根据courier中下发的fdd_head_photo
  1. 返回图片

6.7 快递员添加bus_type字段（必填）

bus_type字段表示业务类型，为int类型

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