广告主 API

广告主端接口前缀为 /api/advertiser。除登录 / 注册 / 找回密码外，均需在请求头携带广告主 JWT：Authorization: Bearer <token>。

响应结构、分页与错误码约定见 概述与鉴权。

认证

登录

POST /api/advertiser/auth/login

参数	类型	必填	说明
username	string	是	用户名，也支持用注册邮箱登录
password	string	是	登录密码

curl -X POST https://api.adbnk.co/api/advertiser/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"secret123"}'

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi....",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 12,
      "username": "demo",
      "nickname": "Demo",
      "email": "[email protected]"
    }
  },
  "timestamp": 1752200000
}

注册

POST /api/advertiser/auth/register

采用渐进式 KYC，最小必填仅 email + password。注册成功直接返回可用 token。

参数	类型	必填	说明
email	string	是	有效邮箱，全局唯一
password	string	是	密码，至少 8 位
username	string	否	不填则自动派生（3-30 位字母数字下划线）
mobile	string	否	手机号
company_name	string	否	公司名称
contact_name	string	否	联系人
industry	string	否	行业名称

其他认证接口

方法	路径	说明
POST	/auth/forgot-password	发送重置邮件，参数 email；请求过于频繁时返回 429
POST	/auth/reset-password	参数 token、new_password、confirm_password
POST	/auth/logout	登出（前端丢弃 token 即可）
GET	/auth/profile	获取当前登录广告主信息
POST	/auth/password	修改密码，参数 old_password、new_password、confirm_password

推广计划（Campaign）

列表

GET /api/advertiser/campaigns

参数	类型	必填	说明
page / page_size	int	否	分页
keyword	string	否	按名称模糊搜索
status	string	否	状态筛选
pricing_model	string	否	计费模式筛选
start_date / end_date	date	否	创建时间范围

创建

POST /api/advertiser/campaigns

前置条件

创建推广计划会进入审核流程，要求账户资料完善度达到 basic，否则返回 412。

参数	类型	必填	说明
name	string	是	计划名称
ad_type	string	否	不传即「智能投放」（推荐）：由素材决定投放到哪里。仅在要把计划限定到某一种格式时才设置（BANNER/NATIVE/VIDEO/POPUP/REWARDED/RESPONSIVE 等）
price / bid	number	是	出价，bid 会兜底为 price，不可为负
pricing_model	string	否	计费模式，默认 CPC；可选 CPM/CPA/CPV/CPS
type	string	否	计划类型，默认 PERFORMANCE
objective	string	否	投放目标，默认 TRAFFIC
daily_budget	number	否	日预算，不可为负
total_budget	number	否	总预算，不可为负
start_date / end_date	date	否	投放起止日期，空表示不限
landing_url	string	否	落地页 URL（https://）
tracker_id	int	否	转化追踪器 ID；CPA/CPS 计费时必填
rotation_mode	string	否	轮播模式，默认 EVEN
target_countries	array	否	定向国家/地区
target_devices	array	否	定向设备
target_os	array	否	定向操作系统
target_browsers	array	否	定向浏览器
target_hours / weekdays	array	否	分时 / 分日定向
bid_adjustments	object	否	分维度竞价调整，见下

bid_adjustments

bid_adjustments 按维度对基础出价做百分比加价 / 减价。只接受 device、geo、os 三个维度，每个维度是「取值 → 百分比」的映射：

{
  "device": { "MOBILE": 20, "PC": -10 },
  "geo":    { "US": 15, "JP": -20 },
  "os":     { "ANDROID": -5 }
}

键在保存时统一转大写。百分比被钳制到 [-90, 500]；0 与无法解析的项会被丢弃，最终为空的对象存为 null。引擎会把命中该次请求的各维度百分比相加后作用于基础出价——计算方式与边界情况见定向与竞价。

curl -X POST https://api.adbnk.co/api/advertiser/campaigns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "夏季促销",
    "pricing_model": "CPC",
    "bid": 0.35,
    "daily_budget": 200,
    "landing_url": "https://shop.example.com"
  }'

其他计划操作

方法	路径	说明
GET	/campaigns/{id}	详情
PUT	/campaigns/{id}	更新
DELETE	/campaigns/{id}	删除计划及其下的广告（素材仍保留在素材库）
POST	/campaigns/{id}/toggle	启停
POST	/campaigns/{id}/copy	复制
POST	/campaigns/{id}/submit-audit	提交审核
POST	/campaigns/batch-submit-audit	批量提交审核
GET	/campaigns/{id}/stats	计划统计

