Server API

Server API cho phép backend của bạn đọc dữ liệu nhận diện mà TRACIO đã thu thập cho workspace của bạn: lịch sử của một khách truy cập, từng phiên riêng lẻ, và các bộ đếm velocity trên cửa sổ ngắn.

Nó bổ sung cho Webhooks chứ không thay thế chúng:

Cả hai bề mặt đều có từ gói Pro trở lên.

URL gốc

https://api.tracio.ai/v1

Đây là một host khác với endpoint dành cho trình duyệt (edge.tracio.ai) và khác với dashboard (app.tracio.ai). Cả ba đều tách biệt: trình duyệt nói chuyện với edge bằng khóa public của bạn, còn backend của bạn nói chuyện với Server API bằng khóa secret của bạn.

Xác thực

Mỗi yêu cầu đều mang theo secret key của bạn dưới dạng bearer token:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Server API chỉ dành cho giao tiếp máy chủ với máy chủ. Các header CORS cố ý không được trả về, nên trình duyệt không thể gọi nó — đó chính là điều giữ secret key của bạn nằm ngoài mã phía client. Đừng bao giờ đưa secret key xuống trình duyệt.

Lấy secret key

Hãy tạo nó trong dashboard ở mục API Keys, chọn loại secret.

• Khóa đầy đủ chỉ được hiển thị đúng một lần, lúc tạo. Phía chúng tôi chỉ lưu một giá trị băm, nên một khóa bị thất lạc thì không thể khôi phục — hãy xoay vòng nó thay vì tìm lại.
• Một secret key có dạng tracio_sk_ theo sau là 43 ký tự, tổng cộng 53. Dashboard liệt kê nó bằng vài ký tự đầu tiên để bạn phân biệt được các khóa với nhau.
• Secret key yêu cầu gói Pro trở lên; khóa public mà agent trong trình duyệt sử dụng là một giá trị riêng biệt, không bí mật, dài 40 ký tự.

Xoay vòng secret key

Việc xoay vòng phát hành một khóa mới và giữ cho khóa cũ vẫn hoạt động trong 7 ngày, nhờ đó bạn có thể triển khai mà không phải ngừng dịch vụ. Hãy triển khai khóa mới, xác nhận lưu lượng đã chuyển sang, rồi để khóa cũ hết hạn. Public key không xoay vòng được — chúng không phải bí mật và vốn dĩ hiển thị ngay trong mã nguồn trang của bạn.

Các endpoint

Mọi route đều là GET. Server API không có thao tác ghi nào: nó đọc dữ liệu, còn cấu hình của bạn nằm trong dashboard.

Dấu gạch chéo ở cuối được chấp nhận và bị bỏ qua. Một đường dẫn không xác định hoặc một phương thức sai sẽ trả về đúng cái phong bì lỗi JSON như mọi thứ khác, không bao giờ là trang HTML hay văn bản thuần.

Cửa sổ thời gian

Mỗi lần đọc đều bị giới hạn bởi một cửa sổ thời gian, do hai tham số truy vấn tùy chọn điều khiển:

• Một ngày trần đặt ở to sẽ bao gồm trọn cả ngày hôm đó.
• Bất cứ thứ gì khác đều bị từ chối với 400 invalid_request và thông báo time must be YYYY-MM-DD or RFC3339.
• Khi bạn không truyền tham số nào, cửa sổ chính là toàn bộ thời gian lưu giữ của gói, kết thúc ở hiện tại.
• Một cửa sổ vươn xa về quá khứ hơn mức gói của bạn cho phép sẽ bị âm thầm cắt gọn chứ không bị từ chối. Cửa sổ thực sự được dùng luôn được báo lại trong meta, vì vậy hãy kiểm tra meta.from và meta.to thay vì mặc định rằng yêu cầu của bạn được tôn trọng nguyên văn.

Tra cứu một khách truy cập

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Phản hồi mang theo lịch sử tổng hợp và nhúng luôn phiên mới nhất, nhờ đó trường hợp thông thường chỉ cần một yêu cầu thay vì hai:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Một khách truy cập không có dữ liệu nào bên trong cửa sổ lưu giữ sẽ trả về 404 not_found với thông báo visitor not found in the retention window — đó không phải lỗi trong tích hợp của bạn, mà nghĩa là khách truy cập đó còn mới hoặc dữ liệu đã hết hạn lưu giữ.

Các trường phán quyết

Phiên mang theo hai phán quyết, và chúng trả lời những câu hỏi khác nhau — client có phải là tự động hay không, và cỗ máy đánh giá rủi ro kết luận tổng thể ra sao:

Cả bot.score lẫn decision.riskScore đều chạy trên thang 0..100. Từ Business trở lên, guidance biến chúng thành khuyến nghị theo từng kịch bản trên thang allow → challenge → review → deny — xem Guidance để biết ý nghĩa của từng nấc.

Liệt kê các phiên của một khách truy cập

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&minRiskScore=50"

Các phiên trở về theo thứ tự mới nhất trước:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Phân trang

Việc phân trang dựa trên con trỏ. Không có tham số page hay offset: hãy truyền lại nextCursor bạn nhận được dưới dạng cursor, và cứ tiếp tục chừng nào hasMore còn đúng.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

