7. 粉丝端 API 7.17 我的偶像福利列表【基础探测通过，待数据联调】

Table of Contents

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

GET /tieup/api/v1/me/benefit-artists/{artist_id}/benefits

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

路径参数：

参数 类型 必填 说明
artist_id integer 是 艺人 ID

查询参数：

参数 类型 必填 说明
scope string 否 all=全部，redeemable=可兑换，redeemed=已兑换；默认 all
page integer 否 页码，默认 1
page_size integer 否 每页数量，默认 20

响应字段：

字段 类型 说明
artist.artist_id integer 艺人 ID
artist.artist_name string 艺人名称
artist.artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
summary.total_count integer 该偶像当前上架福利数量
summary.redeemable_count integer 当前粉丝可兑换福利数量
summary.redeemed_count integer 当前粉丝已兑换福利数量
summary.items array 福利摘要列表
items array 当前页福利列表
items[].id integer 福利 ID，与 benefit_id 相同
items[].benefit_id integer 福利 ID
items[].artist_id integer 艺人 ID
items[].artist_user_id integer 艺人绑定的 APP 用户 ID
items[].artist_name string 艺人名称
items[].artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
items[].benefit_type integer 福利类型：1=实物，2=虚拟
items[].need_shipping_address integer 是否需要收货地址：1=需要，2=不需要
items[].need_email integer 是否需要邮箱：1=需要，2=不需要
items[].title string 福利名称
items[].content string 福利说明，即福利内容
items[].cover_url string/null 福利封面 URL
items[].condition_type string 条件类型
items[].condition_value integer 条件目标值
items[].condition_text string 条件展示文案
items[].stock integer 福利库存，0 表示不限库存
items[].redeemed_count integer 福利累计已兑换数量
items[].per_user_limit integer 每位粉丝可兑换次数限制
items[].required_candy_amount string 历史兼容糖果条件字段，固定两位小数字符串
items[].sort integer 排序值
items[].status integer 福利状态：1=上架，2=下架；本接口只返回上架福利
items[].progress object 当前粉丝对该福利的进度信息
items[].progress.condition_type string 进度条件类型
items[].progress.current_value integer 当前粉丝累计进度值
items[].progress.target_value integer 达标目标值
items[].progress.percent integer 进度百分比，最大 100
items[].progress.remaining_value integer 距离达标还差的数值
items[].progress.remaining_text string/null 未达标提示文案，如 还差1个月即可兑换；已达标或可兑换时为空
items[].progress.is_redeemable integer 是否可兑换：1=是，2=否
items[].progress.is_redeemed integer 是否已兑换：1=是，2=否
items[].progress.redemption_id integer/null 已兑换记录 ID，未兑换为空
items[].progress.redemption_status integer/null 已兑换状态，未兑换为空
items[].redemption object/null 当前有效兑换记录；未兑换为 null，取消或退款记录不作为当前兑换记录
items[].redemption.id integer 兑换记录 ID，与 redemption_id 相同
items[].redemption.redemption_id integer 兑换记录 ID
items[].redemption.redemption_no string 福利兑换编号
items[].redemption.benefit_id integer 福利 ID
items[].redemption.benefit_title string 福利标题
items[].redemption.benefit_type integer/null 福利类型：1=实物，2=虚拟
items[].redemption.fan_user_id integer 粉丝 APP 用户 ID
items[].redemption.fan_nickname string 粉丝昵称
items[].redemption.fan_avatar string 粉丝头像 URL
items[].redemption.artist_id integer 艺人 ID
items[].redemption.artist_user_id integer 艺人绑定的 APP 用户 ID
items[].redemption.artist_nickname string 艺人昵称
items[].redemption.artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
items[].redemption.candy_amount_snapshot string 兑换时糖果数量快照，固定两位小数字符串
items[].redemption.benefit_snapshot object 兑换时福利信息快照
items[].redemption.address_snapshot object/null 兑换时收货地址快照；虚拟福利或不需要地址时为 null
items[].redemption.address_snapshot.receiver_name string 收货人姓名
items[].redemption.address_snapshot.receiver_phone string 联系电话
items[].redemption.address_snapshot.detail_address string 详细收货地址；通过地址簿兑换时还可能包含省、市、区等扩展字段
items[].redemption.email_snapshot string 兑换时邮箱快照，未填写时为空字符串
items[].redemption.fulfillment_remark string/null 发放备注；待发放时为空
items[].redemption.condition_type_snapshot string/null 兑换时条件类型快照
items[].redemption.condition_value_snapshot integer/null 兑换时条件目标值快照
items[].redemption.progress_value_snapshot integer/null 兑换时粉丝实际进度值快照
items[].redemption.progress_snapshot object/null 兑换时完整进度快照
items[].redemption.status integer 兑换状态，与 redemption_status 相同
items[].redemption.redemption_status integer 兑换状态：1=待发放，2=已发放
items[].redemption.redeemed_at string/null 兑换时间，格式 Y-m-d H:i:s
items[].redemption.fulfilled_at string/null 发放时间；待发放时为空
items[].redemption.cancelled_at string/null 取消时间；当前有效兑换记录通常为空
items[].redemption.refunded_at string/null 退款时间；当前有效兑换记录通常为空
items[].redemption.refund_no string/null 退款编号；当前有效兑换记录通常为空
items[].redemption.created_at string/null 兑换记录创建时间
items[].published_at string/null 福利上架时间
items[].unpublished_at string/null 福利下架时间
items[].created_at string/null 福利创建时间
pagination.page integer 当前页码
pagination.page_size integer 每页数量
pagination.total integer 总数量
pagination.next_cursor string/null 游标分页预留字段，当前为空

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "artist": {
      "artist_id": 20001,
      "artist_name": "王心凌",
      "artist_avatar": "https://cdn.example.com/artist/avatar.png"
    },
    "summary": {
      "total_count": 3,
      "redeemable_count": 1,
      "redeemed_count": 2,
      "items": []
    },
    "items": [
      {
        "id": 30001,
        "benefit_id": 30001,
        "artist_id": 20001,
        "artist_user_id": 10002,
        "artist_name": "王心凌",
        "artist_avatar": "https://cdn.example.com/artist/avatar.png",
        "benefit_type": 1,
        "need_shipping_address": 1,
        "need_email": 1,
        "title": "亲笔签名照",
        "content": "亲笔签名照一张，由偶像自行寄出。",
        "cover_url": "https://cdn.example.com/benefits/sign-photo.png",
        "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": {
          "condition_type": "subscription_months",
          "current_value": 4,
          "target_value": 5,
          "percent": 80,
          "remaining_value": 1,
          "remaining_text": "还差1个月即可兑换",
          "is_redeemable": 2,
          "is_redeemed": 2,
          "redemption_id": null,
          "redemption_status": null
        },
        "published_at": "2026-06-20 09:00:00",
        "unpublished_at": null,
        "created_at": "2026-06-20 08:30:00",
        "redemption": null
      },
      {
        "id": 30002,
        "benefit_id": 30002,
        "artist_id": 20001,
        "artist_user_id": 10002,
        "artist_name": "王心凌",
        "artist_avatar": "https://cdn.example.com/artist/avatar.png",
        "benefit_type": 1,
        "need_shipping_address": 1,
        "need_email": 1,
        "title": "限定纪念礼盒",
        "content": "限定纪念礼盒一份，由偶像自行寄出。",
        "cover_url": "https://cdn.example.com/benefits/gift-box.png",
        "condition_type": "question_count",
        "condition_value": 20,
        "condition_text": "提问满20个",
        "stock": 50,
        "redeemed_count": 8,
        "per_user_limit": 1,
        "required_candy_amount": "0.00",
        "sort": 90,
        "status": 1,
        "progress": {
          "condition_type": "question_count",
          "current_value": 22,
          "target_value": 20,
          "percent": 100,
          "remaining_value": 0,
          "remaining_text": null,
          "is_redeemable": 2,
          "is_redeemed": 1,
          "redemption_id": 60001,
          "redemption_status": 1
        },
        "published_at": "2026-06-21 09:00:00",
        "unpublished_at": null,
        "created_at": "2026-06-21 08:30:00",
        "redemption": {
          "id": 60001,
          "redemption_id": 60001,
          "redemption_no": "BR202606230001",
          "benefit_id": 30002,
          "benefit_title": "限定纪念礼盒",
          "benefit_type": 1,
          "fan_user_id": 10001,
          "fan_nickname": "小甜心",
          "fan_avatar": "https://cdn.example.com/fan/avatar.png",
          "artist_id": 20001,
          "artist_user_id": 10002,
          "artist_nickname": "王心凌",
          "artist_avatar": "https://cdn.example.com/artist/avatar.png",
          "candy_amount_snapshot": "0.00",
          "benefit_snapshot": {
            "benefit_id": 30002,
            "benefit_type": 1,
            "need_shipping_address": 1,
            "need_email": 1,
            "title": "限定纪念礼盒",
            "content": "限定纪念礼盒一份，由偶像自行寄出。",
            "cover_url": "https://cdn.example.com/benefits/gift-box.png",
            "condition_type": "question_count",
            "condition_value": 20,
            "condition_text": "提问满20个"
          },
          "address_snapshot": {
            "receiver_name": "张三",
            "receiver_phone": "13800000000",
            "detail_address": "上海市黄浦区详细地址"
          },
          "email_snapshot": "fan@example.com",
          "fulfillment_remark": null,
          "condition_type_snapshot": "question_count",
          "condition_value_snapshot": 20,
          "progress_value_snapshot": 22,
          "progress_snapshot": {
            "condition_type": "question_count",
            "current_value": 22,
            "target_value": 20,
            "percent": 100,
            "remaining_value": 0,
            "remaining_text": null,
            "is_redeemable": 1,
            "is_redeemed": 2,
            "redemption_id": null,
            "redemption_status": null
          },
          "status": 1,
          "redemption_status": 1,
          "redeemed_at": "2026-06-23 14:30:00",
          "fulfilled_at": null,
          "cancelled_at": null,
          "refunded_at": null,
          "refund_no": null,
          "created_at": "2026-06-23 14:30:00"
        }
      },
      {
        "id": 30003,
        "benefit_id": 30003,
        "artist_id": 20001,
        "artist_user_id": 10002,
        "artist_name": "王心凌",
        "artist_avatar": "https://cdn.example.com/artist/avatar.png",
        "benefit_type": 2,
        "need_shipping_address": 2,
        "need_email": 1,
        "title": "生日会邀请函",
        "content": "生日会电子邀请函一份。",
        "cover_url": "https://cdn.example.com/benefits/invitation.png",
        "condition_type": "video_call_minutes",
        "condition_value": 30,
        "condition_text": "视频通话满30分钟",
        "stock": 0,
        "redeemed_count": 5,
        "per_user_limit": 1,
        "required_candy_amount": "0.00",
        "sort": 80,
        "status": 1,
        "progress": {
          "condition_type": "video_call_minutes",
          "current_value": 35,
          "target_value": 30,
          "percent": 100,
          "remaining_value": 0,
          "remaining_text": null,
          "is_redeemable": 2,
          "is_redeemed": 1,
          "redemption_id": 60002,
          "redemption_status": 2
        },
        "published_at": "2026-06-22 09:00:00",
        "unpublished_at": null,
        "created_at": "2026-06-22 08:30:00",
        "redemption": {
          "id": 60002,
          "redemption_id": 60002,
          "redemption_no": "BR202606230002",
          "benefit_id": 30003,
          "benefit_title": "生日会邀请函",
          "benefit_type": 2,
          "fan_user_id": 10001,
          "fan_nickname": "小甜心",
          "fan_avatar": "https://cdn.example.com/fan/avatar.png",
          "artist_id": 20001,
          "artist_user_id": 10002,
          "artist_nickname": "王心凌",
          "artist_avatar": "https://cdn.example.com/artist/avatar.png",
          "candy_amount_snapshot": "0.00",
          "benefit_snapshot": {
            "benefit_id": 30003,
            "benefit_type": 2,
            "need_shipping_address": 2,
            "need_email": 1,
            "title": "生日会邀请函",
            "content": "生日会电子邀请函一份。",
            "cover_url": "https://cdn.example.com/benefits/invitation.png",
            "condition_type": "video_call_minutes",
            "condition_value": 30,
            "condition_text": "视频通话满30分钟"
          },
          "address_snapshot": null,
          "email_snapshot": "fan@example.com",
          "fulfillment_remark": "邀请函已发送至兑换邮箱",
          "condition_type_snapshot": "video_call_minutes",
          "condition_value_snapshot": 30,
          "progress_value_snapshot": 35,
          "progress_snapshot": {
            "condition_type": "video_call_minutes",
            "current_value": 35,
            "target_value": 30,
            "percent": 100,
            "remaining_value": 0,
            "remaining_text": null,
            "is_redeemable": 1,
            "is_redeemed": 2,
            "redemption_id": null,
            "redemption_status": null
          },
          "status": 2,
          "redemption_status": 2,
          "redeemed_at": "2026-06-23 15:00:00",
          "fulfilled_at": "2026-06-24 10:00:00",
          "cancelled_at": null,
          "refunded_at": null,
          "refund_no": null,
          "created_at": "2026-06-23 15:00:00"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 3,
      "next_cursor": null
    }
  }
}

兑换信息说明：

  • redemption 与 /tieup/api/v1/me/benefit-redemptions 使用同一响应结构；未兑换福利固定返回 null。
  • address_snapshot 和 email_snapshot 是兑换时冻结的历史快照，用户后续修改或删除地址簿、修改个人邮箱，不会改变该兑换记录。
  • scope=redeemed 只返回当前状态为待发放或已发放的福利；已取消、已退款记录不计入当前已兑换列表。