logan

Appearance

货源大厅 ​

1. 获取货源大厅列表 ​

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

请求方式： POST

权限要求： 会验证货源大厅访问权限及信誉分≥80

请求参数：

参数名类型必填说明
need_applyint否审核模式：0=自动通过，1=需审核
keywordstring否搜索关键词（搜索名片名称）新增于 2025-12-20
card_levelint否名片等级筛选：-1=全部，0-n=具体等级（默认-1）新增于 2025-12-20
hall_category_idint否大厅分类ID；仅当前商户已开通该分类时生效，不传或无权限时默认使用“我已开通分类”的第一个
pageint否页码
limitint否每页数量

特殊规则：

  • 进入货源大厅前会校验 hall_access=1 且信誉分≥80，并且至少开通一个启用中的大厅分类。
  • 列表只展示所选大厅分类下至少存在一件可代理上架商品，并且名片处于展示中、未被平台关闭的商户；不展示空店铺。
  • hall_category_id 不是任意筛选条件，只能在当前商户已开通分类中选择；传入未开通分类时不会报错，会自动回退到已开通分类中的第一个，并在响应 hall_category_id 返回实际生效值。
  • 列表及商户排名统一按 card_level DESC、COALESCE(refresh_time, create_time) DESC、id DESC 排序；刷新排名只会提升相同名片等级内的顺序。

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 3,
        "user_id": 1004,
        "name": "123", // 名片名称
        "remark": "456", // 名片简介
        "need_apply": 0, // 申请时需要审核代理关系：0 无需 1需要
        "create_time": "2025-11-23 22:55:26", // 创建时间
        "update_time": "2025-11-24 15:56:52", // 更新时间
        "refresh_time": 1763971012, // 刷新时间
        "username": "test1004", // 商户名
        "shop_name": "ovo小店", // 店铺名
        "credit_score": 96, // 信誉值
        "rating_score": 96, // 店铺评分（用于名片预览显示）~~新增于 2025-12-20~~
        "is_quality": 0, // 是否为优质商家 0否 1是
        "goods_count": 4, // 商品数量
        "card_level": 2, // 名片等级 ~~新增于 2025-12-20~~
        "card_style_info": { // 名片样式信息 ~~新增于 2025-12-20~~
          "title": "黄金",
          "level": 2,
          "card_style": "...",
          "text_style": "...",
          "title_style": "...",
          "level_style": "..."
        },
        "badge_info": { // 标签信息 ~~新增于 2025-12-20~~
          "key": "rating",
          "name": "综合评分",
          "icon": "..."
        }
      }
    ],
    "total": 2,
    "hall_category_id": 1 // 本次实际生效的大厅分类ID（2026-05-19新增）
  }
}

2. 获取商户商品列表 ​

更新于 2026-07-31：商品数据返回 good_icon，值对应商户端 src/styles/iconlogo 图标库的 font_class。

更新于 2026-08-01：响应新增 hall，返回当前被访问货源店铺的公开名片、公告、客服联系方式、主题和标签信息；店铺详情页不再复用“获取自己的名片设置”接口。

更新于 2026-08-02：货源店铺页面全部使用货源名片资料。hall.shop_notice 读取 user_hall.shop_notice，hall.shop_contact 和兼容字段 hall.contact 读取 user_hall.contact；不再复用普通店铺的公告、公告开关和客服字段。hall.shop_notice_show 根据货源名片公告是否为空生成。

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

请求方式： POST

权限要求： 会验证货源大厅访问权限及信誉分≥80

请求参数：

参数名类型必填说明
user_idint是商户ID
category_idint否商品分类ID(2025-12-15新增)， 不传或0表示全部
keywordstring否商品名称搜索关键词 新增于 2025-12-20
hall_category_idint否大厅分类ID；仅当前商户已开通该分类时生效，不传或无权限时默认使用“我已开通分类”的第一个
pageint否页码
limitint否每页数量

特殊规则：

  • 只返回所选大厅分类下的商品；商品必须满足 status=1、can_proxy=1、hall_price>0。
  • hall_category_id 会按当前商户已开通分类解析，未传或无权限时自动回退，并在响应中返回实际生效值。

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "cate_id": 1, // 商品分类ID
        "cate_name": "xxx", // 商品分类名称  2025-12-15新增
        "user_id": 1000,
        "sort": 0,
        "name": "1000的商品1",
        "good_icon": "openai",
        "hall_price": "18.00", // 货源大厅价格
        "content": "<p><span style=\"color: rgba(0, 0, 0, 0.9); background-color: rgb(255, 255, 255); font-size: 12px;\">商品描述q</span></p>", // 商品描述
        "status": 1, // 状态：0=下架，1=上架
        "create_at": "2025-11-19 00:50:55", // 创建时间
        "can_proxy": 1, // 是否可代理：0=不可，1=可以
        "stock_quantity": 480, // 库存数量（~~更新于 2025-12-20：改为真实库存~~）
        "shop_name": "1001小店", // 店铺名
        "is_docked": 0, // 是否已对接：0=未对接，1=已对接
        "agent_goods_id": 0, // 当前商户生成的代理商品ID；未对接时为0，用于编辑或取消对接
        "is_blacklist": 0 // 是否在黑名单：0=否，1=是。建议1时前端做成对接按钮为无权限
      }
    ],
    "total": 1,
    "hall_category_id": 1, // 本次实际生效的大厅分类ID（2026-05-19新增）
    "hall": {
      "id": 1,
      "user_id": 1000,
      "name": "1000的货源名片",
      "remark": "店铺简介",
      "shop_notice_show": 1,
      "shop_notice": "货源名片公告内容",
      "shop_contact": "@merchant_support",
      "contact": "@merchant_support",
      "shop_name": "1001小店",
      "rating_score": 96,
      "goods_count": 1,
      "card_level": 2,
      "selected_badge": "rating",
      "card_style_info": {},
      "badge_info": {}
    }
  }
}

