API 概述与鉴权

ADBNK 对外提供 RESTful HTTP API，分为四类接口：

分组	前缀	鉴权	说明
广告主 API	/api/advertiser	JWT Bearer	广告主控制台后端接口
流量主 API	/api/publisher	JWT Bearer	流量主控制台后端接口
广告请求 API	/ad	无	广告位实时请求广告
事件上报 API	/track	无	展示 / 点击 / 转化上报

Base URL

所有接口的基础域名为 https://api.adbnk.co。广告请求与事件上报另有独立子域 js.adbnk.co（SDK）与 track.adbnk.co（追踪），本文示例统一以业务域名书写。

鉴权方式

广告主 / 流量主接口采用 JWT Bearer Token 鉴权。先调用对应端登录接口拿到 token，随后在每个请求的 Authorization 头携带：

Authorization: Bearer <token>

也支持通过查询参数 ?token=<token> 传递（仅用于无法自定义请求头的场景，如像素、iframe）。

Token 通过 HMAC-SHA256 签名，载荷中包含 id（用户 ID）、type（admin / advertiser / publisher）、iat、exp。默认有效期 86400 秒（24 小时），过期需重新登录。

Token 类型与路径必须匹配

广告主 token 只能访问 /api/advertiser/*，流量主 token 只能访问 /api/publisher/*，越权访问返回 401。

登录成功响应示例：

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

统一响应结构

所有接口返回统一的 JSON 信封：

{
  "code": 0,
  "message": "success",
  "data": {},
  "timestamp": 1752200000
}

字段	类型	说明
code	int	业务状态码，0 表示成功，非 0 表示失败
message	string	人类可读的提示信息（按请求语言本地化）
data	object/array/null	业务数据
timestamp	int	服务端 Unix 时间戳（秒）

当 message 来自 i18n 翻译 key 时，响应会额外附带 message_key（及可选 message_params），便于前端二次本地化。

双轨状态码

code 是主要业务信号（0 = 成功）。同时 HTTP 状态码也会与 code 对齐（成功 200，错误映射到对应 4xx/5xx），方便 CDN / WAF / 监控识别错误率。

错误码约定

code 复用 HTTP 语义，常见取值：

code	HTTP	含义
0	200	成功
400	400	参数错误 / 校验失败
401	401	未登录 / Token 无效或过期
403	403	权限不足 / 账户已禁用 / 功能已关闭
404	404	资源不存在
412	412	前置条件未满足（资料未完善 / KYC 未通过）
422	422	语义校验失败
429	429	请求过于频繁
500	500	服务端错误

错误响应示例：

{
  "code": 401,
  "message": "Invalid or expired token",
  "data": null,
  "timestamp": 1752200000
}

分页约定

列表类接口统一使用如下查询参数：

参数	类型	必填	默认	说明
page	int	否	1	页码，最小 1
page_size	int	否	20	每页数量，范围 1–100
sort_field	string	否	id	排序字段（各接口白名单限制）
sort_order	string	否	desc	排序方向：asc / desc

分页响应结构：

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [],
    "pagination": {
      "total": 135,
      "page": 1,
      "page_size": 20,
      "total_pages": 7
    }
  },
  "timestamp": 1752200000
}

限流

平台未对全部接口施加统一限流，但对敏感操作设有节流：

• 忘记密码：同一邮箱 60 秒内只能请求一次，超频返回 429。
• 事件上报：展示 / 点击去重窗口由管理端设置 ad.impression_dedup_seconds / ad.click_dedup_seconds 控制，窗口内重复事件不计费。

WARNING

具体阈值可能随平台配置调整，以实际响应为准。

跨域（CORS）

允许 *.adbnk.co、localhost、127.0.0.1 来源的跨域请求，允许 Content-Type, Authorization, X-Requested-With, Accept, Origin, X-Token 请求头。所有分组均已开启 CORS 预检（OPTIONS）处理。

---

继续阅读：广告主 API · 流量主 API · 广告请求 API · 事件与转化上报