1. 我代理的商品列表

更新于 2026-08-01：代理商品库存统一返回顶级货源商品的实时可用库存

更新于 2026-02-03：新增异常状态筛选和上级商品状态判断

接口地址： /merchantapi/distribution/goods/myAgentGoods

请求方式： POST

请求参数：

参数名	类型	必填	说明
id	int	否	商品 ID
cate_id	int	否	分类 ID
name	string	否	商品名称
status	int	否	状态
has_error	int	否	是否只查询异常商品：1=是（包括价格亏损、上级删除、上级下架） 新增于 2026-02-03
page	int	否	页码
limit	int	否	每页数量

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 100,
        "name": "QQ币100元",
        "cate_name": "游戏点卡",
        "price": "95.00",
        "stock": 1000, // 兼容字段：顶级货源商品的实时可用库存
        "stock_quantity": 1000, // 当前库存字段：与 stock 含义一致
        "cards_stock_counts": 1000, // 卡密库存兼容字段：与 stock 含义一致
        "cards_sold_counts": 500, // 通过该商品售出的卡密数量
        "status": 1, // 状态 1:正常 2:下架
        "cost_price": "90.00", // 供货价格
        "parent_goods_status": 1, // 上级商品状态：-1=已删除 0=已下架 1=正常 ~~新增于 2026-02-03~~
        "parent_goods_status_text": "", // 上级商品状态文本 ~~新增于 2026-02-03~~
        "agent_relation_error": 0, // 代理关系是否异常：0=正常 1=异常
        "agent_relation_status_text": "", // 代理关系异常原因，如：代理关系不存在
        "proxy_goods_invalid": 0, // 代理商品是否失效：0=否 1=是。失效商品不允许编辑和上架
        "proxy_goods_invalid_text": "", // 失效原因，如：代理关系不存在、上级已删除、上级已下架
        // ...其余信息同我的商品列表字段含义信息
        "cate_name": "xxx", // 2025-12-15新增 上级商家 商品分类
        "parent_shop": { // 2025-12-15新增 上级商家 店铺信息
           "shop_name": "xxx" // 2025-12-15新增 上级商家 店铺名称
        },
        "proxy_type": 1, // 代理身份类型：1=等级代理 2=货源大厅
        "proxy_type_text": "等级代理" // 代理身份类型文本
      }
    ],
    "total": 10,
    "count": {
        "total_count": 10,  // 2025-12-15新增 对接商品数
        "online_count": 10, // 2025-12-15新增 对接商品数中上架数量
        "offline_count": 10, // 2025-12-15新增 对接商品数中下架数量
        "price_offline_count": 10 // ~~更新于 2026-02-03~~ 异常商品数量（包括价格亏损、上级删除、上级下架）
    }
  }
}

字段说明：

• parent_goods_status: 上级商品状态
  • -1: 上级已删除
  • 0: 上级已下架
  • 1: 正常
• parent_goods_status_text: 上级商品状态的文本描述
• agent_relation_error: 代理关系异常标记，1 表示当前商品的上级代理关系不存在、申请中或已拒绝；列表仍返回商品，但 cost_price 会按 0 返回
• agent_relation_status_text: 代理关系异常文本
• proxy_goods_invalid: 代理商品失效标记，1 表示该商品不允许编辑和上架。当前包括：代理关系异常、上级商品已删除、上级商品已下架
• proxy_goods_invalid_text: 代理商品失效原因
• has_error: 筛选参数，传 1 时返回所有异常商品（价格亏损 + 上级删除 + 上级下架）
• stock、stock_quantity、cards_stock_counts: 均为顶级货源商品的实时可用卡密库存。代理商品不单独持有卡密，三个字段为兼容不同版本的前端而同时保留

异常状态优先级：

1. 上级已删除（最高优先级）
2. 上级已下架
3. 价格亏损

---

2. 获取代理商品详情

接口地址： /merchantapi/distribution/goods/detail

请求方式： POST

请求参数：

参数名	类型	必填	说明
id	int	是	代理商品 ID

响应示例：

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "id": 100,
    "name": "QQ币100元",
    "price": "95.00",
    "cost_price": "90.00",
    "can_proxy": 0,
    "is_proxy": 1,
    "parent_user_id": 50,
    "source_user_id": 10,
    "hall_category_ids": [1, 3] // 大厅分类ID集合（2026-05-19新增，多选）
  }
}

说明：

• cost_price 为上级给的代理价格
• can_proxy 根据上级设置和代理层级自动判断

---

3. 编辑代理商品

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

请求方式： POST

请求参数：

参数名	类型	必填	说明
id	int	是	代理商品 ID
cate_id	int	是	分类 ID
name	string	是	商品名称
price	float	是	售价
sort	int	否	排序
wholesale_discount	int	否	是否开启批发优惠
wholesale_discount_list	array	否	批发价格列表
inventory_notify	int	否	库存预警值
sold_notify	int	否	售出通知
content	string	否	商品说明
remark	string	否	使用说明
proxy_sync_content	int	否	是否同步上级内容
hall_price	float	否	货源大厅价格
agent_prices	array	否	代理等级价格数组
hall_category_ids	array	否	2026-5-20新增 大厅分类ID数组（多选，hall_price>0 时必传）
sold_out_off	int	否	售完自动下架：0=否，1=是
auto_online_restock	int	否	补货自动上架：0=否，1=是
auto_offline_price_up	int	否	上级涨价自动下架：0=否，1=是
show_option	int	否	店铺显示设置：默认1

响应示例：

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

业务规则：

• 售价和最低批发价必须按每件至少高于成本价 0.01 元；零利润代理商品不能保存为可售配置
• 代理价格不能低于成本价
• can_proxy 不按前端提交值保存，由上级商品权限和代理层级计算；如果是二级或更高级别代理，强制关闭代理权限
• 上级不允许继续代理时，会强制清空 hall_price、hall_category_ids 和 agent_prices
• 修改货源大厅价格会异步检查下级代理商品，只下架价格不合适的下级商品
• hall_price>0 时必须提交有效的 hall_category_ids，分类必须存在且启用
• 上架、补货自动上架、上级调价检查和买家支付都会再次校验最低利润；不满足时不能上架或成交

4. 商品上下架

同 ./2.商品管理.md 商品上下架

5. 删除商品

同 ./2.商品管理.md 删除商品