广告与广告组

广告组 /api/advertiser/adgroups、广告 /api/advertiser/ads 均提供标准 CRUD（index / show / store / update / destroy）以及 toggle、stats、submit-audit 等操作，结构与推广计划一致。

素材与素材库

素材列表

GET /api/advertiser/creatives

参数	类型	必填	说明
keyword	string	否	名称搜索
type	string	否	素材类型
status	string	否	状态
audit_status	string	否	审核状态

创建素材

POST /api/advertiser/creatives

参数	类型	必填	说明
name	string	是	素材名称
creative_type	string	否	素材子类型，默认 image（须在允许集合内）
type	string	否	展示类型，默认 IMAGE
size_id / width / height	int	否	尺寸
image_media_id	int	否	主图素材 ID（推荐，来自素材库）
image_media_id_2	int	否	第二张图素材 ID
video_media_id	int	否	视频素材 ID
icon_media_id	int	否	图标素材 ID
html_code	string	否	HTML 广告代码
vast_xml / vast_url	string	否	VAST 视频广告
click_url	string	否	点击 URL

素材以 media_id 为准

广告主创建/更新素材时，*_url 字段不接受外部 URL，图片/视频只能通过素材库 *_media_id 引用，由服务端解析出可用 URL。

素材库接口：GET /media、POST /media/upload、POST /media/ai-image、POST /media/ai-video、POST /media/ai-copy。

上传辅助：POST /creatives/upload（图片）、POST /creatives/upload-video（视频）。

报表统计

所有报表默认时间范围为最近 7 天。

方法	路径	说明
GET	/statistics/explore	灵活报表：自选指标、维度、筛选与对比（后台「数据报表」页使用的就是它）
GET	/statistics/explore/meta	当前账户可用的指标和维度
GET	/statistics/saved-reports	保存的报表配置（POST 新建，/{id} 上 PUT / DELETE 修改或删除）
GET	/statistics/report	汇总报表
GET	/statistics/campaigns	按计划维度
GET	/statistics/region	地域（geo）报表
GET	/statistics/hourly	分时报表
GET	/statistics/device	设备报表
GET	/statistics/export	导出

GET /api/advertiser/statistics/explore 参数：

参数	类型	必填	说明
start_date / end_date	date	否	日期范围，默认最近 7 天
dimensions	string	否	逗号分隔的行维度，最多四个，默认 date；可选值见 /statistics/explore/meta
columns	string	否	逗号分隔的返回指标，默认标准指标集
filters / exclude	object	否	包含 / 排除指定维度取值，如 {"country":["US"]}
compare	string	否	previous / year / custom（配合 compare_start_date / compare_end_date），默认 none
sort / order	string	否	排序的指标或维度，以及 asc / desc
export	string	否	csv 或 xlsx，把当前视图下载为文件

GET /api/advertiser/statistics/report 参数：

参数	类型	必填	说明
start_date	date	否	起始日期，默认 7 天前
end_date	date	否	结束日期，默认今天
group_by	string	否	分组维度，默认 date
campaign_id	int	否	指定计划

curl "https://api.adbnk.co/api/advertiser/statistics/region?start_date=2026-07-01&end_date=2026-07-10" \
  -H "Authorization: Bearer <token>"

余额与充值

方法	路径	说明
GET	/deposits/balance	查询账户余额
GET	/deposits	充值订单列表
POST	/deposits	发起充值
GET	/deposits/transactions	资金流水
GET	/deposits/{id}	充值订单详情
POST	/deposits/{id}/cancel	取消订单

发起充值

POST /api/advertiser/deposits

参数	类型	必填	说明
amount	number	是	充值金额，须大于 0 且不低于最小充值额
payment_method	string	是	支付方式：BANK/USDT/ALIPAY/WECHAT/OFFLINE

前置条件

充值要求账户资料完善度达到 basic，否则返回 412。

curl -X POST https://api.adbnk.co/api/advertiser/deposits \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "payment_method": "USDT"}'

转化追踪器

创建 / 管理转化追踪器详见 事件与转化上报 及 转化追踪指南。相关接口位于 /api/advertiser/trackers。

TIP

更多广告主功能（优化规则、响应式广告、返佣、通知绑定等）请以广告主控制台为准。