[关闭]
@lina 2020-08-17T15:23:07.000000Z 字数 11033 阅读 346

新版货达人快递 小程序1.1 接口文档

列表项
新版货达人 1.1 小程序

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.1 认证注册接口 (添加队员队长字段）

请求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
  • leader_id: [string] 角色为队员时必填，为队长的courier_id
  • role_type: [int] 0队长，1队员【必填】

响应

  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.         leader: {
  6.             "id": 12,
  7.             "real_name": "xx",
  8.             "leader_id": 1
  9.         }
  10.     },
  11.     "error_message": ""
  12. }

3.1.3 根据手机号获取队长

请求URL

GET
/courier/get_leader

请求参数

  • phone: [string] 手机号必须是11位手机号 【必填】

响应

  1. {
  2.     "status": 0,
  3.     "msg": "保存成功",
  4.     "data": [
  5.         {
  6.             "id": 1, // courier表对应的id
  7.             "real_name": "姚明",
  8.         }
  9.     ]
  10. }

3.2 我的团队（队长才有）

3.2.1 我的团队列表接口

请求URL

GET
/my_team

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         @队长信息
  5.         team_total_income: 1222, // 团队总收入
  6.         teammates: [ // 队员信息
  7.             {
  8.                 "id": 12,
  9.                 "total_income": 121323.23,
  10.                 "real_name"："111",
  12.             }
  13.         ]
  14.     },
  15.     "error_message": ""
  16. }

3.2.2 查看队员收入明细列表接口

请求URL

GET
/courier/${courier_id}/income

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         hist_income: 1222, // 历史总收入
  5.         last_income: 1222, // 最近收入
  6.         'total_liability_compensation': 111,
  7.         'total_platform_award': 11,
  8.     },
  9.     "error_message": ""
  10. }

3.2.3 队长查看队员的财务收入（按月分页）

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

GET
/courier/${courier_id}/income_by_month

请求参数

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

3.3 账务提现（新增）

3.3.1 钱包首页部分数据财务接口（原接口/income弃用）

这接口返回的数据和3.2.2接口返回的数据格式一致
请求URL

GET
/income

/user/info接口返回用户信息不再下发财务相关的信息

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         hist_income: 1222, // 历史总收入
  5.         last_income: 1222, // 最近收入
  6.         withdraw_amt: 122, //可提现收入
  7.         'total_liability_compensation': 111,
  8.         'total_platform_award': 11,
  9.         can_withdraw: true, // true表示可以提现（提现按钮可以点击，否则不可以点击）
  10.     },
  11.     "error_message": ""
  12. }

3.3.2 获取提现信息

请求URL

GET
/income/withdraw

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         start_date: '2019-09-01',
  5.         end_date: '2019-09-15',
  6.         bus_require: '业务需求方',
  7.         item_name: '费用项目',
  8.         amount: 1222,// 总金额
  9.         withdraw_amt: 111,// 可提现金额
  10.         fee: 12, 
  11.         fee_rate: 0.03,//前端需求转成3%
  12.         其他信息在用户信息里
  13.     },
  14.     "error_message": ""
  15. }

3.3.3 提现接口（原接口弃用/income/all）

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

PUT
/income/withdraw

（提交前一个接口下发的start_date、end_date，amount用于校验提现信息）
请求参数

  • amount : [number] 总金额
  • start_date : [string] 开始时间
  • end_date : [string] 结束时间
  • sign_photo : [string] 签字图片

响应

  1. {
  2.     "error_code": 0,
  3.     "data": null,
  4.     "error_message": "当前无法提现|提现金额不正确"
  5. }

3.3.4 提现历史记录

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

GET
/income/hist

（提交前一个接口下发的amount、fee，用于校验提现信息）
请求参数

  • pageSize : [number] 分页
  • page : [number] 分页

响应

  1. {
  2.     "error_code": 0,
  3.     "data": {
  4.         "total": 25,
  5.         "total_page": 3,
  6.         "list": [{
  7.             withdraw_amt: 111,// 提现金额
  8.             fee: 12, 
  9.             draw_time: '2012-01-01 12:21:21'
  10.         }]
  11.     },
  12.     "error_message": "当前无法提现|提现金额不正确"
  13. }

