logan

1. 获取名片设置

接口地址： /merchantapi/distribution/userhall/getSetting

请求方式： POST

权限要求： 信誉分≥70

请求参数：

参数名	类型	必填	说明
hall_category_id	int	否	查询当前商户在指定大厅分类中的排名；只能使用已开通且启用的分类，不传或无权限时回退到已开通分类中的第一个

响应示例：

json

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "id": 1,
    "user_id": 1000,
    "uid": 1000, // 用户ID ~~新增于 2025-12-20~~
    "name": "大厅1000商家", // 名片名称
    "remark": "名片备注名片备注大厅1000商家", // 名片备注
    "shop_notice": "店铺公告内容", // 店铺公告 ~~新增于 2025-12-20~~
    "contact": "联系方式", // 联系方式 ~~新增于 2025-12-20~~
    "refrash_count": 0, // 刷新点数量
    "card_level": 2, // 名片等级 名片页面用于查找购买过的等级
    "need_apply": 0, // 申请时需要审核代理关系：0 无需 1需要
    "status": 1, // 状态：0=下架，1=上架
    "create_time": "2025-11-19 00:54:38",
    "update_time": "2025-11-19 15:56:55",
    "refresh_time": null, // 最后刷新时间
    "close_status": 0, // 平台对此商户的开启状态；信誉分低于80时 关闭：1关闭，默认0开启，级别高于status
    "username": "test1000", // 商户名
    "shop_name": "1001小店", // 店铺名
    "is_checked_in": 0, // 今日是否已签到
    "refresh_point_price": 0.2, // 刷新点单价
    "rating_score": 96, // 店铺评分 ~~新增于 2025-12-20~~
    "goods_count": 10, // 商品数量 ~~新增于 2025-12-20~~
    "selected_badge": "rating", // 当前选中的标签key ~~新增于 2025-12-20~~
    "hall_rank": 6, // 当前商户在实际生效大厅分类中的排名；0表示未上榜
    "rank_total": 24, // 当前大厅分类内参与排名的商户总数
    "hall_category_id": 1 // 本次排名实际生效的大厅分类ID；0表示暂无可用分类
  }
}

说明：

若商户没有货源名片记录，获取名片设置时会自动创建默认名片；若历史名片名称为空，会自动补齐默认名称。
默认名片名称规则：优先使用“店铺名+货源”，没有店铺名时依次使用“商户用户名+货源”、“商户ID+货源”兜底。
排名只统计当前大厅分类下至少有一件可代理上架商品，并且名片处于展示中、未被平台关闭的商户；空店铺不参与排名。
排名顺序与货源大厅列表一致：先按名片等级倒序，再按刷新时间倒序（未刷新时使用创建时间），最后按名片ID倒序。

2. 设置名片信息

~~更新于 2025-12-20：新增店铺公告、联系方式、标签选择参数~~

接口地址： /merchantapi/distribution/userhall/setSetting

请求方式： POST

请求参数：

参数名	类型	必填	说明
name	string	是	名片名称
remark	string	是	名片备注
shop_notice	string	否	店铺公告 ~~新增于 2025-12-20~~
contact	string	否	联系方式 ~~新增于 2025-12-20~~
need_apply	int	是	审核模式：0=自动通过，1=需审核
status	int	是	状态：0=关闭，1=开启
selected_badge	string	否	选择的标签key（默认rating）~~新增于 2025-12-20~~

响应示例：

json

{
  "code": 1,
  "msg": "设置成功"
}

错误示例：

json

{
  "code": 0,
  "msg": "请填写名片名称"
}

json

{
  "code": 0,
  "msg": "请填写名片备注"
}

json

{
  "code": 0,
  "msg": "选择的标签不存在或已禁用" // ~~新增于 2025-12-20~~
}

json

{
  "code": 0,
  "msg": "您的名片等级不足，无法使用该标签" // ~~新增于 2025-12-20~~
}

