8. 偶像端 API 8.32 提现概览与税费预览【已开发，待云账户联调】

Table of Contents

8.32 提现概览与税费预览【已开发，待云账户联调】

GET /tieup/api/v1/artist/withdrawal-overview

用于 APP 初次进入提现页，返回余额、默认账户、提现窗口、基础提现状态和页面固定展示信息。 响应字段：

字段 类型 说明
artist_id integer 当前登录账号对应的艺人 ID
artist_type integer 艺人类型：1=个人艺人，2=经纪公司艺人
agency_company_id integer/null 绑定经纪公司 ID，个人艺人为 null
withdrawable_amount string 当前可提现金额，单位元，两位小数
available_amount string 兼容字段，等于 withdrawable_amount
frozen_amount string 资金状态为冻结中的提现金额汇总，包含明确下单失败但尚未退回的可重试记录
min_withdraw_amount string 最低提现金额，默认 "100.00"，读取后台基础配置
has_withdraw_account boolean 是否已有可用提现账户
default_account object/null 默认提现账户；无默认账户时取最新启用账户，无账户时为 null
default_account.account_no string 完整收款账号，供 APP 展示和编辑账户时回填
default_account.account_no_masked string 脱敏后的收款账号，兼容旧前端展示
window_start_day integer 每月提现窗口开始日，默认 1
window_end_day integer 每月提现窗口结束日，默认 5
is_window_open boolean 当前是否在提现窗口内
next_withdraw_at string/null 下次提现窗口开始时间，窗口开放时为 null
window object 提现窗口详情
can_apply boolean 是否满足个人艺人、窗口和最低金额等基础条件
can_withdraw boolean 兼容字段，等于 can_apply
unavailable_reason string/null 不可提现原因
expected_arrival_before_date string 预计到账截止日期，格式 YYYY-MM-DD
last_month_income object 上个自然月有效入账收入摘要

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "artist_id": 20001,
    "artist_type": 1,
    "agency_company_id": null,
    "withdrawable_amount": "1024.00",
    "available_amount": "1024.00",
    "frozen_amount": "100.00",
    "min_withdraw_amount": "100.00",
    "has_withdraw_account": true,
    "default_account": {
      "id": 1,
      "artist_id": 20001,
      "user_id": 20002,
      "account_type": 1,
      "account_type_label": "支付宝",
      "account_name": "李四",
      "account_no_masked": "al**************.com",
      "account_no": "alipay_account@example.com",
      "bank_name": null,
      "bank_branch": null,
      "is_default": 1,
      "status": 1,
      "created_at": "2026-07-03 10:00:00",
      "updated_at": "2026-07-03 10:00:00"
    },
    "window_start_day": 1,
    "window_end_day": 5,
    "is_window_open": true,
    "next_withdraw_at": null,
    "window": {
      "current_day": 3,
      "start_day": 1,
      "end_day": 5,
      "is_open": true,
      "next_open_at": null
    },
    "can_apply": true,
    "can_withdraw": true,
    "unavailable_reason": null,
    "expected_arrival_before_date": "2026-07-15",
    "last_month_income": {
      "period_start": "2026-06-01 00:00:00",
      "period_end": "2026-06-30 23:59:59",
      "income_amount": "61600.00"
    }
  }
}

说明：

  • 仅个人艺人可提现；经纪公司艺人继续走经纪公司结算链路。
  • 默认账户查询同时限定当前 artist_id、user_id、启用状态和未删除状态；default_account.account_no 不会返回其他用户的收款账号。
  • 提现窗口、最低提现金额、预计到账日和扣税开关读取后台基础配置，旧环境未配置时默认每月 1-5 日、最低 100 元、每月 15 日前到账、开启扣税试算。
  • frozen_amount 仅用于页面展示仍被提现单占用的金额，不参与余额二次扣减；明确下单失败但资金尚未退回时仍计入该字段，真正可提现余额以 withdrawable_amount 为准。
  • 旧接口 GET /tieup/api/v1/artist/withdrawal-status 暂时保留为兼容入口，返回结构同本接口；新接入请使用 withdrawal-overview。