3.4 红包提现（新增）

3.4.1 钱包首页部分数据红包接口

请求URL

GET
/envelope

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         hist_elp: 1222,
  5.         withdraw_elp: 1222,
  6.         expire_time: '2018-01-01 12:00:00', // 拆红包的过期时间
  7.         has_elp: true, // true表示可以有拆红包
  8.         can_withdraw: true, // true表示可以点击红包提现
  9.     },
  10.     "error_message": ""
  11. }

3.4.2 获取红包提现信息

请求URL

GET
/envelope/withdraw

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         start_date: '2019-09-01',
  5.         end_date: '2019-09-15',
  6.         bus_require: '业务需求方',
  7.         item_name: '费用项目',
  8.         amount: 1222,// 总金额
  9.         withdraw_amt: 111,// 可提现金额
  10.         fee: 12, 
  11.         fee_rate: 0.03,//前端需求转成3%
  12.         其他信息在用户信息里
  13.     },
  14.     "error_message": ""
  15. }

3.4.3 红包提现接口

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

PUT
/envelope/withdraw

（提交前一个接口下发的start_date、end_date，amount用于校验提现信息）
请求参数

  • amount : [number] 总金额
  • start_date : [string] 开始时间
  • end_date : [string] 结束时间
  • sign_photo : [string] 签字图片
    header中X-auth-token为下发的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data": null,
  4.     "error_message": "当前无法提现|提现金额不正确"
  5. }

3.4.4 拆红包

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

POST
/envelope/open

请求参数

  • expire_time : [string] 下发的过期时间，用来校验是哪个红包
    header中X-auth-token为下发的token

响应

  1. {
  2.     "error_code": 0,
  3.     "data": 1.5,// 红包金额
  4.     "error_message": "红包已过期"
  5. }

3.5 注册红包（10.19新增）

注册红包是在用户注册，被管理员第一次审批通过后才会有的（再次驳回第二次审批通过后不会有注册红包），而且一个用户最多只有一个注册红包

用户表里courier添加pass_elp_amt和elp_status两个字段，
elp_status注册红包状态
0 - 当前木有红包
1 - 有红包待拆
2 - 已拆过领过红包

小程序端应该先调用用户信息接口，如果elp_status == 1表示有注册红包可以拆，弹窗给用户拆红包，然后调用下面拆注册红包的接口

3.4.1 拆注册红包接口（采用的秒达云原来的提现到零钱的接口）

请求URL

POST
/wechat/withdraw

请求参数

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

响应

  1. {
  2.     "error_code": 0, // 不为0 的时候表示出现异常了，比如企业账户没钱等情况下
  3.     "data": 1.2, // 红包金额
  4.     "error_message": ""
  5. }

4 通达云接口

4.1 账务提现（完全修改）

4.1.1 钱包首页部分数据财务接口（原接口/income弃用）

请求URL

GET
/income

请求参数

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

响应

  1. {
  2.     "error_code": 0,
  3.     "data":{
  4.         courier: {
  5.             amount: 122, //可提现收入,
  6.             快递员信息，包括历史收入啥的
  7.         },
  8.         can_withdraw: true, // true表示可以提现（提现按钮可以点击，否则不可以点击）,
  9.         withdraw_info: { // 提现信息，只有can_withdraw为true才有
  10.             start_date: '2019-09-01',
  11.             end_date: '2019-09-15',
  12.             bus_require: '业务需求方',
  13.             item_name: '费用项目',
  14.             amount: 1222,// 提现金额
  15.         }
  16.     },
  17.     "error_message": ""
  18. }

4.1.2 提现接口（原接口弃用/income/all）

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

PUT
/income/withdraw

（提交前一个接口下发的start_date、end_date，amount用于校验提现信息）
请求参数

  • amount : [number] 提现金额
  • start_date : [string] 开始时间
  • end_date : [string] 结束时间
  • sign_photo : [string] 签字图片

