流量主 API
流量主端接口前缀为 /api/publisher。除登录 / 注册 / 找回密码外，均需携带流量主 JWT：Authorization: Bearer <token>。
响应结构、分页与错误码约定见 概述与鉴权。
认证
登录
POST /api/publisher/auth/login
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
username | string | 是 | 用户名或注册邮箱 |
password | string | 是 | 登录密码 |
curl -X POST https://api.adbnk.co/api/publisher/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"pub_demo","password":"secret123"}'响应结构同广告主登录，返回 token / token_type / expires_in / user。
其他认证接口
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /auth/register | 注册 |
POST | /auth/forgot-password | 发送重置邮件，参数 email |
POST | /auth/reset-password | 参数 token、new_password、confirm_password |
POST | /auth/logout | 登出 |
GET | /auth/profile | 当前登录流量主信息 |
POST | /auth/password | 修改密码（old_password/new_password/confirm_password） |
站点（Site）
列表
GET /api/publisher/sites
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page / page_size | int | 否 | 分页 |
keyword | string | 否 | 名称/域名搜索 |
status | string | 否 | 状态 |
audit_status | string | 否 | 审核状态 |
start_date / end_date | date | 否 | 创建时间范围 |
创建站点
POST /api/publisher/sites
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 站点名称 |
media_type | string | 否 | 媒体类型：WEB（默认）/APP/TELEGRAM |
media_type_id | int | 否 | 媒体子类型，必须属于站点的 media_type，否则返回 400 error.site.media_type_id_invalid |
domain | string | 是* | WEB 和 TELEGRAM 必填，需为合法域名且未被占用；TELEGRAM 填小程序网址的域名 |
app_package | string | 是* | APP 必填，包名唯一 |
url | string | 否 | 站点 URL，未填时自动用 https://<domain>；TELEGRAM 请填小程序的 https 网址 |
tg_bot_username | string | 是* | 仅 TELEGRAM。bot 用户名：5–32 个字符，字母开头，其余为字母、数字或下划线，以 bot 结尾（不区分大小写）。开头带一个 @ 也可以，会被去掉 |
tg_app_short_name | string | 否 | 仅 TELEGRAM。小程序短名，3–30 个字母、数字或下划线 |
description | string | 否 | 站点描述 |
industry_id | int | 否 | 行业 ID |
icp | string | 否 | ICP 备案号 |
curl -X POST https://api.adbnk.co/api/publisher/sites \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"我的博客","media_type":"WEB","domain":"blog.example.com"}'新建站点默认 audit_status=PENDING，需审核通过后方可创建广告位。
Telegram 小程序站点
添加 Telegram 小程序时，传 media_type=TELEGRAM，并带上 domain、url、tg_bot_username，可选 tg_app_short_name。不要传 Bot ID，也不要传 bot token：平台会按用户名识别 bot。Telegram 相关字段建站后不能修改（PUT 时会被忽略），要换 bot 请新建站点。Telegram 站点一律人工审核。完整接入流程见 Telegram 小程序接入。
curl -X POST https://api.adbnk.co/api/publisher/sites \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name":"My Mini App","media_type":"TELEGRAM","domain":"app.example.com","url":"https://app.example.com/","tg_bot_username":"my_app_bot"}'Telegram 站点的响应（创建、列表、详情）多一个 tg 对象：
| 字段 | 类型 | 说明 |
|---|---|---|
bot_id | string | 平台识别到的 Bot ID，十进制字符串。请按字符串保存，它可能超出 JavaScript 的安全整数范围 |
bot_username | string | bot 用户名 |
app_short_name | string | null | 小程序短名 |
tme_url | string | https://t.me/<bot_username> |
steps | object | 验证状态：domain、bio、launch，取值为 verified 或 pending |
请确认 bot_id 和 bot_username 是你的 bot。
code | message_key | 含义 |
|---|---|---|
400 | error.site.tg_bot_username_invalid | bot 用户名格式不正确 |
400 | error.site.tg_short_name_invalid | 小程序短名格式不正确 |
400 | error.site.tg_bot_not_found | 找不到这个用户名对应的 bot |
400 | error.site.media_type_id_invalid | media_type_id 不属于站点的媒体类型（所有媒体类型都适用） |
429 | common.rate_limited | bot 识别请求过于频繁，请稍后重试 |
503 | error.site.tg_resolve_unavailable | bot 识别暂时不可用，请稍后重试 |
站点其他操作
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /sites/{id} | 详情 |
PUT | /sites/{id} | 更新。修改后的 media_type_id 必须属于站点的媒体类型（400 error.site.media_type_id_invalid） |
DELETE | /sites/{id} | 删除 |
POST | /sites/{id}/toggle | 启停 |
GET | /sites/{id}/stats | 站点统计 |
GET | /sites/{id}/verify-code | 获取验证代码。TELEGRAM 站点的响应还带 tg 对象：上表字段，加上 bio_code（填入 bot 简介的验证码）和 launch_links（需在 Telegram 里打开一次的链接） |
POST | /sites/{id}/verify | 验证站点，参数 method。TELEGRAM 站点见下文 |
Telegram 站点验证
Telegram 站点分三步验证：域名（方式与网站相同）、bot 简介、在 Telegram 里打开一次启动链接。每次调用 POST /sites/{id}/verify 都会重新检测所有尚未通过的步骤；已通过的步骤保持通过。
三步全部通过之前，接口返回 422，message_key 为 error.site.tg_verify_incomplete，各步骤状态在 data.steps 中：
{ "code": 422, "message_key": "error.site.tg_verify_incomplete",
"data": { "steps": { "domain": "verified", "bio": "not_found", "launch": "not_detected" } } }| 步骤 | 取值 |
|---|---|
domain | verified / pending（域名上还没检测到验证代码） |
bio | verified / not_found（bot 简介里没有验证码）/ retry（暂时无法检测，请几分钟后重试） |
launch | verified / not_detected（还没检测到带验证码的启动）/ retry（暂时无法检测，请重试） |
三步都通过后，接口返回成功，带 verified: true 和各步骤状态。对已经验证过的站点再次调用也会返回成功和 verified: true，但响应可能不包含 steps。这表示站点已验证、等待平台审核——审核完成前 audit_status 不变（新站点保持 PENDING）。验证本身永远不会让 Telegram 站点直接通过审核。
广告位（Zone）
列表
GET /api/publisher/zones
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
site_id | int | 否 | 按站点筛选 |
type | string | 否 | 广告类型筛选 |
status | string | 否 | 状态 |
audit_status | string | 否 | 审核状态 |
keyword | string | 否 | 名称搜索 |
创建广告位
POST /api/publisher/zones
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | string | 是 | 广告位名称 |
site_id | int | 是 | 所属站点，须属于当前流量主且已审核通过 |
zone_type_id | int | 是* | 广告位类型 ID（推荐），广告类型由它推导 |
ad_type / type | string | 是* | 广告类型，如 BANNER/NATIVE/VIDEO/POPUP/REWARDED 等；仅在不传 zone_type_id 时需要 |
size_id | int | 否 | 尺寸 ID |
width | int | 否 | 宽度，默认 300 |
height | int | 否 | 高度，默认 250 |
position | string | 否 | 位置，默认 CONTENT |
device | string | 否 | 设备，默认 ALL |
floor_ecpm | number | 否 | eCPM 底价（每千次展示的 $），默认 0 |
创建成功后系统自动生成唯一 zone_key（形如 zone_ab12cd34），用于广告请求。
广告位其他操作
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /zones/{id} | 详情 |
PUT | /zones/{id} | 更新（site_id 不可改） |
DELETE | /zones/{id} | 删除 |
POST | /zones/{id}/toggle | 启停 |
GET | /zones/{id}/code | 获取投放代码 |
GET | /zones/{id}/preview | 预览 |
POST | /zones/{id}/submit-audit | 提交审核 |
GET | /zones/{id}/stats | 广告位统计 |
Telegram 小程序广告位
TELEGRAM 站点下创建广告位须传 zone_type_id，只能使用以下类型：横幅、移动横幅、吸附横幅、浮动横幅、移动浮动横幅、原生信息流、移动插屏、桌面插屏、激励视频、激励插屏。其他类型返回 400 error.zone.type_telegram_unsupported。
这类广告位的 GET /zones/{id}/code 只返回一种 Telegram 代码，结构为 {name, description, code}：
| 键 | 广告位类型 | 说明 |
|---|---|---|
telegram_tag | 横幅类、浮动横幅、原生信息流 | 广告位标签加 SDK，放在页面里 |
telegram_programmatic | 插屏、激励 | 由你的代码调用 window.adbnk.telegram.init().show()。另有 ssv（布尔值）：激励广告位为 true，表示应以服务端回调发奖 |
Telegram 广告位不提供直链、iframe 或 VAST 形式的代码。详见 Telegram 小程序接入。
获取到 zone_key 后即可发起广告请求，详见 广告请求 API。
收益报表
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /statistics/explore | 灵活报表：自选指标、维度、筛选与对比（后台「数据报表」页使用的就是它）。参数及 export=csv|xlsx 与广告主 API一致 |
GET | /statistics/explore/meta | 当前账户可用的指标和维度 |
GET | /statistics/report | 汇总报表 |
GET | /statistics/sites | 按站点维度 |
GET | /statistics/zones | 按广告位维度 |
GET | /statistics/region | 地域（geo）报表 |
GET | /statistics/hourly | 分时报表 |
GET | /statistics/device | 设备报表 |
GET | /statistics/export | 导出 |
GET /api/publisher/statistics/report 参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
start_date | date | 否 | 起始日期，默认 7 天前 |
end_date | date | 否 | 结束日期，默认今天 |
group_by | string | 否 | 分组维度，默认 date |
site_id | int | 否 | 指定站点 |
提现
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /withdrawals/balance | 查询可提现余额 |
GET | /withdrawals | 提现记录列表 |
POST | /withdrawals | 发起提现 |
GET | /withdrawals/transactions | 资金流水 |
GET | /withdrawals/payment-methods | 可用提现渠道 |
GET | /withdrawals/bank-cards | 银行卡列表 |
POST | /withdrawals/bank-cards | 新增银行卡 |
DELETE | /withdrawals/bank-cards/{id} | 删除银行卡 |
GET | /withdrawals/{id} | 提现详情 |
POST | /withdrawals/{id}/cancel | 取消提现 |
发起提现
POST /api/publisher/withdrawals
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | number | 是 | 提现金额，须大于 0 且不低于渠道最小额 |
payment_method / channel | string | 是 | 提现渠道：BANK/USDT（当前开放的渠道） |
account_info | string | 否 | 收款账户信息（渠道相关） |
bank_info | object | 否 | 银行渠道的账户明细 |
KYC 硬门禁
提现要求账户完成 KYC 实名认证，否则返回 412。
curl -X POST https://api.adbnk.co/api/publisher/withdrawals \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"amount": 300, "payment_method": "USDT", "account_info": "TRC20:TXxxxx"}'手续费与税费按平台及渠道配置计算，最终到账金额 = 提现金额 − 手续费 − 税费。结算与提现规则详见 结算与提现指南。
TIP
更多流量主功能（黑名单、通知绑定、返佣等）请以流量主控制台为准。