流量 CDK 与推广分佣

把流量额度做成可转让的兑换码，以及推广佣金的产生、冻结与提现规则。

两个跟流量分发和收益相关的功能：CDK 用来把额度转给别人，推广体系用来从邀请里拿佣金。

流量 CDK

CDK 是一张可转让的流量券。生成时从你的流量池划走额度，别人兑换后额度进他的池子。

参数

单张 CDK 的流量面额。

超过有效期未兑换就失效。

兑换接口的频率上限。超了返回 429。

生成

POST/api/v1/proxy/traffic-cdks

shell

curl -X POST 'https://api.example.com/api/v1/proxy/traffic-cdks' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"trafficBytes": 10737418240, "validDays": 7}'

10737418240 是 10 GB。

查看明文

GET/api/v1/proxy/traffic-cdks/:id/secret

CDK 的明文值要单独取。列表接口不返回明文，避免在日志和缓存里泄露。

兑换

POST/api/v1/proxy/traffic-cdks/redeem

shell

curl -X POST 'https://api.example.com/api/v1/proxy/traffic-cdks/redeem' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"code":"CDK_CODE_HERE"}'

作废

POST/api/v1/proxy/traffic-cdks/:id/cancel

未被兑换的 CDK 可以作废，额度退回你的流量池。

列表与统计

GET/api/v1/proxy/traffic-cdks

GET/api/v1/proxy/traffic-cdks/metrics

什么时候用 CDK

适合

转售流量给下游客户
给团队成员发额度，不想开子账号
活动奖励、试用发放

不适合

自己内部分配额度 —— 用子账号的 trafficLimitBytes 更直接，还能看到分开的用量统计

推广分佣

怎么运作

拿到推广码

每个用户有唯一的推广码和对应的 /r/:code 链接。

GET/api/v1/affiliate

PUT/api/v1/affiliate/code

分享链接

点击按 UTC 自然日汇总统计。

被邀请用户完成购买

产生佣金。佣金率由平台设置决定。

佣金解冻

佣金先进 frozen 状态，冻结期后转为 available。默认冻结 7 天。

也存在 reversed 状态——被邀请用户退款时佣金会被冲回。

提现或转入钱包

两种去处，见下面。

佣金的去处

转入钱包（可以直接用来买流量）：

POST/api/v1/affiliate/convert

提现到 USDT：

POST/api/v1/affiliate/withdrawals

支持三条链：TRC20 / ERC20 / BEP20。

shell

curl -X POST 'https://api.example.com/api/v1/affiliate/withdrawals' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"amountMinor": 5000, "network": "TRC20", "address": "YOUR_USDT_ADDRESS"}'

提现状态流转：

text

pending → approved → paid
pending → rejected

GET/api/v1/affiliate/withdrawals

默认参数

项	默认值
最低提现金额	1000（货币最小单位）
佣金冻结期	7 天
功能开关	默认关闭
佣金率	默认 0

校验推广码

公开接口，注册页用来验证码是否有效：

GET/api/v1/affiliate/referrals/:code

点击计数（公开，不校验 Origin）：

POST/api/v1/affiliate/referrals/:code/visits

金额单位

钱包和佣金的金额都用货币最小单位表示，币种是 USD。也就是说 5000 表示 50.00 美元。

写代码时不要用浮点数处理金额，直接用整数分。

钱包

GET/api/v1/wallet

返回两组余额：

字段	说明
`availableMinor`	可用金额（最小单位）
`reservedMinor`	已冻结金额（下单中）
`trafficRemainBytes`	剩余流量字节
`trafficTotalBytes`	累计购买流量字节

金额账本记录每次变动后的可用和冻结值，方便对账。

这一类的其他文档