json

{
  "code": 0,
  "msg": "您的评分不足XX分，无法使用该标签" // ~~新增于 2025-12-20~~
}

3. 签到获取刷新点

接口地址： /merchantapi/distribution/userhall/checkIn

响应示例：

json

{
  "code": 1,
  "msg": "签到成功"
}

错误示例：

json

{
  "code": 0,
  "msg": "今天已经签到过了"
}

业务规则：

每天只能签到一次
签到成功获得1个刷新点
记录签到日志

4. 签到记录

接口地址： /merchantapi/distribution/userhall/signLog

请求方式： POST

请求参数：

参数名	类型	必填	说明
month	string	否	月份（格式：Y-m，默认当月）

响应示例：

json

{
  "code": 1,
  "msg": "获取成功",
  "data": ["2023-12-01", "2023-12-02", "2023-12-05"] // 无记录时 data项不存在
}

5. 刷新排名

接口地址： /merchantapi/distribution/userhall/refreshRank

请求方式： POST

请求参数：

参数名	类型	必填	说明
hall_category_id	int	否	需要返回刷新后排名的大厅分类ID；只能使用已开通且启用的分类，不传或无权限时回退到已开通分类中的第一个

响应示例：

json

{
  "code": 1,
  "msg": "刷新成功",
  "data": {
    "refresh_point": 9, // 剩余刷新点数量
    "hall_rank": 1, // 刷新后当前大厅分类排名；0表示未上榜
    "rank_total": 24, // 当前大厅分类内参与排名的商户总数
    "hall_category_id": 1 // 本次排名实际生效的大厅分类ID
  }
}

错误示例：

json

{
  "code": 0,
  "msg": "名片不存在" // 其他 刷新点不足
}

业务规则：

需要消耗1个刷新点
刷新会更新名片的 refresh_time；相同名片等级内，刷新时间越新排名越靠前
不会越过更高名片等级的商户；完整顺序为 card_level DESC、COALESCE(refresh_time, create_time) DESC、id DESC
只统计当前大厅分类下至少存在一件可代理上架商品，且名片正常展示、未被平台关闭的商户
返回剩余刷新点、刷新后的当前排名、参与排名的商户总数和实际生效的大厅分类ID

6. 购买刷新点

接口地址： /merchantapi/distribution/userhall/buyRefreshPoint

请求方式： POST

请求参数：

参数名	类型	必填	说明
count	int	是	购买数量

响应示例：

json

{
  "code": 1,
  "msg": "购买成功"
}

错误示例：

json

{
  "code": 0,
  "msg": "购买数量不能小于等于0" // 其他：运营钱包余额不足，请先充值
}

业务规则：

需要有足够的运营资金
价格根据系统配置计算
扣除运营资金并记录日志

6.1 刷新点变动记录

~~新增于 2026-01-01~~

接口地址： /merchantapi/distribution/userhall/refreshPointLog

请求方式： POST

请求参数：

参数名	类型	必填	说明
type	int	否	类型：1=签到 2=购买 3=刷新消耗（不传查全部）
date_range	array	否	日期范围，如 ["2026-01-01", "2026-01-31"]

响应示例：

json

{
  "code": 1,
  "msg": "获取成功",
  "data": {
    "list": [
      {
        "id": 3,
        "user_id": 1000,
        "type": 2,
        "amount": 5,
        "balance": 10,
        "remark": "购买",
        "create_at": "2026-01-01 13:23:00",
        "type_text": "购买",
        "amount_text": "+5",
        "create_time": "2026-01-01 13:23" // 2026-1-6移除，当前接口以 create_at 为准
      },
      {
        "id": 2,
        "user_id": 1000,
        "type": 3,
        "amount": -1,
        "balance": 5,
        "remark": "刷新",
        "create_at": "2026-01-01 13:22:00",
        "type_text": "刷新",
        "amount_text": "-1"
      },
      {
        "id": 1,
        "user_id": 1000,
        "type": 1,
        "amount": 1,
        "balance": 6,
        "remark": "签到",
        "create_at": "2026-01-01 13:21:00",
        "type_text": "签到",
        "amount_text": "+1"
      }
    ],
    "total": 3
  }
}

