API 参考

反欺诈 API

用于识别的浏览器 SDK、用于实时事件的签名 Webhook，以及工作区管理 API。在设备层面阻止欺诈所需的一切，尽在于此。

端点

SDK@tracio/sdk

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

请求

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

响应

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

POST/webhook/tracio

每次识别时，TRACIO 都会向您的端点投递一个签名事件。校验 X-Tracio-Signature 头，然后据扁平化的 JSON 负载采取行动。这是服务端事件接口 — 不存在按 requestId 轮询的 REST 读取方式。

请求

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

响应

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}

POST/api/v1/workspaces/{workspaceId}/webhooks

通过工作区管理 API 注册一个 Webhook 端点。使用您的仪表盘会话（Clerk）JWT 进行认证，并按您的工作区角色进行校验。签名密钥仅在创建时返回一次。

请求

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

响应

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}

GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

通过工作区管理 API 查询访客已存储的历史记录，使用您的仪表盘会话（Clerk）JWT 进行认证。可支撑 GDPR 访问权请求。

请求

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

响应

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

认证

TRACIO 使用三种凭据，每个接口一种：用于浏览器 SDK 的公钥、用于工作区管理 API 的仪表盘会话（Clerk）JWT，以及用于校验 Webhook 投递的 HMAC 签名密钥。不存在独立的 API 密钥。

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

速率限制

限制以工作区为单位。管理 API 的响应包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 Retry-After 头。

方案	识别次数	Webhook 事件	管理 API	访客查询
免费版	100/day	100/day	50/day	100/day
专业版	1,000/min	1,000/min	500/min	1,000/min
企业版	10,000/min	10,000/min	5,000/min	10,000/min

错误码

所有错误都返回一个 JSON 主体，包含 code、message 和 details 字段。

400错误请求请求主体格式错误或缺少必填字段。

401未授权凭据缺失或无效 — 公钥（SDK）、Clerk JWT（管理 API）或 Webhook 签名。

403禁止访问您的工作区角色（RBAC）无权执行此操作。

404未找到在您的工作区中未找到访客 ID 或 Webhook。

429触发速率限制请求过多。请检查 Retry-After 头和您的方案限额。

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

错误响应格式

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

开始构建

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

获取 API 密钥完整 API 文档