Tài liệu API

API chống gian lận

Một SDK trình duyệt để nhận diện, webhook có chữ ký cho các sự kiện thời gian thực, và một API quản lý workspace. Mọi thứ bạn cần để chặn gian lận ở cấp thiết bị.

Lấy API Key API Playground

Endpoint

SDK@tracio/sdk

Nhận diện khách truy cập trong trình duyệt bằng client SDK. Trả về một ID khách truy cập ổn định và kết luận bot mà không cần vòng lặp về máy chủ. Public key an toàn để đưa vào mã phía client.

Yêu cầu

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

Phản hồi

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

POST/webhook/tracio

TRACIO gửi một sự kiện có chữ ký tới endpoint của bạn ở mỗi lần nhận diện. Xác minh header X-Tracio-Signature, rồi xử lý payload JSON phẳng. Đây là bề mặt sự kiện phía máy chủ — không có phương thức đọc REST poll-by-requestId.

Yêu cầu

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

Phản hồi

{
  "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

Đăng ký một endpoint webhook qua API quản lý workspace. Được xác thực bằng JWT phiên bảng điều khiển (Clerk) của bạn và kiểm tra theo vai trò trong workspace. Signing secret chỉ được trả về một lần khi tạo.

Yêu cầu

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": [] }'

Phản hồi

{
  "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}

Tra cứu lịch sử lưu trữ của một khách truy cập qua API quản lý workspace, được xác thực bằng JWT phiên bảng điều khiển (Clerk) của bạn. Hỗ trợ các yêu cầu quyền truy cập dữ liệu theo GDPR.

Yêu cầu

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

Phản hồi

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

Xác thực

TRACIO dùng ba loại thông tin xác thực, mỗi loại cho một bề mặt: một public key cho browser SDK, JWT phiên bảng điều khiển (Clerk) của bạn cho API quản lý workspace, và một signing secret HMAC để xác minh các lần gửi webhook. Không có API secret riêng lẻ.

# 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>

Giới hạn tần suất

Giới hạn được áp theo từng workspace. Phản hồi của Management API bao gồm các header X-RateLimit-Limit, X-RateLimit-Remaining, và Retry-After.

Gói	Lượt nhận diện	Sự kiện webhook	Management API	Lượt tra cứu khách truy cập
Free	100/day	100/day	50/day	100/day
Pro	1,000/min	1,000/min	500/min	1,000/min
Enterprise	10,000/min	10,000/min	5,000/min	10,000/min

Mã lỗi

Mọi lỗi đều trả về một body JSON với các trường code, message, và details.

400Bad RequestBody yêu cầu sai định dạng hoặc thiếu các trường bắt buộc.

401UnauthorizedThiếu hoặc sai thông tin xác thực — public key (SDK), Clerk JWT (management API), hoặc chữ ký webhook.

403ForbiddenVai trò của bạn trong workspace (RBAC) không có quyền cho thao tác này.

404Not FoundKhông tìm thấy ID khách truy cập hoặc webhook trong workspace của bạn.

429Rate LimitedQuá nhiều yêu cầu. Kiểm tra header Retry-After và giới hạn của gói bạn.

500Internal ErrorLỗi máy chủ. Thử lại với exponential backoff. Nếu vẫn tiếp diễn, liên hệ hỗ trợ.

Định dạng phản hồi lỗi

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

Bắt đầu xây dựng

Lấy API key của bạn và thực hiện yêu cầu nhận diện đầu tiên trong chưa đầy 5 phút.

Lấy API Key Tài liệu API đầy đủ