响应

  1. {
  2.     "error_code": 0,
  3.     "data": null,
  4.     "error_message": "当前无法提现|提现金额不正确"
  5. }

4.1.4 提现历史记录（先不做）

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

GET
/income/hist

请求参数

  • pageSize : [number] 分页
  • page : [number] 分页

响应

  1. {
  2.     "error_code": 0,
  3.     "data": {
  4.         "total": 25,
  5.         "total_page": 3,
  6.         "list": [{
  7.             withdraw_amt: 111,// 提现金额
  8.             draw_time: '2012-01-01 12:21:21'
  9.         }]
  10.     },
  11.     "error_message": ""
  12. }

4 预支付需求接口

4.1 当前提现规则

请求URL

GET
/withdrawal/config

请求参数

响应

  1. {
  2.     "error_code": 0,
  3.     "error_message": "",
  4.     "data": {
  5.         "config": {
  6.             "type": 2,
  7.             "after_day": 5,
  8.             "percent_wages": 5,
  9.             "withdrawal_config": [
  10.                 {
  11.                     "month_type": 1,
  12.                     "day": 15,
  13.                     "fee": 3
  14.                 },
  15.                 {
  16.                     "month_type": 1,
  17.                     "day": 25,
  18.                     "fee": 2
  19.                 },
  20.                 {
  21.                     "month_type": 2,
  22.                     "day": 3,
  23.                     "fee": 1
  24.                 },
  25.                 {
  26.                     "month_type": 2,
  27.                     "day": 5,
  28.                     "fee": 0.5
  29.                 }
  30.             ]
  31.         }
  32.     }
  33. }

4.2 我的预支记录

请求URL

GET
/withdrawal/list

请求参数

  • pageSize : [integer] 分页，默认10
  • page : [integer] 当前页数，默认1

响应

  1. {
  2.     "error_code": 0,
  3.     "error_message": "",
  4.     "data": {
  5.         "list": [
  6.             {
  7.                 "id": 41,
  8.                 "courier_id": 84,
  9.                 "month_start": "2020-06",
  10.                 "month_end": "2020-07",
  11.                 "amount": "4000.00", //预支金额
  12.                 "withdraw_amt": "3880.00",//实际到账金额
  13.                 "fee": "3.00",//手续费
  14.                 "draw_time": "2020-08-10 23:43:49", //预支时间
  15.                 "sign_photo": "https://api.ane.huodaren.net/uploads/2020-06/223681591376047.png",
  16.                 "order_sn": "",
  17.                 "status": 2,//状态 1提现中 2提现成功 3提现失败
  18.                 "last_reply_state": "",
  19.                 "withdrawal_config": null,
  20.                 "created_at": "-0001-11-30 00:00:00",
  21.                 "updated_at": "2020-08-12 23:04:31",
  22.                 "month": "2020-06,2020-07" //涉及金额月份
  23.             }
  24.         ],
  25.         "total": 1,
  26.         "total_page": 1
  27.     }
  28. }

4.3 可预支金额

请求URL

GET
/withdrawal/amount

请求参数

响应

  1. {
  2.     "error_code": 0,
  3.     "error_message": "",
  4.     "data": {
  5.         "total": "3000.00",//累计收入 未计算百分比
  6.         "amount": "2100.00",//可预支金额  total * 预支比例
  7.         "withdraw": "2058.00", //实际到账金额
  8.         "fee": "42.00",//手续费
  9.         "income_list": [
  10.             //关联的收入记录
  11.         ],
  12.         "month": [
  13.             "2020-07"//涉及月份
  14.         ]
  15.     }
  16. }

4.4 提现

请求URL

POST
/withdrawal/cash

请求参数

  • sign_photo : [string] 签名的图片地址

响应

  1. {
  2.     "error_code": 0,
  3.     "error_message": "您的申请已成功，请关注订单状态",
  4.     "data": {
  5.         "withdraw": 100
  6.     }
  7. }
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注