Data API

Data API (trước đây được mô tả tại trang này là 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. Một vài route cũng ghi dữ liệu — bản ghi tài khoản, trường tùy chỉnh và mục danh sách — để backend của bạn có thể làm giàu những gì TRACIO biết.

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/v2

Đâ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 Data API bằng khóa secret của bạn.

Chuyển từ v1

Các route /v1 đã bị gỡ bỏ. Hãy dùng /v2: các route giữ nguyên, và mọi khóa JSON cũng như tham số truy vấn đều ở dạng snake_case (visitor_id, risk_score, min_risk_score). Các khóa bên trong từ điển fields và labels của riêng bạn là dữ liệu của bạn và giữ nguyên cách viết gốc. JavaScript SDK vẫn giữ giao diện camelCase.

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/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Data 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ự.
• Khóa được gắn với một môi trường: khóa production không nhìn thấy khách truy cập từ staging — phản hồi là 404, giống hệt như với dữ liệu không tồn tại.

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

Cùng khóa và host đó cũng phục vụ các API quyết định, tất cả đều ở dạng snake_case:

Kết quả của chúng cũng đến với bạn dưới dạng sự kiện webhook: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked và affiliate_threshold_crossed.

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/v2/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:

{
  "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "first_seen_at": "2026-05-02T10:11:12Z",
  "last_seen_at": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognito_visits": 3,
  "unique_ips": 5,
  "unique_countries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "max_risk_score": 63,
    "avg_bot_score": 12.5,
    "bot_sessions": 7,
    "last_decision": "real"
  },
  "network": {
    "vpn_seen": false,
    "proxy_seen": false,
    "tor_seen": false,
    "datacenter_seen": true,
    "proxy_detected_seen": true,
    "last_isp": "Deutsche Telekom",
    "last_real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  "last_session": {
    "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "account_id": "user_8842",
    "account": { "id": "user_8842", "email": "ann@example.com", "display_name": "Ann Lee" },
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "fields": { "order_ref": "A-1029" },
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "user_agent": "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",
    "gpu": "Apple M2",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "connection_type": "residential",
      "proxy_detected": true,
      "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "store_url": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetect_score": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "match_type": "exact",
      "match_confidence": 0.99
    },
    "device_info": {
      "device_id": "d_4f9c2e",
      "cross_browser": true,
      "confidence": 0.88,
      "linked_browsers": 2
    },
    "decision": { "action": "real", "risk_score": 12, "suspect_score": 3 }
  },
  "meta": {
    "plan": "business",
    "retention_days": 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.risk_score đề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. Giá trị và thang đo khớp với phần thân webhook v3 của cùng lượt truy cập, và guidance được tính theo cùng các quy tắ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/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&min_risk_score=50"

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

{
  "items": [
    {
      "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "next_cursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "has_more": true,
  "meta": {
    "plan": "business",
    "retention_days": 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 next_cursor bạn nhận được dưới dạng cursor, và cứ tiếp tục chừng nào has_more còn đúng. Trang cuối có thể hoàn toàn không có next_cursor, nên đừng bắt buộc trường đó.

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

  do {
    const url = new URL(`https://api.tracio.ai/v2/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(`Data API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.has_more ? page.next_cursor : undefined
  } 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.

Dữ kiện thiết bị

Bên cạnh trình duyệt và hệ điều hành lấy từ User-Agent, một phiên còn mang những gì trình duyệt của khách truy cập báo cáo về cỗ máy, đã được làm sạch ở phía chúng tôi. Mỗi trường sẽ vắng mặt khi lượt truy cập không mang theo dữ liệu như vậy, nên hãy coi từng trường là tùy chọn.

Tiện ích mở rộng trình duyệt

extensions liệt kê các tiện ích mở rộng của trình duyệt được phát hiện trong lượt truy cập — từ Pro trở lên. Mỗi mục là một đối tượng:

Một phát hiện chỉ được báo cáo sau khi đã vượt qua các kiểm tra độ tin cậy của chúng tôi — một môi trường trả lời "đã cài đặt" cho mọi phép dò, hoặc một lô dài hơn 12 cái tên, sẽ bị loại bỏ vì không đáng tin. Vì vậy một danh sách rỗng hoặc vắng mặt có nghĩa là "không có gì chúng tôi xác nhận được", chứ không phải "không có tiện ích mở rộng nào được cài". Hãy đọc nó như bằng chứng, chứ không phải như một bản kiểm kê.

Trường tùy chỉnh

fields chứa các cặp khóa–giá trị tùy chỉnh mà tích hợp của bạn đã gắn vào lượt truy cập — mã tham chiếu đơn hàng, tên gói, kết quả thanh toán. Khóa và giá trị luôn là chuỗi: số hoặc giá trị boolean bạn gắn vào sẽ được trả về dưới dạng văn bản. Giống như phần còn lại của phiên, trường này có trên mọi gói có quyền truy cập API (từ Pro trở lên) và không xuất hiện khi lượt truy cập không có trường nào.

fields được đọc trực tiếp ở mỗi yêu cầu, không được sao chép tại thời điểm truy cập. Các trường gắn vào sau lượt truy cập (xem Gắn trường sau lượt truy cập) cũng xuất hiện ở đây, nên với cùng một lượt truy cập, fields có thể chứa nhiều hơn những gì webhook đã gửi.

Đừng đưa dữ liệu cá nhân như họ tên, địa chỉ email hay số điện thoại vào trường tùy chỉnh — thay vào đó, hãy gắn một mã tham chiếu mà hệ thống của chính bạn có thể tra ra, và gửi thông tin tài khoản là ai dưới dạng bản ghi tài khoản (bên dưới).

Bản ghi tài khoản

account là bản ghi của bạn cho tài khoản đứng sau lượt truy cập — thứ bạn đã gửi gần nhất cho account_id đó qua POST /v2/accounts/metadata:

{
  "account": { "id": "user-42", "email": "ann@example.com", "display_name": "Ann Lee" }
}

Bản ghi được đọc trực tiếp ở mỗi yêu cầu, nên việc đổi tên cũng hiện ra trên các lượt truy cập cũ: khối này mô tả tài khoản như hiện tại, chứ không phải như lúc truy cập. Nó có trên mọi gói có quyền truy cập API (từ Pro trở lên). Các nhãn bạn gửi kèm bản ghi không được trả về.

Khối này vắng mặt khi lượt truy cập không có tài khoản liên kết, khi không có bản ghi cho tài khoản đó (hoặc bạn đã xóa nó bằng cách gửi giá trị rỗng), và — hiếm khi — khi không đọc được bản ghi: phiên vẫn được trả về đầy đủ thay vì làm yêu cầu thất bại, nên hãy coi khối vắng mặt là "không rõ", chứ không phải "tài khoản này không có email". Webhook không mang khối này.

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/v2/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 request_id, 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/v2/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitor_id=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Ở đây visitor_id 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ể.

identification.drift_score — điểm hành vi đã làm mượt mà phán quyết chiếm đoạt tài khoản dựa vào, từ Business trở lên — chỉ được trả về bởi lần đọc một phiên này. Độ lệch hành vi được đo trong lượt truy cập, sau lần nhận diện ban đầu, nên các route danh sách và phiên mới nhất bỏ qua nó. Một lượt truy cập có hành vi chưa từng được đánh giá thì không có drift_score. Cùng giá trị đó đến với bạn qua webhook account_takeover.

Bạn nhận được câu trả lời nào cho một lượt truy cập đã được hiệu chỉnh

Một lượt truy cập có thể được gửi qua webhook nhiều hơn một lần: primary trước, sau đó là late hoặc correction khi các tín hiệu chậm hơn và bằng chứng hành vi đến — và một pha sau có thể lật ngược phán quyết trước đó. Data API trả lời từ bản ghi primary. Các pha sau không được gộp ngược vào đó, nên với một lượt truy cập đã được hiệu chỉnh, webhook cuối cùng là câu trả lời mới hơn. Nếu bạn hành động vài phút sau lượt truy cập, hãy ưu tiên pha bạn nhận được sau cùng thay vì một lần đọc mới ở đây.

Có một điều diễn ra theo chiều ngược lại: khi bộ phát hiện chiếm đoạt tài khoản đã kích hoạt cho một lượt truy cập, guidance ở đây phản ánh điều đó, trong khi các phần thân webhook identification của cùng lượt truy cập không mang trục đó — nó đi theo lần gửi account_takeover riêng.

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/v2/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,
  "unique_ips": 9,
  "unique_countries": 3,
  "unique_accounts": 12,
  "bot_events": 4,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

unique_accounts đế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. bot_events có từ Business trở lên; ở Pro khóa này vắng mặt.

Siêu dữ liệu tài khoản

TRACIO chỉ biết các tài khoản của bạn qua ID mà trang của bạn truyền dưới dạng linkedId — một chuỗi mờ đục như usr_8412. Hãy gửi các nhãn dễ đọc một lần, và mọi màn hình dashboard hiển thị tài khoản đó sẽ hiển thị tên hoặc email thay cho ID thô, còn đối tượng phiên trả chúng về trong khối account. Không có gì ở đây ảnh hưởng đến việc phát hiện hay chấm điểm; đây là một lớp hiển thị.

curl -s -X POST "https://api.tracio.ai/v2/accounts/metadata" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[
        {"account_id":"usr_8412","email":"ann@example.com","display_name":"Ann Lee","labels":{"tier":"vip"}},
        {"account_id":"usr_9130","display_name":"Bob Ray"}
      ]}'

{ "updated": 2 }

• Đây là nơi dành cho dữ liệu cá nhân về một tài khoản — không phải fields. Email hoặc tên gửi đến đây chỉ nằm trong bản ghi tài khoản của workspace: nó không được lưu theo từng lượt truy cập, không được ghi vào trang, và một lần gửi cập nhật mọi lượt truy cập của tài khoản đó.
• Phạm vi là workspace và môi trường của khóa. Khóa staging không bao giờ ghi đè những gì khóa production đã ghi cho cùng ID tài khoản.
• Mỗi lần gửi là ghi đè toàn bộ, không phải vá. Các trường bạn bỏ qua được lưu là rỗng — hãy gửi bản ghi đầy đủ mỗi lần. Đó cũng là cách xóa một giá trị.
• Trường không xác định bị từ chối với 400 invalid_request, và một mục sai sẽ làm từ chối cả lô — lỗi nêu rõ vị trí của nó. ID tài khoản trùng lặp trong một lô thì không sao: mục cuối cùng thắng.

Giới hạn: 1000 tài khoản cho một yêu cầu, thân 1 MiB, account_id ≤ 256 ký tự, email ≤ 320, display_name ≤ 256, tối đa 16 nhãn với khóa ≤ 64 và giá trị ≤ 256 ký tự.

Gắn trường sau lượt truy cập

Trình duyệt chỉ có thể gửi những gì trang biết vào lúc render — mã đơn hàng, không bao giờ là kết quả kiểm tra thanh toán hay bất cứ thứ gì được xác định sau đó. Route này lấp khoảng trống đó: tìm lượt truy cập theo một trường nó đã mang, và gắn thêm trường cho nó từ phía máy chủ.

curl -s -X POST "https://api.tracio.ai/v2/events/fields" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"},"fields":{"amount":"120.00"}}'

{ "updated": 1 }

• match tìm lượt truy cập theo một trường nó đã có, không phải theo request_id, trong workspace và môi trường của khóa.
• Cửa sổ tìm kiếm là 24 giờ. Lượt truy cập cũ hơn trả về 404 not_found — hãy ghi trường ngay sau khi kết quả được xác định.
• updated đếm số lượt truy cập khác nhau. Nó vượt quá 1 chỉ khi match của bạn trúng nhiều hơn một lượt truy cập — một cặp khóa/giá trị không riêng cho một đơn hàng hay giỏ hàng. Một match trúng hơn 100 sự kiện bị từ chối với 400 invalid_request thay vì được áp dụng cho một tập con tùy ý.
• Trường được ghi ở đây hiển thị trong dashboard với thẻ server, và được ưu tiên hơn giá trị cùng khóa do trình duyệt ghi.
• Không khớp là 404 not_found, không phải 200 rỗng.

Giới hạn giống kênh trình duyệt: 50 trường cho một lệnh gọi, khóa ≤ 40 byte, giá trị ≤ 500 byte — byte, không phải ký tự — bộ ký tự của khóa A-Za-z0-9_.:-, thân 1 MiB.

Xóa trường

Xóa các trường tùy chỉnh — không bao giờ xóa bản thân lượt truy cập. Hãy dùng nó cho những giá trị bạn không còn cần gắn với lượt truy cập, chẳng hạn tổng tiền đơn hàng. Các webhook đã gửi và các bản xuất đã lấy không bị thay đổi.

# by request_id — clears every field on this one visit
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31"}'

# by match — clears "order_ref" from every visit currently holding "A-1029"
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"}}'

{ "deleted": 1 }

• request_id và match loại trừ nhau — gửi cả hai, hoặc không gửi cái nào, là 400 invalid_request. match dùng cùng cửa sổ 24 giờ và cùng trần 100 sự kiện như khi gắn.
• deleted đếm số trường bị gỡ khỏi lượt truy cập (theo request_id) hoặc số lượt truy cập mà trường bị gỡ khỏi (theo match).
• Gọi lại khi không còn gì sẽ trả về 404 not_found.

Danh sách của workspace

Chính những danh sách mà người vận hành của bạn quản lý trong dashboard, truy cập được từ back office của riêng bạn. Loại của danh sách là hành động của nó với lượt truy cập khớp — block, manual_review, challenge, allow — còn chế độ quyết định hành động có được áp dụng hay không: observe chỉ đếm số lần khớp, enforce áp dụng nó vào guidance (trục list). Danh sách và chế độ của chúng được tạo trong dashboard; Data API đọc danh sách và thêm, gỡ các mục.

curl -s "https://api.tracio.ai/v2/lists" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

[
  {
    "id": "7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60",
    "name": "Chargeback accounts",
    "type": "block",
    "mode": "enforce",
    "entries_count": 128
  }
]

# ban an account for 30 days
curl -s -X POST "https://api.tracio.ai/v2/lists/7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60/entries" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"value":"usr_8412","value_type":"linked_id","ttl_minutes":43200}'

{
  "id": "02b4c8d1-6e7f-4a90-b1c2-d3e4f5a6b7c8",
  "value": "usr_8412",
  "value_type": "linked_id",
  "expires_at": "2026-10-19T12:00:00Z",
  "propagation": "immediate"
}

Gỡ một mục bằng cùng phần thân tại POST /v2/lists/{list_id}/entries/delete; câu trả lời là { "removed": true, "propagation": "immediate" }.

• value_type là thứ mà giá trị được đối chiếu: linked_id, visitor_id, device_id, ip, cidr hoặc country. Giá trị không phân tích được theo loại của nó là 400 invalid_request.
• Khi nhiều danh sách cùng khớp, loại cụ thể nhất sẽ quyết định — linked_id → visitor_id → device_id → ip → cidr → country — và trong loại đó hành động nghiêm ngặt nhất sẽ thắng.
• ttl_minutes là tùy chọn. Nếu bỏ qua, TTL mặc định của danh sách được áp dụng; nếu không có, mục không bao giờ hết hạn (expires_at là null). Thêm lại một mục sẽ gia hạn nó.
• propagation cho biết khi nào thay đổi có hiệu lực: immediate, hoặc ttl — trong khoảng năm phút.
• Xóa một giá trị không có ở đó là 200 với removed: false; 404 được dành cho danh sách không xác định.

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ó match_confidence, một lượt truy cập sạch thì không có antidetect_score hay suspect_score. 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. Quyền truy cập API bắt đầu từ Pro, và Pro 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 — cùng với identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields và account. Business và Enterprise bổ sung geo.isp, network.asn, network.real_ip, decision.suspect_score, identification.drift_score, reasons, behavior, guidance, device_info, spoofing, os_environment, screen, locale, client_hints và environment. Các trường ở cấp con người (person_id, reputation, linked_accounts_count, linked_visitors_count) được dành riêng cho Business và Enterprise và sẽ xuất hiện khi lớp con người được bật — hiện nay nó chạy ở chế độ quan sát và các trường này chưa được gửi đi. 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>",
    "request_id": "8f14e45fceea167a5a36dedd"
  }
}

request_id 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, request_id 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. Dữ liệu từ workspace khác không thể phân biệt với dữ liệu không tồn tại: nó cho ra 404, không phải 403.

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.

Hãy thử lại 429 và 503 với khoảng nghỉ tăng dần; thử lại các 4xx khác là vô ích — chúng có nghĩa là bản thân yêu cầu cần được sửa.

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

Các phản hồi mà khóa đã được nhận ra sẽ mang theo tình trạng hiện tại của bạn (phản hồi 401 và 402 thì không, và Enterprise, vốn không có hạn mức ngày, không nhận header hạn mức):

• 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 Data 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