广告主 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]",
      "advertisement_id": 8,
      "role": "ADMIN"
    }
  },
  "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；同邮箱 60 秒限一次
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 等）。可由 campaign_option_id 推导
campaign_option_id	int	否	广告格式选项 ID，可替代 ad_type
price / bid	number	是	出价，bid 会兜底为 price，不可为负
pricing_model	string	否	计费模式，默认 CPC；可选 CPM/CPA/CPS
type	string	否	计划类型，默认 PERFORMANCE
objective	string	否	投放目标，默认 TRAFFIC
daily_budget	number	否	日预算，不可为负
total_budget	number	否	总预算，不可为负
start_date / end_date	date	否	投放起止日期，空表示不限
landing_url	string	否	落地页 URL
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	否	分时 / 分日定向

curl -X POST https://api.adbnk.co/api/advertiser/campaigns \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "夏季促销",
    "ad_type": "BANNER",
    "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/report	汇总报表
GET	/statistics/campaigns	按计划维度
GET	/statistics/region	地域（geo）报表
GET	/statistics/hourly	分时报表
GET	/statistics/device	设备报表
GET	/statistics/export	导出

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

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