8. 偶像端 API 8.27 福利兑换详情【基础探测通过，待数据联调】

Table of Contents

8.27 福利兑换详情【基础探测通过，待数据联调】

GET /tieup/api/v1/artist/benefit-redemptions/{redemption_id}

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

路径参数：

参数 类型 必填 说明
redemption_id integer 是 兑换记录 ID

响应字段：

字段 类型 说明
id integer 兑换记录主键 ID，与 redemption_id 一致
redemption_id integer 福利兑换记录 ID
redemption_no string 福利兑换编号
benefit_id integer 福利 ID
benefit_title string 福利标题
benefit_type integer/null 福利类型：1=实物，2=虚拟
fan_user_id integer 粉丝用户 ID
fan_nickname string 粉丝昵称
fan_avatar string 粉丝头像 URL
artist_id integer 艺人 ID
artist_user_id integer 艺人用户 ID
artist_nickname string 艺人昵称
artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
candy_amount_snapshot string 历史兼容字段，新福利兑换不额外扣糖果，通常为 0.00
benefit_snapshot object 兑换时福利快照
benefit_snapshot.benefit_id integer 兑换时福利 ID
benefit_snapshot.benefit_type integer 兑换时福利类型：1=实物，2=虚拟
benefit_snapshot.need_shipping_address integer 兑换时福利是否需要收货地址：1=需要，2=不需要
benefit_snapshot.need_email integer 兑换时福利是否需要邮箱：1=需要，2=不需要
benefit_snapshot.title string 兑换时福利名称
benefit_snapshot.content string 兑换时福利说明
benefit_snapshot.cover_url string/null 兑换时福利封面图
benefit_snapshot.condition_type string 兑换时福利条件类型
benefit_snapshot.condition_value integer 兑换时福利条件目标值
benefit_snapshot.condition_text string 兑换时福利条件文案
benefit_snapshot.address_id integer/null 兑换时使用的用户地址 ID；直接传三字段地址时为空
benefit_snapshot.address_hash string/null 兑换时地址快照哈希，用于幂等复用校验
benefit_snapshot.email_snapshot string 兑换时邮箱快照
address_snapshot object/null 兑换时地址快照对象，虚拟福利可为空；新直传地址场景包含三字段，使用 address_id 或历史数据时可能包含省市区等扩展字段
address_snapshot.receiver_name string 收货人姓名
address_snapshot.receiver_phone string 收货人手机号
address_snapshot.detail_address string 详细地址
email_snapshot string 兑换时邮箱快照，未填写时为空字符串
fulfillment_remark string/null 偶像发放备注
condition_type_snapshot string/null 兑换时条件类型快照
condition_value_snapshot integer/null 兑换时条件目标值快照
progress_value_snapshot integer/null 兑换时粉丝进度值快照
progress_snapshot object/null 兑换时完整进度快照
progress_snapshot.condition_type string 兑换时福利条件类型
progress_snapshot.current_value integer 兑换时粉丝历史累计进度值
progress_snapshot.target_value integer 兑换时福利条件目标值
progress_snapshot.percent integer 兑换时进度百分比，最大 100
progress_snapshot.remaining_value integer 兑换时距离达标还差的数值
progress_snapshot.remaining_text string/null 兑换时未达标提示文案；已达标时为空
progress_snapshot.is_redeemable integer 兑换时是否可兑换：1=是，2=否
progress_snapshot.is_redeemed integer 兑换时是否已兑换：1=是，2=否
status integer 兑换状态，与 redemption_status 一致
redemption_status integer 兑换状态：1=待发放，2=已发放，3=已取消，4=已退款
redeemed_at string/null 兑换时间
fulfilled_at string/null 发放时间
cancelled_at string/null 取消时间
refunded_at string/null 退款时间
refund_no string/null 关联退款单号
created_at string/null 创建时间

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 60001,
    "redemption_id": 60001,
    "redemption_no": "BR202606230001",
    "benefit_id": 30001,
    "benefit_title": "亲笔签名照",
    "benefit_type": 1,
    "fan_user_id": 10001,
    "fan_nickname": "Tieup用户",
    "fan_avatar": "https://cdn.example.com/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": 30001,
      "benefit_type": 1,
      "need_shipping_address": 1,
      "need_email": 1,
      "title": "亲笔签名照",
      "content": "亲笔签名照一张",
      "cover_url": "https://cdn.example.com/benefit/sign.png",
      "condition_type": "subscription_months",
      "condition_value": 5,
      "condition_text": "订阅满5个月",
      "address_id": null,
      "address_hash": "address_snapshot_sha256",
      "email_snapshot": "fan@example.com"
    },
    "address_snapshot": {
      "receiver_name": "张三",
      "receiver_phone": "13800138000",
      "detail_address": "上海市黄浦区详细地址"
    },
    "email_snapshot": "fan@example.com",
    "fulfillment_remark": null,
    "condition_type_snapshot": "subscription_months",
    "condition_value_snapshot": 5,
    "progress_value_snapshot": 5,
    "progress_snapshot": {
      "condition_type": "subscription_months",
      "current_value": 5,
      "target_value": 5,
      "percent": 100,
      "remaining_value": 0,
      "remaining_text": null,
      "is_redeemable": 1,
      "is_redeemed": 2
    },
    "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"
  }
}

说明：偶像只能查看自己的福利兑换记录。address_id 只用于兑换时读取用户地址，查询接口以 address_snapshot 为准；用户后续修改或删除地址簿不会影响历史兑换快照，程序也不会把快照反向恢复成用户地址簿记录。