logan

Appearance

1. 获取商品列表 ​

接口地址： /merchantapi/goods/good/list

请求参数：

参数名类型必填说明
idint否商品 ID（精确搜索）
cate_idint否分类 ID
namestring否商品名称（模糊搜索）
statusint否商品状态：0=下架，1=上架
stock_quantity_typestring否库存类型筛选：1=已售罄，2=库存预警，3=全部预警
pageint否页码（默认 1）
limitint否每页数量（默认 20）

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 3, // 商品ID
        "cate_id": 1, // 分类ID
        "user_id": 1000, // 商户ID
        "parent_user_id": 0, // 父级商户ID 前端无需关注
        "source_user_id": 0, // 源头商户ID 前端无需关注
        "parent_goods_id": 0, // 父级商品ID 前端无需关注
        "source_goods_id": 0, // 源头商品ID 前端无需关注
        "source": 0, // 商品来源 0:自己 1:对接码代理 2:货源大厅 前端无需关注
        "sort": 0, // 排序值
        "name": "1000的商品2", // 商品名称
        "price": "5.00", // 价格
        "cost_price": "2.00", // 成本价
        "hall_price": "0.00", // 货源大厅价格
        "wholesale_discount": 0, // 是否开启批发优惠 0:否 1:是
        "wholesale_discount_list": [], // 批发价格列表
        "limit_quantity_max": 0, // 限购数量上限
        "limit_quantity": 0, // 起购数量
        "inventory_notify": 0,
        "sold_notify": 0, // 售出通知 0:关闭 1:开启
        "content": "<p>2222</p>", // 商品说明
        "remark": "<p>222222222</p>", // 使用说明
        "status": 0, // 商品状态 0:下架 1:上架
        "sold_out_off": 0, // 售完下架 0:否 1:是
        "delivery_type": 1, // 发货方式 1:自动发货 2:手动发货
        "show_option": 1, // 显示选项 1:在店铺显示 2:不在店铺显示
        "create_at": "2025-11-19 17:16:44", // 创建时间
        "is_freeze": 0, // 平台冻结状态 0:正常 1:冻结
        "delete_at": null, // 删除时间
        "card_order": 0, // 发卡顺序 0:先卖老卡 1:先卖新卡 2:随机发卡
        "can_proxy": 0, // 是否允许代理销售 0:否 1:是
        "is_proxy": 0, // 是否为代理商品 0:否 1:是 前端无需关注
        "proxy_sync_content": 0, // 自动同步商品内容 0:不同步 1:同步 前端无需关注
        "event_give": [], // 活动赠送配置
        "addtion_give": [], // 附加赠送配置
        "stock_quantity": 0, // 库存数量
        "cate_name": "1000分类1", // 分类名称
        "cards_stock_counts": 0, // 库存卡密数量
        "cards_sold_counts": 0 // 已售出卡密数量
      }
    ],
    "total": 50
  }
}

说明：

  • 本接口为商家自营商品列表，为了保持通用性代理商品也是用的此模型，故部分不需要关注的字段 已经标注。
  • cards_stock_counts: 库存卡密数量
  • cards_sold_counts: 已售出卡密数量

2. 添加商品 ​

接口地址： /merchantapi/goods/good/add

仅允许请求参数：

参数名类型必填说明
cate_idint是分类 ID
namestring是商品名称
pricefloat是商品售价
cost_pricefloat是成本价
sortint否排序值（默认 0）
wholesale_discountint否是否开启批发优惠：0=否，1=是
wholesale_discount_listarray否批发价格列表
limit_quantityint否起购数量（默认 1）
limit_quantity_maxint否限购数量上限（0 表示不限购）
inventory_notifyint否库存预警值（0 表示不预警）
sold_notifyint否售出通知：0=关闭，1=开启
contentstring否商品说明
remarkstring否使用说明
card_orderint否发卡顺序：0=先卖老卡，1=先卖新卡
statusint否商品状态：0=下架，1=上架（默认 1）
event_givearray否活动赠送配置
addtion_givearray否附加赠送配置
can_proxyint否是否允许代理销售：0=否，1=是
hall_pricefloat否货源大厅价格
agent_pricesarray否代理等级价格数组

批发价格列表格式：

