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 Server API chỉ đọc để tra lịch sử. 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": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "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 đẩy: bạn không phải poll nó. Nếu bạn thực sự cần đọc lại một lượt truy cập sau đó, Server API trả lời theo requestId.

Yêu cầu

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

Phản hồi

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

Lấy các public key Ed25519 của nền tảng dùng để xác minh các lần gửi webhook. Route này không cần xác thực và được cache trong năm phút. Trường kid trong header chữ ký cho bạn biết phải dùng key nào.

Yêu cầu

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

Phản hồi

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

GET/v1/visitors/{visitorId}

Đọc lịch sử của một khách truy cập từ Server API bằng secret key của bạn. Có từ gói Pro. Cửa sổ truy vấn bị giới hạn theo gói của bạn và cửa sổ bạn thực sự nhận được sẽ được báo lại trong meta. Hỗ trợ các yêu cầu quyền truy cập dữ liệu theo GDPR.

Yêu cầu

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

Phản hồi

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

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, một secret key (tracio_sk_…) gửi dưới dạng Authorization: Bearer cho Server API, và một signing secret HMAC để xác minh các lần gửi webhook. Secret key được tạo trong bảng điều khiển, chỉ hiển thị một lần, và không bao giờ được để lọt vào trình duyệt — Server API cố ý không trả về bất kỳ header CORS nào.

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

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

Giới hạn được áp theo từng workspace. Các lệnh gọi Server API được đếm riêng với lượt nhận diện, nên việc đọc lịch sử của chính bạn không bao giờ tiêu tốn hạn mức bạn đã trả tiền. Mọi phản hồi đều mang X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset, cùng Retry-After khi gặp 429. Server API không thuộc gói Free.

Gói	Tần suất Server API	Server API mỗi ngày	Endpoint webhook	Cửa sổ truy vấn
Free	Không bao gồm	Không bao gồm	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	Không giới hạn	100	365 days

Mã lỗi

Mọi lỗi đều trả về cùng một khung: một đối tượng error với code dạng chuỗi, một message dễ đọc cho người, và requestId của lệnh gọi bị lỗi.

400Bad RequestTham số truy vấn sai định dạng, cửa sổ không được hỗ trợ, hoặc một định danh không phải visitor ID hợp lệ.

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

402Upgrade RequiredGói của bạn không bao gồm quyền truy cập Server API. Quyền này bắt đầu từ gói Pro.

404Not FoundKhông có khách truy cập hay phiên nào với định danh đó trong cửa sổ truy vấn của gói bạn.

405Method Not AllowedServer API chỉ đọc. Mọi route chỉ trả lời GET và không gì khác.

429Rate LimitedQuá nhiều yêu cầu mỗi giây, hoặc hạn mức hằng ngày đã hết. 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ợ kèm requestId.

503Service UnavailableAPI tạm thời không thể trả lời. Thử lại với exponential backoff.

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

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

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 đủ