8. 偶像端 API 8.22 偶像福利列表【基础探测通过，待数据联调】

Table of Contents

8.22 偶像福利列表【基础探测通过，待数据联调】

GET /tieup/api/v1/artist/benefits

鉴权：需要 Authorization: Bearer <access_token>。

查询参数：

参数 类型 必填 说明
page integer 否 页码，默认 1
page_size integer 否 每页数量，默认 20
status integer 否 福利状态筛选：1=上架，2=下架
benefit_type integer 否 福利类型：1=实物，2=虚拟
condition_type string 否 条件类型筛选

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "summary": {
      "active_count": 3,
      "redeemed_count": 12,
      "total_count": 5,
      "pending_count": 4,
      "fulfilled_count": 8
    },
    "items": [
      {
        "id": 30001,
        "benefit_id": 30001,
        "artist_id": 20001,
        "artist_user_id": 10001,
        "artist_name": "林雨薇",
        "artist_avatar": "https://cdn.example.com/avatar/artist.png",
        "title": "亲笔签名照",
        "content": "亲笔签名照一张，由偶像自行寄出。",
        "cover_url": "https://cdn.example.com/benefit/sign.png",
        "benefit_type": 1,
        "need_shipping_address": 1,
        "need_email": 1,
        "condition_type": "subscription_months",
        "condition_value": 5,
        "condition_text": "订阅满5个月",
        "stock": 100,
        "redeemed_count": 12,
        "per_user_limit": 1,
        "required_candy_amount": "0.00",
        "sort": 100,
        "status": 1,
        "progress": null,
        "published_at": "2026-06-23 10:00:00",
        "unpublished_at": null,
        "created_at": "2026-06-23 10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "next_cursor": null
    }
  }
}

响应字段：

字段 类型 说明
summary.active_count integer 当前开启的福利数量，统计 status=1 且未删除
summary.redeemed_count integer 当前偶像全部未删除福利累计已兑换数量
summary.total_count integer 当前偶像全部未删除福利总数量
summary.pending_count integer 当前偶像全部历史兑换记录中的待发放总数量，统计兑换状态 status=1，福利下架或删除后仍计入
summary.fulfilled_count integer 当前偶像全部历史兑换记录中的已发放总数量，统计兑换状态 status=2，福利下架或删除后仍计入
items array 当前页福利列表，受查询筛选影响
items[].id integer 福利主键 ID，与 benefit_id 一致
items[].benefit_id integer 福利 ID
items[].artist_id integer 艺人 ID
items[].artist_user_id integer 艺人用户 ID
items[].artist_name string 艺人名称
items[].artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
items[].title string 福利名称
items[].content string 福利说明，即福利内容
items[].cover_url string/null 福利封面图 URL
items[].benefit_type integer 福利类型：1=实物，2=虚拟，由 need_shipping_address 派生
items[].need_shipping_address integer 是否需要收货地址：1=需要，2=不需要
items[].need_email integer 是否需要邮箱：1=需要，2=不需要；与地址要求独立
items[].condition_type string 条件类型：subscription_months、question_count、video_call_minutes、candy_spent
items[].condition_value integer 条件目标值
items[].condition_text string 条件展示文案，不带额外前缀
items[].stock integer 库存，0 表示不限库存
items[].redeemed_count integer 已兑换数量
items[].per_user_limit integer 单用户兑换次数限制，当前固定为 1
items[].required_candy_amount string 历史兼容字段，新福利达标兑换不额外扣糖果，固定按 0 处理
items[].sort integer 排序值，越大越靠前
items[].status integer 福利状态：1=上架，2=下架
items[].progress object/null 当前粉丝进度；偶像端管理列表通常为空
items[].published_at string/null 上架时间
items[].unpublished_at string/null 下架时间
items[].created_at string/null 创建时间
pagination object 分页信息
pagination.page integer 当前页码
pagination.page_size integer 每页数量
pagination.total integer 命中筛选条件的总数量
pagination.next_cursor string/null 游标分页预留字段，当前为空

说明：summary 为偶像福利管理总览，不受本次列表 status、benefit_type、condition_type 筛选影响。pending_count、fulfilled_count 按当前偶像全部历史兑换记录统计，已取消和已退款记录不计入。