反欺诈数据 API
数据 API 是 Web SDK 的服务端搭档。用它来拉取裁决、汇总统计、导出数据, 用于报表与对账——拉取你自己系统据以一致的那些数字。
基础 URL
https://apiv1.captcha.la鉴权
所有数据 API 请求都用你的反欺诈应用凭据鉴权,以请求头形式发送:
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRETWARNING
X-App-Secret 仅限服务端。绝不要把它暴露给浏览器、移动端或公开仓库。 页面 SDK 始终只使用公开的 appKey。
端点
获取单条裁决
获取某一次访问的裁决(例如用于对账某次具体访问)。
GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET响应的 data 是一个 BotVerdict 对象:
{
"code": 0,
"data": {
"is_bot": true,
"score": 87,
"level": "high",
"action": "flag",
"consistency": { "ok": false },
"degraded": false
}
}汇总统计
按时间范围拉取分桶计数——总量、机器人占比,以及按 action/level 的拆分—— 用于看板与质量报表。
GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET{
"code": 0,
"data": {
"from": "2026-06-01",
"to": "2026-06-30",
"total": 124500,
"bots": 18230,
"bot_rate": 0.146,
"by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
"by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
}
}导出
按时间范围导出逐次访问的裁决行,用于离线对账。
GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET每一行携带该次访问的标识、时间戳,以及裁决字段 (is_bot、score、level、action),你可据此与自己的日志关联。
逐点击对账
对于付费流量场景,一次访问可以回溯到某次具体投递的点击,供双方就此结算。这用到 点击 token,见广告反作弊指南。
Click token 参考(给流量方)
流量方在自己的服务器上签一枚 click token,加到目标 URL 上,这样这次访问的裁决就能归属回该流量方。签名是离线的——不需要调用 API。
获取签名凭据
在 dashboard 里打开你的 app → 反欺诈 → 签发签名密钥,会得到:
bot_kid—— 你的公开 key id(作为 token 里的pkid)。bot_hmac_secret—— 你的签名 secret,只显示一次,务必存在服务端。
Token 格式
ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>body 是 JSON payload 的 base64url;签名对该 body 字符串计算。
payload 字段
| 字段 | 必填 | 说明 |
|---|---|---|
pkid | 是 | 你的 bot_kid;后端据此反查你的 secret 验签 |
cid | 是 | 本次点击的唯一 id,对账主键。每次点击生成全新唯一值 |
aud | 否 | 目标广告主的 app_key。设了之后 token 只在该广告主页面被承接;不设则任意广告主页面都可承接 |
click_ts | 否 | 点击发生的 unix 秒 |
exp | 否 | unix 秒过期时间;过期 token 被拒 |
加到链接上
把 token 作为 _ctk 查询参数加到广告主目标 URL:
https://advertiser.example/lp?_ctk=ct.<...>.<...>广告主的 SDK 会自动读取 _ctk(可用 tokenParam 配置参数名)。同一 cid 只能被认领一次(防重放)。见 安全模型。
示例(伪代码)
const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body = base64url(JSON.stringify(payload))
const sig = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url = `${destination}?_ctk=${encodeURIComponent(token)}`Postback(服务端到服务端推送)
除了轮询数据 API,你还可以让裁决在产生时主动推送到你自己的端点—— 对希望实时记录/对账每次访问的联盟 tracker 和广告主服务端很方便。
启用
在 dashboard 里打开你的 app → 反欺诈 → 设置 Postback URL (bot_postback_url)。设了之后,每条裁决都会在产生后不久 POST 到该 URL。 推送是异步且隔离的——端点慢或失败,绝不影响已返回给页面 SDK 的裁决。
推送时机
每次产生该 app 裁决的 verify 都会触发。推送尽力而为,带少量自动重试; 按 至少一次 语义处理,以 cid 去重。
请求
POST <你的 bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>Body(JSON):
{
"cid": "CID_OF_THE_VISIT",
"is_bot": 1,
"score": 87,
"level": "high",
"action": "flag",
"advertiser_app_id": 12,
"provider_app_id": 34,
"created_at": "2026-06-25 00:00:00"
}| 字段 | 说明 |
|---|---|
cid | 本次访问的对账主键(无 click token 时可能为 null) |
is_bot | 1 / 0 |
score | 风险分 |
level | low / medium / high / critical |
action | 服务端权威 action(record_only / flag / challenge) |
advertiser_app_id | 本次 verify 所属 app 的 id |
provider_app_id | 经 click token 归属时的流量方 id,否则为 null |
created_at | 裁决时间(UTC) |
验签
X-Bot-Signature 头让你确认请求确实来自我们。格式为 t=<unix_ts>,v=<hex>,其中:
hex = HMAC_SHA256( "<unix_ts>." + 原始请求体 , bot_hmac_secret )bot_hmac_secret 就是你在反欺诈 → 签发签名密钥 拿到的那枚签名 secret。 验签时对收到的原始 body 重算 HMAC(不要把 JSON 重新序列化),常量时间比较。 可选地拒绝 t 与本机时钟偏差过大的请求以限制重放。
// Express 示例
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2) // 去掉 "t=" 前缀
const v = vPart.slice(2) // 去掉 "v=" 前缀
const expected = crypto
.createHmac('sha256', BOT_HMAC_SECRET)
.update(ts + '.' + rawBody) // rawBody 是未解析的原始请求体
.digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))