Hãy coi con trỏ là mờ đục — nội dung của nó là chi tiết triển khai và có thể thay đổi. Một con trỏ đã bị sửa sẽ bị từ chối với 400 invalid_request và thông báo malformed cursor.

Lấy một phiên đơn lẻ

Phiên gần đây nhất:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Endpoint này trả về một đối tượng phiên trần — không phải mảng, và không được bọc trong phong bì nào. Một khách truy cập không có phiên nào trong cửa sổ sẽ trả về 404 not_found với no sessions for this visitor in the retention window.

Hoặc theo requestId, chính là định danh cũng xuất hiện trong payload của webhook:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitorId=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Ở đây visitorId là tùy chọn, nhưng truyền nó khi bạn đã biết sẽ làm cho việc tra cứu nhanh hơn đáng kể.

Velocity

Velocity trả lời câu hỏi "gần đây khách truy cập này đã làm nhiều đến mức nào" — chính là hình dạng của credential stuffing, thử thẻ và đăng ký hàng loạt.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window chấp nhận 1h, 24h hoặc 7d và mặc định là 24h. Mọi giá trị khác đều bị từ chối với 400 invalid_request và window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts đếm số giá trị linkedId khác nhau mà bạn đã gửi cho thiết bị này — xem Liên kết tài khoản. botEvents có từ Business trở lên.

Quy ước phản hồi

Một trường vắng mặt nghĩa là "không có dữ liệu", không bao giờ là số không. Những trường không có giá trị sẽ bị lược bỏ hoàn toàn thay vì được gửi dưới dạng 0, "" hay null: một khách truy cập hoàn toàn mới thì không có matchConfidence, một lượt truy cập sạch thì không có antidetectScore hay suspectScore. Ngoại lệ cố ý duy nhất là bot.score, luôn hiện diện ngay cả khi bằng không. Hãy đọc các trường một cách phòng thủ.

Payload phụ thuộc vào gói của bạn. Mọi gói có quyền truy cập API đều nhận được phiên cơ bản — các định danh, dấu thời gian, URL, IP, user agent, trình duyệt, OS, thiết bị, geo, network, bot, identification và decision. Pro bổ sung identification.matchType, identification.matchConfidence và bot.antidetectScore. Business và Enterprise bổ sung geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo cùng các trường ở cấp con người (personId, reputation, linkedAccountsCount, linkedVisitorsCount). Việc một trường của Business vắng mặt trên gói Pro không phải là lỗi.

Phần nội bộ ở cấp tín hiệu không bao giờ được trả về, trên bất kỳ gói nào: tên của từng tín hiệu, trọng số của chúng, các ngưỡng đứng sau một phán quyết, giá trị tín hiệu thô và cách phân rã điểm số đều nằm lại ở phía chúng tôi. Một điểm số có thể bị suy ngược ra các đầu vào của nó thì không còn hữu ích như một biện pháp phòng vệ.

Lỗi

Mọi thất bại đều dùng chung một phong bì:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

requestId này không phải là định danh lượt truy cập. Hai giá trị khác nhau dùng chung một cái tên: bên trong payload của phiên, requestId là UUID của lượt truy cập, chính là cái mà webhook gửi đến; bên trong phong bì lỗi, nó là một định danh truy vết dài 24 ký tự được sinh ra cho mỗi lệnh gọi HTTP. Định danh truy vết đó cũng quay lại trong header X-Request-Id trên mọi phản hồi, dù thành công hay không. Hãy đính kèm nó khi bạn liên hệ bộ phận hỗ trợ — đó là cách chúng tôi tìm ra đúng lệnh gọi của bạn.

Các bước kiểm tra chạy theo một thứ tự cố định — khóa, rồi gói, rồi giới hạn — nên một yêu cầu với khóa sai luôn báo về khóa trước, không bao giờ báo là vấn đề hạn mức.

Hai trường hợp 401 cố ý đọc khác nhau: missing Authorization: Bearer <secret key> nghĩa là header chưa bao giờ đến, còn invalid or revoked API key nghĩa là nó đã đến nhưng không khớp. 402 mang theo Data API requires the Pro plan or higher.

Giới hạn tốc độ và hạn mức

Mọi phản hồi đã xác thực đều mang theo tình trạng hiện tại của bạn:

• Các đợt bùng ngắn được cho phép: giới hạn mỗi giây là một token bucket chịu được tới ba lần tốc độ duy trì trước khi bắt đầu từ chối.
• Một yêu cầu bị từ chối vì vượt tốc độ mỗi giây không tiêu tốn hạn mức ngày, nên một đợt bùng không thể ngốn hết ngân sách của cả ngày.
• Giới hạn của Server API được đếm tách biệt với lưu lượng nhận diện. Việc đọc lịch sử của chính bạn không bao giờ tiêu tốn số lần nhận diện mà bạn đang trả tiền.

Bước tiếp theo

• Webhooks — nhận từng lần nhận diện ngay khi nó xảy ra
• Liên kết tài khoản — gắn id tài khoản của riêng bạn với một thiết bị
• Phát hiện bot — phán quyết về bot được tạo ra như thế nào
• Quyền riêng tư & GDPR — xử lý yêu cầu của chủ thể dữ liệu