json
{
  "wholesale_discount_list": [
    {
      "num": 10, // 购买数量
      "price": 90.0 // 价格
    },
    {
      "num": 50,
      "price": 85.0
    }
  ]
}

活动赠送配置格式：

json
{
  "event_give": [
    {
      "num": 10, // 购买数量
      "give_num": 1 // 赠送数量
    }
  ]
}

附加赠送配置格式：

json
{
  "addtion_give": [
    {
      "good_id": 100, // 赠品商品ID
      "bug_num": 1, // 购买数量
      "give_num": 1 // 赠送数量
    }
  ]
}

代理等级价格格式：

json
{
  "agent_prices": [
    {
      "agent_level_id": 1,
      "agent_price": 92.0,
      "status": 1 // 状态：0=关闭，1=开启
    },
    {
      "agent_level_id": 2,
      "agent_price": 93.0,
      "status": 1
    }
  ]
}

响应示例：

json
{
  "code": 1,
  "msg": "添加商品成功"
}

错误响应：

json
{
  "code": 0,
  "msg": "商品价格必须大于成本价"
}

3. 获取商品详情 ​

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

请求参数：

参数名类型必填说明
idint是商品 ID

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "id": 3, // 商品ID
    "cate_id": 1,
    "user_id": 1000, // 商户ID
    "parent_user_id": 0, // 父级商户ID 前端无需关注
    "source_user_id": 0, // 源头商户ID 前端无需关注
    "parent_goods_id": 0, // 父级商品ID 前端无需关注
    "source_goods_id": 0, // 源头商品ID 前端无需关注
    "source": 0, // 商品来源 0:自己 1:对接码代理 2:货源大厅 前端无需关注
    "sort": 0, // 排序值
    "name": "1000的商品2", // 商品名称
    "price": "5.00", // 商品售价
    "cost_price": "2.00",
    "hall_price": "0.00", // 货源大厅价格
    "wholesale_discount": 0, // 是否开启批发优惠 0:否 1:是
    "wholesale_discount_list": [], // 批发价格列表
    "limit_quantity_max": 0, // 限购数量上限
    "limit_quantity": 0, // 起购数量
    "inventory_notify": 0, // 库存预警值
    "sold_notify": 0, // 售出通知 0:关闭 1:开启
    "content": "<p>2222</p>", // 商品说明
    "remark": "<p>222222222</p>", // 使用说明
    "status": 0, // 商品状态 0:下架 1:上架
    "sold_out_off": 0, // 售完下架 0:否 1:是
    "delivery_type": 1, // 发货方式 1:自动发货 2:手动发货
    "show_option": 1, // 显示选项 1:在店铺显示 2:不在店铺显示
    "create_at": "2025-11-19 17:16:44",
    "is_freeze": 0, // 平台冻结状态 0:正常 1:冻结
    "delete_at": null, // 删除时间
    "card_order": 0, // 发卡顺序 0:先卖老卡 1:先卖新卡 2:随机发卡
    "can_proxy": 0, // 是否允许代理销售 0:否 1:是
    "is_proxy": 0, // 是否为代理商品 0:否 1:是 前端无需关注
    "proxy_sync_content": 0, // 自动同步商品内容 0:不同步 1:同步 前端无需关注
    "event_give": [], // 活动赠送配置
    "addtion_give": [], // 附加赠送配置
    "stock_quantity": 0 // 库存数量
  }
}

4. 编辑商品 ​

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

请求参数： 与添加商品相同，需额外传入 id 参数

参数名类型必填说明
idint是商品 ID
.........其他参数同添加商品

响应示例：

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

业务规则：

  1. 编辑商品时会同步更新所有代理商品的发卡顺序和限购设置
  2. 关闭代理销售时，会下架所有下级代理商品
  3. 下架可代理商品时，会同时下架所有下级代理商品
  4. 修改货源大厅价格/代理价格时，会更新代理关系中的成本价并下架相关代理商品

5. 删除商品 ​

接口地址： /merchantapi/goods/good/del

请求参数：

参数名类型必填说明
idint是商品 ID

响应示例：

json
{
  "code": 1,
  "msg": "删除商品成功"
}

说明： 删除操作为软删除，商品数据会保留在数据库中;如果有下级代理商品则会被下架

6. 商品上下架 ​

接口地址： /merchantapi/goods/good/status

请求参数：

参数名类型必填说明
idint是商品 ID
valint是状态值：0=下架，1=上架