字段说明：

type: 类型（1=签到 2=购买 3=刷新消耗）
type_text: 类型文本
amount: 变动数量（正数增加，负数减少）
amount_text: 格式化的变动数量（带正负号）
balance: 变动后余额
create_at: 创建时间

7. 获取系统名片排名卡片列表

~~更新于 2025-12-20：返回数据新增普通等级和标签列表~~
更新于 2026-07-31：名片主题改为独立购买权益，新增当前启用状态、有效期、剩余天数、续费周期和自动续费状态。

接口地址： /merchantapi/distribution/userhall/getSystemCardStyle

响应示例：

json

{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "id": 0,
      "title": "普通", // ~~新增于 2025-12-20：普通等级~~
      "desc": "默认等级，免费使用",
      "level": 0,
      "price": 0,
      "discount": 0,
      "status": 1,
      "config": "rating,cert",
      "is_owned": 1, // 是否可直接使用，免费主题固定为1
      "is_active": 1, // 是否为当前正在展示的主题
      "badges": [ // 该等级可用的标签列表 ~~新增于 2025-12-20~~
        {
          "key": "rating",
          "name": "综合评分",
          "icon": "...",
          "is_locked": false,
          "lock_reason": ""
        }
      ]
    },
    {
      "id": 3,
      "title": "黄金", // 标题
      "desc": "黄金等级描述", // 描述
      "price": "30.00", // 价格
      "status": 1,
      "level": 2, // 等级
      "is_owned": 1, // 当前有效期内是否已购买
      "is_active": 0, // 是否为当前正在展示的主题
      "expire_time": 1788192000,
      "expire_time_text": "2026-09-01 00:00",
      "remaining_days": 32,
      "auto_renew": 1,
      "buy_time_type": "month",
      "create_time": "2025-11-25 01:15:42",
      "update_time": "2025-11-25 01:17:37",
      "badges": [ // 该等级可用的标签列表 ~~新增于 2025-12-20~~
        {
          "key": "rating",
          "name": "综合评分",
          "icon": "...",
          "is_locked": false,
          "lock_reason": ""
        },
        {
          "key": "quality",
          "name": "优质商家",
          "icon": "...",
          "is_locked": true,
          "lock_reason": "需评分≥90"
        }
      ]
    }
  ]
}

7.1 获取可用的名片标签列表

~~新增于 2025-12-20~~

接口地址： /merchantapi/distribution/userhall/getBadgeList

请求方式： POST

请求参数： 无

响应示例：

json

{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "id": 1,
      "key": "rating",
      "name": "综合评分",
      "icon": "...",
      "unlock_score": 0,
      "allowed_levels": [],
      "is_locked": false,
      "lock_reason": ""
    },
    {
      "id": 2,
      "key": "quality",
      "name": "优质商家",
      "icon": "...",
      "unlock_score": 90,
      "allowed_levels": [2, 3],
      "is_locked": true,
      "lock_reason": "需评分≥90"
    }
  ]
}

字段说明：

is_locked: 当前用户是否可使用该标签
lock_reason: 锁定原因（评分不足等）


---

## 8. 购买系统名片排名卡片

> ~~更新于 2025-12-20：新增标签选择参数~~
>
> 更新于 2026-07-31：支持同时持有多个付费主题；购买新主题不会覆盖其他主题权益，已购主题可单独切换和设置自动续费。

**接口地址：** `/merchantapi/distribution/userhall/buyCardStyle`

**请求方式：** POST

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| system_card_id | int | 是 | 名片排名卡片ID |
| buy_time_type | string | 否 | 购买时长：month=1个月，year=1年（默认month） |
| selected_badge | string | 否 | 选择的标签key ~~新增于 2025-12-20~~ |

