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

新版货达人快递 小程序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",
  11. }
  12. ]
  13. },
  14. "error_message": ""
  15. }

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