代理等级管理

1. 获取代理等级列表

更新于 2026-08-01：等级商品数量与详情列表统一查询口径，缺失分类的商品按“未分类”返回

更新于 2025-12-20：返回数据新增对接码列表、代理数量、商品数量

接口地址： /merchantapi/distribution/agentlevel/list

请求方式： POST

请求参数：

参数名	类型	必填	说明
name	string	否	等级名称（模糊搜索）
status	int	否	状态：0=禁用，1=启用
remark	string	否	备注（模糊搜索）
page	int	否	页码
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 7,
        "user_id": 1000,
        "name": "金牌",
        "sort": 0,
        "remark": "",
        "status": 1,
        "create_time": "2025-11-09 15:49:59",
        "update_time": "2025-11-09 15:51:04",
        "codes": [
          // 该等级的对接码列表 ~~新增于 2025-12-20~~
          {
            "id": 1,
            "code": "DJM1234567890",
            "name": "金牌对接码",
            "status": 1,
            "create_time": "2025-11-19 16:34:13",
            "update_time": "2025-11-19 16:34:13",
            "use_count": 5 // 使用次数
          }
        ],
        "code_count": 1, // 对接码数量 ~~新增于 2025-12-20~~
        "agent_count": 5, // 代理数量 ~~新增于 2025-12-20~~
        "goods_count": 10 // 当前等级配置的有效商品数量，与 levelGoodsList 的 total 保持一致
      }
    ],
    "total": 2
  }
}

---

2. 创建代理等级

接口地址： /merchantapi/distribution/agentlevel/create

请求方式： POST

请求参数：

参数名	类型	必填	说明
name	string	是	等级名称
sort	int	否	排序值（默认 0）
remark	string	否	备注说明
status	int	否	状态：0=禁用，1=启用（默认 1）

响应示例：

{
  "code": 1,
  "msg": "创建成功"
}

业务规则：

• 最多只能创建 5 个代理等级，含隐藏等级
• 等级名称不能为空

---

3. 编辑代理等级

接口地址： /merchantapi/distribution/agentlevel/edit

请求方式： POST

请求参数：

参数名	类型	必填	说明
id	int	是	等级 ID
name	string	是	等级名称
sort	int	否	排序值
remark	string	否	备注说明
status	int	否	状态

响应示例：

{
  "code": 1,
  "msg": "编辑成功"
}

---

4. 删除代理等级

接口地址： /merchantapi/distribution/agentlevel/delete

请求方式： POST

请求参数：

参数名	类型	必填	说明
id	int	是	等级 ID

响应示例：

{
  "code": 1,
  "msg": "删除成功",
  "data": {
    "offline_goods_count": 3,
    "affected_agents": 2
  }
}

业务规则：

• 无论等级下是否存在商品配置、代理商或已经对接的商品，都允许删除。
• 删除时会自动关闭并删除该等级的商品价格配置和对接码，同时下架该等级已经对接出去的商品及其后续下级商品；不会下架上级自己的源商品。
• 已建立的商家代理关系和商品对接关系继续保留，但旧对接码失效、继续向下代理权限关闭。下级可获取新的对接码切换等级，切换后重新确认商品并上架。
• 也可以在“等级管理 → 查看商品”中提前关闭单个商品。这里的等级商品开关与商品编辑页中的对应等级开关使用同一套级联下架逻辑。

---

5. 获取可用代理等级列表

接口地址： /merchantapi/distribution/agentlevel/enabledlist

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "name": "金牌代理",
      "sort": 100,
      "status": 1
    }
  ]
}

说明： 只返回状态为启用的代理等级

---

6. 获取代理等级下的商品列表

新增于 2025-12-20

接口地址： /merchantapi/distribution/agentlevel/goodsList

请求方式： POST

请求参数：

参数名	类型	必填	说明
level_id	int	否	代理等级 ID（不传则查询所有等级）
user_id	int	否	按代理用户 ID 筛选
source	string	否	对接类型：1=等级代理，2=货源大厅代理
page	int	否	页码
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 100,
        "name": "商品名称",
        "price": "50.00",
        "cost_price": "40.00",
        "status": 1,
        "agent_username": "test1001",
        "relation_source": 1,
        "source_text": "等级代理",
        "parent_goods_name": "上级商品名称",
        "parent_goods_id": 50,
        "stock_quantity": 100
      }
    ],
    "total": 10
  }
}

---

7. 获取代理等级下的代理列表

新增于 2025-12-20

接口地址： /merchantapi/distribution/agentlevel/agentList

请求方式： POST

请求参数：

参数名	类型	必填	说明
level_id	int	是	代理等级 ID
page	int	否	页码
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 1001,
        "username": "test1001",
        "avatar": "...",
        "agent_level_id": 7,
        "bind_code_id": 1,
        "create_time": "2025-11-20 10:00:00",
        "goods_count": 5
      }
    ],
    "total": 5
  }
}

8. 获取代理等级下的商品 （自己的商品）

更新于 2026-08-01：列表包含已关闭配置，并新增等级商品可分销状态接口

新增于 2026-1-14

接口地址： /merchantapi/distribution/agentlevel/levelGoodsList

请求方式： POST

请求参数：

参数名	类型	必填	说明
level_id	int	是	代理等级 ID
name	string	否	商品名称关键词
page	int	否	页码
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 4,  // 商品id
        "name": "商品1e", // 商品名
        "price": "12.00", // 商品价格
        "stock_quantity": 302, // 商品库存
        "create_at": 1766300728, // 创建时间
        "goods_status": 1, // 商品上架状态
        "is_proxy": 0, // 是否为代理商品 是=1 否=0 （用于移除功能时 调用商品编辑接口的区分 0使用接口：/商户端手册/4.商品管理/2.商品管理.html#_4-编辑商品;   1使用接口 /商户端手册/4.商品管理/4.我代理的商品.html#_3-编辑代理商品 ）
        "agent_price": 17, // 给代理的进货销售价格
        "agent_status": 1, // 该等级下 该商品的 代理状态。允许被当前等级代理=1，否=0
        "cate_name": "xxx" // 分类名 
      }
    ],
    "total": 1
  }
}

说明：

• 返回当前商户配置到该代理等级的商品，包含已开启和已关闭的配置。
• agent_status 表示该商品在当前等级下是否允许分销；goods_status 表示商品自身上下架状态，两者不是同一个开关。
• 商品分类缺失或商品未分类时仍返回该商品，cate_name 为“未分类”；软删除商品不计入列表和等级商品数量。

9. 修改等级商品可分销状态

接口地址： /merchantapi/distribution/agentlevel/changeGoodsStatus

请求方式： POST

参数名	类型	必填	说明
level_id	int	是	代理等级 ID
goods_id	int	是	当前商户自己的商品 ID
status	int	是	可分销状态：0=关闭，1=开启

开启时会校验商品已开启代理分销、代理价格有效；代理商品的代理价格不能低于当前成本价。

关闭时会立即下架该等级已经对接出去的商品及其后续下级商品。创建订单和确认支付时，服务端还会重新校验整条代理供货链；上级关闭商品代理、等级商品对接或货源大厅供货后，相关代理商品不可继续成交。