8. 偶像端 API 8.24 更新福利【未授权拦截通过，待登录态联调】

Table of Contents

8.24 更新福利【未授权拦截通过，待登录态联调】

PATCH /tieup/api/v1/artist/benefits/{benefit_id}

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

路径参数：

参数 类型 必填 说明
benefit_id integer 是 福利 ID

请求体示例：

{
  "title": "虚拟专属祝福",
  "content": "录制一段专属文字或语音祝福，由偶像自行发放",
  "condition_type": "candy_spent",
  "condition_value": 500,
  "need_shipping_address": 2,
  "need_email": 1,
  "stock": 0,
  "sort": 80,
  "status": 1
}

请求参数：

参数 类型 必填 说明
title string 否 福利名称
content string 否 福利说明，即福利内容
cover_url string 否 福利封面图 URL
condition_type string 否 条件类型
condition_value integer 否 条件目标值
need_shipping_address integer 否 是否需要地址：1=实物，2=虚拟；已有兑换记录后不建议允许修改
need_email integer 否 是否需要邮箱：1=需要，2=不需要；已有兑换记录后不建议允许修改
stock integer 否 库存，不能小于已兑换数量
per_user_limit integer 否 单用户兑换次数限制，当前固定为 1
sort integer 否 排序值
status integer 否 福利状态：1=上架，2=下架

更新规则：

  • 将下架福利更新为 status=1 时，如果当前偶像已开启 4 个福利，接口返回 422，提示 同时只能开启4个福利。
  • 更新已上架福利的其他字段并保持 status=1，不重复占用开启名额。
  • 将福利更新为 status=2 不受开启数量限制。

响应字段：

字段 类型 说明
id integer 福利主键 ID，与 benefit_id 一致
benefit_id integer 福利 ID
artist_id integer 艺人 ID
artist_user_id integer 艺人用户 ID
artist_name string 艺人名称
artist_avatar string 艺人头像，严格读取独立维护的 tieup_artist.avatar；未配置时返回空字符串，不回退绑定账号的用户头像
benefit_type integer 福利类型：1=实物，2=虚拟，由 need_shipping_address 派生
need_shipping_address integer 是否需要收货地址：1=需要，2=不需要
need_email integer 是否需要邮箱：1=需要，2=不需要；与地址要求独立
title string 福利名称
content string 福利说明，即福利内容
cover_url string/null 福利封面图 URL
condition_type string 条件类型：subscription_months、question_count、video_call_minutes、candy_spent
condition_value integer 条件目标值
condition_text string 条件展示文案，不带额外前缀
stock integer 库存，0 表示不限库存
redeemed_count integer 已兑换数量
per_user_limit integer 单用户兑换次数限制，当前固定为 1
required_candy_amount string 历史兼容字段，新福利达标兑换不额外扣糖果，固定按 0 处理
sort integer 排序值，越大越靠前
status integer 福利状态：1=上架，2=下架
progress object/null 当前粉丝进度；偶像端详情通常为空
published_at string/null 上架时间
unpublished_at string/null 下架时间
created_at string/null 创建时间

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": 30001,
    "benefit_id": 30001,
    "artist_id": 20001,
    "artist_user_id": 10001,
    "artist_name": "林雨薇",
    "artist_avatar": "https://cdn.example.com/avatar/artist.png",
    "benefit_type": 2,
    "need_shipping_address": 2,
    "need_email": 1,
    "title": "虚拟专属祝福",
    "content": "录制一段专属文字或语音祝福，由偶像自行发放",
    "cover_url": "https://cdn.example.com/benefit/blessing.png",
    "condition_type": "candy_spent",
    "condition_value": 500,
    "condition_text": "消耗糖果满500个",
    "stock": 0,
    "redeemed_count": 12,
    "per_user_limit": 1,
    "required_candy_amount": "0.00",
    "sort": 80,
    "status": 1,
    "progress": null,
    "published_at": "2026-06-23 10:00:00",
    "unpublished_at": null,
    "created_at": "2026-06-23 10:00:00"
  }
}