推广中心

推广数据查询、排行榜、渠道统计相关接口。通过 openApi.* 命名空间访问全站推广概览数据，通过 referral.* 命名空间管理自己的推广链接、查看个人推广统计和签到领奖。

概览数据（openApi）

以下端点通过 openApi 路由提供，需要 referral:read scope。

推广数据总览

获取全站推广活动的汇总数据，包含总链接数、总邀请人数、点击量、付款统计等。支持按日期范围和渠道筛选，不传参数则返回全量汇总。

示例 1 — 全量汇总：

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralOverview' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{}'

示例 2 — 指定日期范围 + 渠道：

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralOverview' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"from":"2026-03-01T00:00:00.000Z","to":"2026-03-31T23:59:59.999Z","channel":"twitter"}'

返回字段说明：

• period — 筛选的日期范围，未指定时为 null
• channel — 筛选的渠道，未指定时为 null
• links — 总链接数
• referrals — 总邀请记录数
• clicks / uniqueClicks — 总点击 / 去重点击
• payments.count / payments.amount — 付款笔数 / 金额
• pointsAwarded — 已发放推广积分
• activeReferrers — 活跃推广者数

推广趋势统计

按日聚合的全站推广数据时间序列，适用于趋势图表可视化。支持渠道筛选。

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralTrendStats' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"from":"2026-03-01T00:00:00.000Z","to":"2026-03-15T23:59:59.999Z"}'

返回字段说明：

• period.from / period.to — 查询的日期范围
• channel — 筛选的渠道，未指定时为 null
• trend[] — 每日数据数组，每项包含 date、clicks、uniqueClicks、registers、paymentCount、paymentAmount

推广排行榜

按不同指标查看推广用户排行榜。支持渠道筛选（points 指标除外）。

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralLeaderboard' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"metric":"referrals","limit":10,"channel":"bilibili"}'

返回字段说明：

• items[].userId — 用户 ID
• items[].name — 用户昵称
• items[].avatar — 头像 URL
• items[].value — 指标数值

推广渠道统计

按推广渠道（channel）聚合统计点击、注册、付款数据，包含转化率计算。支持日期范围筛选和自定义排序。

示例 — 查询本月各渠道表现：

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralChannelStats' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"from":"2026-03-01T00:00:00.000Z","to":"2026-03-31T23:59:59.999Z","sortBy":"registers","limit":10}'

返回字段说明：

• period — 筛选的日期范围，未指定时为 null
• items[].channel — 渠道名称
• items[].clicks / uniqueClicks — 点击 / 去重点击
• items[].registers — 注册数
• items[].payments / paymentAmount — 付款笔数 / 金额
• items[].conversionRate — 注册转化率（百分比）

推广链接排行

全站维度的推广链接表现排行，可按渠道筛选和自定义排序。

curl -X POST 'https://your-domain.com/api/trpc/openApi.referralLinkRanking' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"sortBy":"paymentCount","channel":"twitter","limit":5}'

返回字段说明：

• items[].id / code / label / channel — 链接基本信息
• items[].clicks / uniqueClicks / registers — 点击与注册数据
• items[].paymentCount / paymentAmount — 付款统计
• items[].conversionRate — 注册转化率（百分比）
• items[].createdAt — 创建时间
• items[].user — 链接所属用户（id、name、avatar）

用户推广管理（referral）

以下端点通过 referral 路由提供，操作当前登录用户自己的推广数据。查询类需要 referral:read scope，写入类需要 referral:write scope。

获取我的推广统计

查询当前用户的推广统计信息，包含指定日期、前一日、全量汇总和转化率。可选指定日期和链接 ID 筛选。

示例 — 查询指定日期的统计：

curl -X POST 'https://your-domain.com/api/trpc/referral.getMyStats' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"date":"2026-03-15"}'

返回字段说明：

• date — 查询的日期（YYYY-MM-DD）
• points — 当前积分余额
• referralCode — 个人推广码
• totalReferrals / totalLinks — 总邀请人数 / 总链接数
• todayClicks / todayUniqueClicks / todayRegisters / todayPaymentCount / todayPaymentAmount — 指定日期的数据
• yesterdayUniqueClicks / yesterdayRegisters / yesterdayPaymentCount — 指定日期前一天的数据
• totalClicks / totalUniqueClicks / totalRegisters / totalPaymentCount / totalPaymentAmount — 全量数据
• conversionRate — 注册转化率（百分比）
• paymentConversionRate — 付款转化率（百分比）
• earnedPoints — 推广获得的总积分

推广趋势数据

查询当前用户指定日期范围内按日聚合的推广数据趋势。

curl -X POST 'https://your-domain.com/api/trpc/referral.getMyTrendStats' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"from":"2026-03-01T00:00:00.000Z","to":"2026-03-15T23:59:59.999Z"}'

渠道统计

按渠道（channel）聚合当前用户的推广数据，包含转化率。

返回每个渠道： channel、clicks、uniqueClicks、registers、paymentCount、paymentAmount、paymentUsers、linkCount、conversionRate、paymentConversionRate

Top 链接

获取当前用户表现最好的推广链接。

推广链接列表

分页查询当前用户的推广链接，支持搜索、渠道筛选、状态筛选和排序。

curl -X POST 'https://your-domain.com/api/trpc/referral.getMyLinks' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"page":1,"limit":10,"channel":"twitter","sortBy":"registers","sortDir":"desc"}'

创建推广链接

创建新的推广链接，受站点推广开关和每用户链接上限约束。

curl -X POST 'https://your-domain.com/api/trpc/referral.createLink' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"label":"B 站简介区","channel":"bilibili","targetUrl":"https://example.com/promo"}'

更新推广链接

更新自己的推广链接属性。

删除推广链接

删除自己的推广链接及关联数据。

被推广用户列表

分页查询当前用户邀请的用户记录，支持搜索、按链接和渠道筛选。

curl -X POST 'https://your-domain.com/api/trpc/referral.getMyReferrals' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"page":1,"limit":10,"channel":"twitter"}'

积分流水

分页查询当前用户的积分变动记录，支持按类型和收支方向筛选。

curl -X POST 'https://your-domain.com/api/trpc/referral.getPointsHistory' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer sk-your-api-key' \
-d '{"page":1,"limit":20,"type":"REFERRAL_REWARD","amountDir":"income"}'

生成推广码

为当前用户生成个人推广码（若已有则直接返回）。

签到状态

获取签到系统的状态：是否启用、今日是否已签到、积分区间。

返回字段说明：

• enabled — 签到功能是否开启
• checkedInToday — 今日是否已签到
• todayPoints — 今日签到获得的积分（未签到为 0）
• pointsMin / pointsMax — 签到积分随机区间

每日签到

执行每日签到领取积分奖励。每日限一次。

返回字段说明：

• awarded — 是否成功领取
• points — 领取的积分数

每日登录奖励

领取每日登录奖励积分。每日限一次，与签到独立。

返回字段说明：

• awarded — 是否成功领取
• points — 领取的积分数