API 参考

反欺诈 API

用于识别的浏览器 SDK、用于实时事件的签名 Webhook，以及用于查询历史的只读 Server API。在设备层面阻止欺诈所需的一切，尽在于此。

端点

SDK@tracio/sdk

使用客户端 SDK 在浏览器中识别访客。无需服务端往返，即可返回稳定的访客 ID 和机器人判定。公钥可安全地嵌入客户端代码中。

请求

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

响应

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

每次识别时，TRACIO 都会向您的端点投递一个签名事件。校验 X-Tracio-Signature 头，然后依据扁平化的 JSON 负载采取行动。这是推送接口：您无需为此轮询。如果确实需要事后读取某次访问，Server API 支持按 requestId 查询。

请求

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

响应

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

获取用于校验 Webhook 投递的平台 Ed25519 公钥。该路由无需认证，并缓存五分钟。签名头中的 kid 会告诉您该使用哪把密钥。

请求

curl https://api.tracio.ai/.well-known/webhook-keys

响应

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

使用您的密钥从 Server API 读取访客的历史记录。自 Pro 方案起提供。查询窗口受您的方案限制，实际获得的窗口会在 meta 中返回。可支撑 GDPR 访问权请求。

请求

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

响应

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

认证

TRACIO 使用三种凭据，每个接口一种：用于浏览器 SDK 的公钥、以 Authorization: Bearer 发送给 Server API 的密钥（tracio_sk_…），以及用于校验 Webhook 投递的 HMAC 签名密钥。密钥在仪表盘中创建，仅显示一次，且绝不能进入浏览器——Server API 有意不返回任何 CORS 头。

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

速率限制

限制以工作区为单位。Server API 调用与识别次数分开计数，因此读取自己的历史记录绝不会消耗您付费购买的配额。每个响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset，429 时还会附带 Retry-After。Free 方案不包含 Server API。

方案	Server API 速率	Server API 每日上限	Webhook 端点	查询窗口
免费版	不包含	不包含	0	7 days
专业版	10 req/s	10,000	5	30 days
商业版	50 req/s	100,000	20	90 days
企业版	200 req/s	无限制	100	365 days

错误码

所有错误都返回同一种封装：一个 error 对象，包含字符串 code、可读的 message，以及本次失败调用的 requestId。

400错误请求查询参数格式错误、窗口不受支持，或标识符不是有效的访客 ID。

401未授权凭据缺失或无效 — 公钥（SDK）、密钥（Server API）或 Webhook 签名。

402需要升级您的方案不包含 Server API 访问权限。该权限自 Pro 方案起提供。

404未找到在您方案的查询窗口内未找到该标识符对应的访客或会话。

405方法不允许Server API 为只读。所有路由仅响应 GET，别无其他。

429触发速率限制每秒请求过多，或每日配额已用尽。请检查 Retry-After 头和您的方案限额。

500内部错误服务器错误。请采用指数退避重试。若持续出现，请携带 requestId 联系支持团队。

503服务不可用API 暂时无法响应。请采用指数退避重试。

错误响应格式

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

开始构建

获取您的 API 密钥，在 5 分钟内发起您的首次识别请求。

获取 API 密钥完整 API 文档