2.1 获取上级存在货源大厅商品的分类 ​

  • 2025-12-15 新增

接口地址： /merchantapi/distribution/hall/getCategoryTree

请求方式： POST

请求参数：

参数名类型必填说明
user_idint是商户ID
hall_category_idint否大厅分类ID；仅当前商户已开通该分类时生效，不传或无权限时默认使用“我已开通分类”的第一个

响应示例：

json
{
    "code": 1,
    "msg": "获取成功",
    "data": {
        "hall_category_id": 1,
        "tree": [
            {
                "value": 4, // 栏目id
                "label": "11111111", // 栏目名
                "children": []
            },
            {
                "value": 5,
                "label": "测试",
                "children": []
            }
        ]
    }
}

说明：

  • 2026-06-29 修复：分类树后端筛选货源大厅商品时，使用商品关联表自身字段 hall_price、status、id 进行过滤，避免生成 Goods.hall_price 这类不存在的 SQL 表别名导致报错。
  • hall_category_id 只有在当前商户已开通该大厅分类时才会生效；未传或无权限时，后端默认使用“我已开通分类”的第一个，并在响应中返回实际生效值。

3. 获取代理状态 ​

接口地址： /merchantapi/distribution/hall/agentStatus

请求方式： POST

请求参数：

参数名类型必填说明
user_idint是商户ID
hall_category_idint否大厅分类ID；仅当前商户已开通该分类时生效，不传或无权限时默认使用“我已开通分类”的第一个

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "status": "none" // 代理状态：none=未申请，pending=待审核，approved=已通过，rejected=已拒绝
  }
}

4. 申请成为代理 ​

接口地址： /merchantapi/distribution/hall/becomeAgent

请求方式： POST

权限要求： 需要货源大厅访问权限

请求参数：

参数名类型必填说明
user_idint是商户ID

响应示例：

json
{
  "code": 1,
  "msg": "成为代理成功", 
  "data": {
    "status": 1, // 状态：0=失败，1=成功
    "result": "成为代理成功",
    "hall_category_id": 1 // 本次使用的大厅分类ID（2026-05-19新增）
  }
}

业务规则：

  • 不能对接自己
  • 名片必须存在且开启
  • 根据名片设置决定是否需要审核
  • 自动通过：status=1
  • 需要审核：status=0
  • 必须在当前生效大厅分类下存在该商户的可代理商品，否则返回“该商户在当前大厅分类下暂无可代理商品”
  • 成功响应中的 hall_category_id 为实际生效的大厅分类ID

5. 搜索商品 ​

更新于 2025-12-20：新增名片等级筛选、名片样式信息、标签信息、代理状态等返回字段

更新于 2026-07-31：返回商品图标字段 good_icon，值对应商户端 src/styles/iconlogo 图标库的 font_class。

接口地址： /merchantapi/distribution/hall/searchGoods

请求方式： POST

请求参数：

参数名类型必填说明
keywordstring是搜索关键词
card_levelint否名片等级筛选：-1=全部，0-n=具体等级（默认-1）新增于 2025-12-20
hall_category_idint否大厅分类ID；仅当前商户已开通该分类时生效，不传或无权限时默认使用“我已开通分类”的第一个
pageint否页码
limitint否每页数量

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 8,
        "cate_id": 3,
        "cate_name": "分类名称", // ~~新增于 2025-12-20~~
        "user_id": 1004,
        "sort": 0,
        "name": "商品名称",
        "good_icon": "openai",
        "hall_price": "8.00",
        "content": "商品描述...",
        "status": 1,
        "create_at": "2025-11-23 20:56:24",
        "is_freeze": 0,
        "can_proxy": 1,
        "stock_quantity": 0,
        "shop_name": "ovo小店",
        "username": "test1004",
        "card_level": 2, // 名片等级 ~~新增于 2025-12-20~~
        "hall_name": "名片名称", // ~~新增于 2025-12-20~~
        "need_apply": 0, // 是否需要审核 ~~新增于 2025-12-20~~
        "rating_score": 96, // 店铺评分 ~~新增于 2025-12-20~~
        "is_docked": 0, // 是否已对接 ~~新增于 2025-12-20~~
        "agent_goods_id": 0, // 当前商户生成的代理商品ID；未对接时为0，用于编辑或取消对接（2026-08-01新增）
        "is_blacklist": 0, // 是否在黑名单 ~~新增于 2025-12-20~~
        "agent_status": "none", // 代理申请状态：none=未申请, pending=申请中, approved=已通过, rejected=已拒绝 ~~新增于 2025-12-20~~
        "card_style_info": { // 名片样式信息 ~~新增于 2025-12-20~~
          "title": "黄金",
          "level": 2,
          "card_style": "...",
          "text_style": "...",
          "title_style": "...",
          "level_style": "..."
        },
        "badge_info": { // 标签信息 ~~新增于 2025-12-20~~
          "key": "rating",
          "name": "综合评分",
          "icon": "..."
        }
      }
    ],
    "total": 2,
    "hall_category_id": 1
  }
}