响应示例：

json
{
  "code": 1,
  "msg": "上架成功"
}

错误响应：

json
{
  "code": 0,
  "msg": "商品价格不能小于成本价"
}
...... 其余各种业务错误详情都如此，只msg不同

业务规则：

  1. 上架时检查：
    • 商品必须绑定分类
    • 代理商品需检查上级商品链路状态
    • 代理商品需检查上级商户信誉分（≥70 分）
    • 商品价格不能低于成本价
    • 平台未冻结该商品
  2. 下架时：
    • 如果是可代理商品，会同时下架所有下级代理商品

7. 商品回收站列表 ​

接口地址： /merchantapi/goods/good/trash

请求参数：

参数名类型必填说明
cate_idint否分类 ID
namestring否商品名称（模糊搜索）
pageint否页码（默认 1）
limitint否每页数量

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "cate_id": 10,
        "cate_name": "游戏点卡",
        "name": "QQ币100元",
        "price": "95.00",
        "status": 0,
        "delete_at": "2025-11-19 17:16:44"
        ...同上商品列表
      }
    ],
    "total": 5
  }
}

8. 批量恢复商品 ​

接口地址： /merchantapi/goods/good/recover

请求参数：

参数名类型必填说明
idsarray是商品 ID 数组

请求示例：

json
{
  "ids": [1, 2, 3]
}

响应示例：

json
{
  "code": 1,
  "msg": "恢复成功"
}

9. 获取分类下的商品列表(value+label 格式，用于选择卡密页商品列表) ​

接口地址： /merchantapi/goods/good/getGoodsByCategory

请求参数：

参数名类型必填说明
cate_idint是分类 ID

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "value": 1,
      "label": "QQ币100元"
    },
    {
      "value": 2,
      "label": "QQ币50元"
    }
  ]
}

说明： 返回 label-value 格式，用于下拉选择

10. 清空商品未售卡密 ​

接口地址： /merchantapi/goods/good/emptiedCards

请求参数：

参数名类型必填说明
idint是商品 ID

响应示例：

json
{
  "code": 1,
  "msg": "清空商品未售卡密成功"
}

说明： 将未售出的卡密放入回收站，后台会异步更新商品库存

11. 获取代理等级列表 ​

接口地址： /merchantapi/goods/good/getAgentLevels

请求参数： 无

响应示例：

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

说明： 用于商品编辑页设置代理价格

12. 获取商品的代理等级价格 ​

接口地址： /merchantapi/goods/good/getGoodsAgentPrices

请求参数：

参数名类型必填说明
goods_idint是商品 ID

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "agent_level_id": 1,
      "agent_price": "92.00",
      "status": 1,
      "level_name": "金牌代理"
    },
    {
      "agent_level_id": 2,
      "agent_price": "93.00",
      "status": 1,
      "level_name": "银牌代理"
    }
  ]
}

说明： 用于编辑商品时回显代理价格

13. 业务规则 ​

13.1 价格规则 ​

  • 商品售价必须大于成本价
  • 批发价格不能低于成本价
  • 代理价格不能低于成本价（代理商品）
  • 货源大厅价格不能低于成本价

2. 代理商品规则 ​

  • 开启代理销售时，可以设置货源大厅价格和代理等级价格
  • 关闭代理销售时，会下架所有下级代理商品
  • 修改货源大厅价格时，会同时下架所有从货源大厅对接的代理商品
  • 代理商品上架时需检查上级商品链路和上级商户信誉分

3. 库存规则 ​

  • 库存数量由卡密表统计得出
  • 清空卡密会将未售卡密放入回收站
  • 库存预警可设置站内信或邮件通知

4. 赠送规则 ​

  • 活动赠送：购买指定数量赠送指定数量
  • 附加赠送：购买本商品赠送其他商品
  • 附加赠送不能赠送本身商品（避免与活动赠送冲突）

5. 敏感词检测 ​

  • 商品名称、商品说明、使用说明都会进行敏感词检测

注意事项 ​

  • 添加/编辑商品前会检测店铺状态和风控状态
  • 商品价格受系统配置的最低价和最高价限制
  • 代理商品不能添加库存，只能由源头商户添加
  • 删除商品为软删除，可以从回收站恢复
  • 商品上架时会进行多项检查，确保商品可正常销售