hy/hyapp-server

Fork 0

zhx 772cb71a46 vip gif图，排行榜分区

2026-07-21 11:31:21 +08:00

5.2 KiB

Raw Blame History

Fami VIP 设置接口对接文档

1. 接口范围

本文档只描述 Fami VIP 设置相关接口、请求参数和返回字段。

2. 设置字段

VIP 等级	设置项	`benefit_code`	接口字段	无记录默认值
VIP6	隐藏个人数据	`hide_profile_data`	`hide_profile_data_enabled`	`false`
VIP6	榜单隐身	`leaderboard_invisible`	`leaderboard_invisible_enabled`	`false`
VIP7	匿名访问主页	`anonymous_profile_visit`	`anonymous_profile_visit_enabled`	`false`
VIP8	进房全服通知	`room_entry_notice`	`room_entry_notice_enabled`	`true`
VIP9	上线全服通知	`online_global_notice`	`online_global_notice_enabled`	`true`

updated_at_ms = 0 表示用户尚未修改，当前返回的是默认值。

3. 公共请求约定

3.1 请求头

Authorization: Bearer {access_token}
X-App-Code: fami
Content-Type: application/json

3.2 统一响应结构

{
  "code": "OK",
  "message": "OK",
  "data": {},
  "request_id": "req_xxx"
}

接口成功条件为 code == "OK"。

4. 查询当前用户设置

4.1 请求

GET /api/v1/vip/settings

请求体：无。

4.2 成功响应

{
  "code": "OK",
  "message": "OK",
  "data": {
    "settings": {
      "app_code": "fami",
      "user_id": 10001,
      "room_entry_notice_enabled": true,
      "online_global_notice_enabled": true,
      "hide_profile_data_enabled": false,
      "anonymous_profile_visit_enabled": false,
      "leaderboard_invisible_enabled": false,
      "updated_at_ms": 0
    },
    "evaluated_at_ms": 1784563200000
  },
  "request_id": "req_vip_settings_get"
}

5. 修改当前用户设置

5.1 请求

PATCH /api/v1/vip/settings

请求体支持以下可选字段：

{
  "room_entry_notice_enabled": true,
  "online_global_notice_enabled": true,
  "hide_profile_data_enabled": false,
  "anonymous_profile_visit_enabled": false,
  "leaderboard_invisible_enabled": false
}

PATCH 规则：

每次请求至少传一个设置字段。
未传字段保持原值。
显式传 false 表示关闭该设置。
不支持修改其他用户的设置。

单字段请求示例：

{
  "hide_profile_data_enabled": true
}

5.2 成功响应

修改成功后返回完整设置对象：

{
  "code": "OK",
  "message": "OK",
  "data": {
    "settings": {
      "app_code": "fami",
      "user_id": 10001,
      "room_entry_notice_enabled": true,
      "online_global_notice_enabled": true,
      "hide_profile_data_enabled": true,
      "anonymous_profile_visit_enabled": false,
      "leaderboard_invisible_enabled": false,
      "updated_at_ms": 1784563200123
    },
    "server_time_ms": 1784563200150
  },
  "request_id": "req_vip_settings_patch"
}

6. VIP 用户信息接口返回设置

6.1 请求

GET /api/v1/vip/me

设置字段路径：

data.state.user_settings

精简响应示例：

{
  "code": "OK",
  "data": {
    "state": {
      "effective_vip": {
        "level": 8,
        "name": "VIP8",
        "active": true
      },
      "effective_benefits": [
        {
          "benefit_code": "room_entry_notice",
          "status": "active"
        }
      ],
      "user_settings": {
        "app_code": "fami",
        "user_id": 10001,
        "room_entry_notice_enabled": true,
        "online_global_notice_enabled": true,
        "hide_profile_data_enabled": false,
        "anonymous_profile_visit_enabled": false,
        "leaderboard_invisible_enabled": false,
        "updated_at_ms": 0
      }
    }
  },
  "request_id": "req_vip_me"
}

真实响应还包含 paid_vip、equipped_trial_card、effective_source、evaluated_at_ms 和 program_config 等字段。

7. 当前用户聚合信息返回设置

7.1 请求

GET /api/v1/users/me/overview