说明： 搜索商品名称和商品说明，更新于 2025-12-20：按名片等级降序排列。is_docked=1 时前端可使用 agent_goods_id 调用代理商品详情、编辑或取消对接接口。

响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 8,
        "cate_id": 3,
        "user_id": 1004,
        "sort": 0,
        "name": "谁的青春不励志，得言精心整理，100句人生励志语录1、你只管努力，剩下的交给时间。 谁的青春不励志，得言精心整理，100句人生励志语录1、你只管努力，剩下的交给时间。",
        "hall_price": "8.00",
        "content": "<ul><li style=\"text-align: start;\">“成功不是终点，而失败并不致命：有勇气继续下去才是最重要的。”—— ...</li><li style=\"text-align: start;\">“宁可在独创性上失败，也不要在模仿中成功。”—— ...</li><li style=\"text-align: start;\">“成功之路和失败之路几乎是相同的。”—— ...</li><li style=\"text-align: start;\">“成功通常属于那些忙于寻找成功的人。”—— ...</li><li style=\"text-align: start;\">“学会从失败中成功。 ...</li><li style=\"text-align: start;\">“这个世界上，坚持不懈是无可替代的。</li></ul>",
        "status": 1,
        "create_at": "2025-11-23 20:56:24",
        "is_freeze": 0,
        "can_proxy": 1,
        "stock_quantity": 0,
        "shop_name": "ovo小店",
        "username": "test1004"
      },
      {
        "id": 6,
        "cate_id": 7,
        "user_id": 1002,
        "sort": 0,
        "name": "谁的青春不励志，得言精心整理，100句人生励志语录1、你只管努力，剩下的交给时间。 谁的青春不励志，得言精心整理，100句人生励志语录1、你只管努力，剩下的交给时间。",
        "hall_price": "20.00",
        "content": "<ul><li style=\"text-align: start;\">“成功不是终点，而失败并不致命：有勇气继续下去才是最重要的。”—— ...</li><li style=\"text-align: start;\">“宁可在独创性上失败，也不要在模仿中成功。”—— ...</li><li style=\"text-align: start;\">“成功之路和失败之路几乎是相同的。”—— ...</li><li style=\"text-align: start;\">“成功通常属于那些忙于寻找成功的人。”—— ...</li><li style=\"text-align: start;\">“学会从失败中成功。 ...</li><li style=\"text-align: start;\">“这个世界上，坚持不懈是无可替代的。</li></ul>",
        "status": 1,
        "create_at": "2025-11-23 18:09:03",
        "is_freeze": 0,
        "can_proxy": 1,
        "stock_quantity": 957,
        "shop_name": "九头蛇",
        "username": "test1002"
      }
    ],
    "total": 2
  }
}

说明： 搜索商品名称和商品说明

5.1 取消单个商品对接 ​

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

请求方式： POST

请求参数：

参数名类型必填说明
idint是搜索或店铺商品列表返回的 agent_goods_id

业务规则：

  • 仅允许取消当前登录商户自己的代理商品。
  • 成功后代理商品软删除进入回收站，同时删除商品对接关系。
  • 对接关系删除后，货源大厅列表会恢复“申请对接/对接”状态，允许后续重新对接。

响应示例：

json
{
  "code": 1,
  "msg": "已取消对接",
  "data": null
}

6. 货源大厅分类 ​

接口地址： /merchantapi/distribution/hall/categoryList

请求方式： POST

响应示例：

示例

json
{
    "code": 1,
    "msg": "获取成功",
    "data": [
        {
            "id": 1,
            "name": "默认分类1",
            "sort": 999,
            "status": 1,
            "remark": "",
            "create_time": "2026-05-19 17:04:35",
            "update_time": "2026-05-19 20:44:25"
        },
        {
            "id": 2,
            "name": "默认分类2",
            "sort": 0,
            "status": 1,
            "remark": "",
            "create_time": "2026-05-19 20:44:34",
            "update_time": "2026-05-19 20:44:34"
        }
    ]
}