**响应示例：**

```json
{
  "code": 1,
  "msg": "购买成功"
}

业务规则：

需要有足够的运营资金
购买后自动应用样式
buy_time_type=year 时按 price * (1 - discount / 100) * 12 计算价格；month 时按月价格计算
buy_time_type 只能传 month 或 year
扣除运营资金并记录日志
同一个主题重复购买时从原到期时间继续顺延；购买其他主题不会覆盖已有主题权益
购买后使用基础标签 rating，再单独选择当前主题允许的标签

8.1 切换当前使用的名片主题

接口地址： /merchantapi/distribution/userhall/useCardStyle

请求方式： POST

请求参数：

参数名	类型	必填	说明
system_card_id	int	是	`0` 切换为免费普通主题；其他值只能使用当前有效期内已购买的主题ID

业务规则：

免费普通主题永久可用，切换免费主题不会清除当前付费主题的购买记录和到期时间。
当前有效期内已购买的付费主题可以从免费主题切换回来。
未购买或已过期的付费主题需要先调用 buyCardStyle 购买。
切换主题后使用基础标签 rating，再通过 setSetting 选择该等级允许展示的标签。

8.2 设置主题自动续费

接口地址： /merchantapi/distribution/userhall/setCardStyleAutoRenew

请求方式： POST

参数名	类型	必填	说明
system_card_id	int	是	已购买的系统主题ID
auto_renew	int	是	`1` 开启，`0` 关闭

业务规则：

每个已购主题独立设置自动续费，互不影响。
自动续费沿用该主题最近一次购买的月付或年付周期，并按续费时系统价格扣运营钱包。
运营钱包余额不足时不扣款，关闭该主题自动续费并发送站内消息。
未开启自动续费的主题从剩余 3 天开始，每天发送一次到期提醒。
当前启用主题到期且续费失败时，自动切换为免费普通主题。

业务规则总结

1. 访问权限

需要核销邀请码开通访问权限
信誉分必须≥80分
信誉分不足时无法访问货源大厅

2. 邀请码规则

购买邀请码需要运营资金
核销邀请码增加信誉分
邀请码只能使用一次

3. 名片设置

信誉分≥70才能设置名片
名片可以设置审核模式
名片可以开启/关闭

4. 刷新点规则

每日签到获得1个刷新点
刷新排名消耗1个刷新点
可以购买刷新点

5. 代理申请

不能对接自己
根据名片设置决定是否需要审核
申请成功后可以对接商品

注意事项

货源大厅功能需要信誉分≥80
设置名片需要信誉分≥70
邀请码购买和核销会影响信誉分
刷新排名需要消耗刷新点
系统名片需要购买才能使用
每日只能签到一次

1. 获取名片设置 ​

2. 设置名片信息 ​

3. 签到获取刷新点 ​

4. 签到记录 ​

5. 刷新排名 ​

6. 购买刷新点 ​

6.1 刷新点变动记录 ​

7. 获取系统名片排名卡片列表 ​

7.1 获取可用的名片标签列表 ​

8.1 切换当前使用的名片主题 ​

8.2 设置主题自动续费 ​

业务规则总结 ​

1. 访问权限 ​

2. 邀请码规则 ​

3. 名片设置 ​

4. 刷新点规则 ​

5. 代理申请 ​

注意事项 ​

1. 获取名片设置

2. 设置名片信息

3. 签到获取刷新点

4. 签到记录

5. 刷新排名

6. 购买刷新点

6.1 刷新点变动记录

7. 获取系统名片排名卡片列表

7.1 获取可用的名片标签列表

8.1 切换当前使用的名片主题

8.2 设置主题自动续费

业务规则总结

1. 访问权限

2. 邀请码规则

3. 名片设置

4. 刷新点规则

5. 代理申请

注意事项