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

Table of Contents

8.21 创建福利【未授权拦截通过，待登录态联调】

POST /tieup/api/v1/artist/benefits

鉴权：需要 Authorization: Bearer <access_token>，且当前账号已开通偶像端。

说明：偶像添加福利时不直接提交 benefit_type。服务端根据 need_shipping_address 派生福利类型：1 需要收货地址表示实物福利，2 不需要收货地址表示虚拟福利。need_email 独立控制兑换时是否需要粉丝填写邮箱，可与收货地址同时要求。福利达标后粉丝可任意时间兑换，兑换本身不扣糖果。同一偶像最多同时开启 4 个福利；创建福利默认上架，但当前已开启 4 个福利时，新福利自动保存为下架。

请求体：

{
  "title": "亲笔签名照",
  "content": "亲笔签名照一张",
  "cover_url": "https://cdn.example.com/benefit/sign.png",
  "condition_type": "subscription_months",
  "condition_value": 5,
  "need_shipping_address": 1,
  "need_email": 1,
  "stock": 100,
  "per_user_limit": 1,
  "sort": 100,
  "status": 1
}

请求参数：

参数 类型 必填 说明
title string 是 福利名称
content string 否 福利说明，即福利内容
cover_url string 否 福利封面图 URL
condition_type string 是 条件类型：subscription_months、question_count、video_call_minutes、candy_spent
condition_value integer 是 达标目标值，必须大于 0
need_shipping_address integer 是 1=需要粉丝提供收货地址，派生实物福利；2=不需要地址，派生虚拟福利
need_email integer 是 1=兑换时需要粉丝填写邮箱；2=不需要邮箱。该字段与 need_shipping_address 独立，可同时为 1
stock integer 否 库存，0 表示不限库存
per_user_limit integer 否 单用户兑换次数限制，当前固定为 1
sort integer 否 排序值，越大越靠前
status integer 否 福利状态：1=上架，2=下架

创建规则：

  • 未传 status 时默认按上架处理。
  • 若当前偶像已存在 4 个 status=1 且未删除福利，请求未传 status 或传 status=1 时，服务端不报错，但新福利自动保存为 status=2。
  • 若明确传 status=2，直接创建为下架。

响应字段：

字段 类型 说明
benefit_id integer 福利 ID
artist_id integer 艺人 ID
benefit_type integer 福利类型：1=实物，2=虚拟，由 need_shipping_address 派生
need_shipping_address integer 是否需要收货地址：1=需要，2=不需要
need_email integer 是否需要邮箱：1=需要，2=不需要
title string 福利名称
content string 福利说明
condition_type string 条件类型
condition_value integer 条件目标值
condition_text string 条件展示文案
stock integer 库存
redeemed_count integer 已兑换数量
per_user_limit integer 单用户兑换次数限制，当前固定为 1
sort integer 排序值
status integer 福利状态：1=上架，2=下架

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "benefit_id": 30001,
    "artist_id": 20001,
    "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个月",
    "stock": 100,
    "redeemed_count": 0,
    "per_user_limit": 1,
    "sort": 100,
    "status": 1
  }
}