Data API

Data API (เดิมมีเอกสารในหน้านี้ในชื่อ Server API) ให้แบ็กเอนด์ของคุณอ่านข้อมูลการระบุตัวตนที่ TRACIO เก็บไว้ให้ workspace ของคุณแล้ว ได้แก่ ประวัติของผู้เข้าชมรายหนึ่ง เซสชันแต่ละครั้ง และตัวนับ velocity ในช่วงเวลาสั้น ๆ มีบางเส้นทางที่เขียนข้อมูลได้ด้วย — เรคคอร์ดบัญชี ฟิลด์ที่กำหนดเอง และรายการในลิสต์ — เพื่อให้แบ็กเอนด์ของคุณเสริมข้อมูลที่ TRACIO รู้ได้

มันเสริม Webhooks มากกว่าจะมาแทนที่

ทั้งสองพื้นผิวใช้ได้ตั้งแต่แพ็กเกจ Pro ขึ้นไป

URL หลัก

https://api.tracio.ai/v2

นี่คือโฮสต์คนละตัวกับปลายทางฝั่งเบราว์เซอร์ (edge.tracio.ai) และคนละตัวกับแดชบอร์ด (app.tracio.ai) ทั้งสามแยกจากกัน เบราว์เซอร์คุยกับ edge ด้วยคีย์ public ของคุณ ส่วน แบ็กเอนด์ของคุณคุยกับ Data API ด้วยคีย์ secret ของคุณ

การย้ายจาก v1

เส้นทาง /v1 ถูกนำออกแล้ว ให้ใช้ /v2 แทน เส้นทางเหมือนเดิม และทุกคีย์ JSON และพารามิเตอร์ query อยู่ในรูป snake_case (visitor_id, risk_score, min_risk_score) คีย์ภายในพจนานุกรม fields และ labels ของคุณเองถือเป็นข้อมูลของคุณและคงการสะกดเดิมไว้ ส่วน JavaScript SDK ยังคงอินเทอร์เฟซแบบ camelCase

การยืนยันตัวตน

ทุกคำขอต้องพา secret key ของคุณไปด้วยในรูปแบบ bearer token

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

Data API ใช้ได้เฉพาะแบบเซิร์ฟเวอร์ถึงเซิร์ฟเวอร์ ระบบจงใจไม่คืนเฮดเดอร์ CORS เบราว์เซอร์จึงเรียกมันไม่ได้ — นั่นคือสิ่งที่กัน secret key ของคุณออกจากโค้ดฝั่งไคลเอนต์ อย่าส่ง secret key ไปยังเบราว์เซอร์เด็ดขาด

การขอ secret key

สร้างได้ในแดชบอร์ดที่ API Keys โดยเลือกชนิด secret

• คีย์เต็ม ๆ จะถูกแสดงเพียงครั้งเดียวตอนสร้าง ฝั่งเราเก็บไว้เพียงค่าแฮช คีย์ที่หายไป จึงกู้คืนไม่ได้ — ให้หมุนเวียนคีย์ใหม่แทน
• secret key มีหน้าตาเป็น tracio_sk_ ตามด้วยอักขระอีก 43 ตัว รวมทั้งหมด 53 ตัว แดชบอร์ดจะแสดงรายการด้วยอักขระไม่กี่ตัวแรก คุณจึงแยกแยะคีย์ออกจากกันได้
• secret key ต้องใช้แพ็กเกจ Pro ขึ้นไป ส่วน public key ที่ agent ในเบราว์เซอร์ใช้นั้น เป็นค่าคนละตัว ไม่เป็นความลับ และยาว 40 อักขระ
• คีย์ผูกอยู่กับสภาพแวดล้อม: คีย์ production มองไม่เห็นผู้เข้าชมจาก staging — การตอบกลับจะเป็น 404 เหมือนกับข้อมูลที่ไม่มีอยู่จริงทุกประการ

การหมุนเวียน secret key

การหมุนเวียนจะออกคีย์ใหม่และให้คีย์เดิมใช้ได้ต่ออีก 7 วัน คุณจึงทยอยนำคีย์ใหม่ออกใช้ ได้โดยไม่มีช่วงหยุดทำงาน ให้ดีพลอยคีย์ใหม่ ยืนยันว่าทราฟฟิกย้ายไปแล้ว แล้วปล่อยให้คีย์เดิม หมดอายุไป ส่วน public key หมุนเวียนไม่ได้ — มันไม่ใช่ความลับและถูกออกแบบให้มองเห็นได้ใน ซอร์สของหน้าเว็บคุณอยู่แล้ว

ปลายทาง

คีย์และโฮสต์เดียวกันนี้ยังให้บริการ API การตัดสินใจด้วย ทั้งหมดอยู่ในรูป snake_case:

ผลลัพธ์ของ API เหล่านี้ยังมาถึงคุณในรูป เหตุการณ์ webhook ด้วย: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked และ affiliate_threshold_crossed

เครื่องหมายทับปิดท้ายเป็นที่ยอมรับและถูกละไว้ เส้นทางที่ไม่รู้จักหรือเมธอดที่ผิดจะคืนซอง ข้อผิดพลาด JSON แบบเดียวกับทุกกรณี ไม่เคยคืนเป็นหน้า HTML หรือข้อความล้วน

ช่วงเวลา

การอ่านทุกครั้งถูกจำกัดด้วยช่วงเวลา ซึ่งควบคุมด้วยพารามิเตอร์ query สองตัวที่ไม่บังคับ

• การใส่วันที่ล้วนเป็น to จะรวมทั้งวันนั้นเข้ามาด้วย
• ค่าอื่นใดนอกเหนือจากนี้จะถูกปฏิเสธด้วย 400 invalid_request พร้อมข้อความ time must be YYYY-MM-DD or RFC3339
• เมื่อคุณไม่ส่งทั้งสองค่า ช่วงเวลาจะเท่ากับระยะเวลาเก็บรักษาทั้งหมดของแพ็กเกจคุณ โดย สิ้นสุดที่ปัจจุบัน
• ช่วงเวลาที่ย้อนไปไกลกว่าที่แพ็กเกจของคุณอนุญาตจะถูกตัดให้พอดีอย่างเงียบ ๆ แทนที่จะ ถูกปฏิเสธ ช่วงเวลาที่ใช้จริงจะถูกรายงานกลับมาใน meta เสมอ ให้ตรวจ meta.from และ meta.to แทนที่จะสันนิษฐานว่าคำขอของคุณถูกใช้ตามตัวอักษร

ค้นหาผู้เข้าชม

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

การตอบกลับพาประวัติรวมมาให้และฝังเซสชันล่าสุดมาด้วย กรณีทั่วไปจึงใช้คำขอเดียวแทนที่จะ ต้องใช้สองคำขอ

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

ผู้เข้าชมที่ไม่มีข้อมูลอยู่ในช่วงเวลาเก็บรักษาจะคืน 404 not_found พร้อมข้อความ visitor not found in the retention window — นั่นไม่ใช่ข้อผิดพลาดในการผสานรวมของคุณ แต่หมายความว่าผู้เข้าชมรายนั้นเป็นรายใหม่หรือข้อมูลหมดอายุไปแล้ว

ฟิลด์คำตัดสิน

เซสชันพาคำตัดสินมาสองชุด และทั้งสองตอบคำถามคนละข้อ — ไคลเอนต์เป็นระบบอัตโนมัติหรือไม่ และเครื่องประเมินความเสี่ยงสรุปโดยรวมว่าอย่างไร

ทั้ง bot.score และ decision.risk_score อยู่บนสเกล 0..100 ตั้งแต่ Business ขึ้นไป guidance จะแปลงค่าเหล่านี้เป็นคำแนะนำรายสถานการณ์บนบันได allow → challenge → review → deny — ดูความหมายของแต่ละขั้นได้ที่ Guidance ค่าและสเกลตรงกับเนื้อหา webhook v3 ของการเข้าชมเดียวกัน และ guidance คำนวณด้วยกฎชุดเดียวกัน

แสดงรายการเซสชันของผู้เข้าชม

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

เซสชันจะกลับมาโดยเรียงจากใหม่สุดก่อน

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

การแบ่งหน้า

การแบ่งหน้าอิงเคอร์เซอร์ ไม่มีพารามิเตอร์ page หรือ offset ให้ส่ง next_cursor ที่ คุณได้รับกลับไปเป็น cursor แล้ววนต่อไปตราบที่ has_more ยังเป็นจริง หน้าสุดท้ายอาจไม่มี next_cursor มาเลย จึงอย่ากำหนดให้ฟิลด์นี้เป็นฟิลด์บังคับ

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
}

ให้ถือว่าเคอร์เซอร์เป็นค่าทึบ — เนื้อในของมันเป็นรายละเอียดการพัฒนาและอาจเปลี่ยนแปลงได้ เคอร์เซอร์ที่ถูกแก้ไขจะถูกปฏิเสธด้วย 400 invalid_request พร้อมข้อความ malformed cursor

ข้อเท็จจริงของอุปกรณ์

นอกเหนือจากเบราว์เซอร์และระบบปฏิบัติการที่ได้จาก User-Agent เซสชันยังบรรจุสิ่งที่เบราว์เซอร์ของผู้เข้าชมรายงานเกี่ยวกับตัวเครื่อง โดยผ่านการชำระข้อมูลฝั่งเราแล้ว ทุกฟิลด์จะไม่มีเมื่อการเข้าชมไม่ได้นำข้อมูลเช่นนั้นมา จึงควรถือว่าแต่ละฟิลด์เป็นทางเลือก

ส่วนขยายเบราว์เซอร์

extensions แสดงรายการส่วนขยายเบราว์เซอร์ที่ตรวจพบระหว่างการเข้าชม — มีตั้งแต่ Pro ขึ้นไป แต่ละรายการเป็นอ็อบเจ็กต์

สิ่งที่ตรวจพบจะถูกรายงานก็ต่อเมื่อผ่านการตรวจสอบความน่าเชื่อถือของเราแล้ว — สภาพแวดล้อมที่ตอบว่า "ติดตั้งแล้ว" กับทุกการตรวจสอบ หรือชุดผลลัพธ์ที่ยาวเกิน 12 ชื่อ จะถูกทิ้งเพราะเชื่อถือไม่ได้ ดังนั้นรายการที่ว่างเปล่าหรือไม่มีเลยจึงหมายถึง "ไม่มีสิ่งใดที่เรายืนยันได้" ไม่ใช่ "ไม่มีส่วนขยายติดตั้งอยู่" ให้อ่านมันในฐานะหลักฐาน ไม่ใช่ในฐานะบัญชีรายการ

ฟิลด์ที่กำหนดเอง

fields เก็บคู่คีย์-ค่าที่กำหนดเองซึ่งการผสานระบบของคุณแนบไว้กับการเข้าชม เช่น รหัสอ้างอิงคำสั่งซื้อ ชื่อแพ็กเกจ ผลการชำระเงิน คีย์และค่าเป็นสตริงเสมอ ตัวเลขหรือค่าบูลีนที่แนบไว้จะถูกส่งกลับในรูปข้อความ เช่นเดียวกับส่วนอื่นของเซสชัน ฟิลด์นี้ใช้ได้ในทุกแพ็กเกจที่เข้าถึง API ได้ (ตั้งแต่ Pro ขึ้นไป) และจะไม่มีอยู่เมื่อการเข้าชมไม่มีฟิลด์ใดเลย

fields ถูกอ่านแบบสดทุกครั้งที่มีคำขอ ไม่ได้คัดลอกไว้ตอนที่เกิดการเข้าชม ฟิลด์ที่แนบหลังการเข้าชม (ดู การแนบฟิลด์หลังการเข้าชม) จึงปรากฏที่นี่ด้วย ดังนั้นสำหรับการเข้าชมเดียวกัน fields อาจมีข้อมูลมากกว่าที่ Webhook ส่งมา

อย่าใส่ข้อมูลส่วนบุคคล เช่น ชื่อ ที่อยู่อีเมล หรือหมายเลขโทรศัพท์ ลงในฟิลด์ที่กำหนดเอง ให้แนบรหัสอ้างอิงที่ระบบของคุณเองสามารถค้นกลับได้แทน และส่งข้อมูลว่าบัญชีนั้นเป็นใครในรูปเรคคอร์ดบัญชี (ด้านล่าง)

เรคคอร์ดบัญชี

account คือเรคคอร์ดของคุณสำหรับบัญชีที่อยู่เบื้องหลังการเข้าชม — สิ่งที่คุณส่งมาล่าสุดสำหรับ account_id นั้นผ่าน POST /v2/accounts/metadata:

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

เรคคอร์ดถูกอ่านแบบสดทุกครั้งที่มีคำขอ การเปลี่ยนชื่อจึงปรากฏบนการเข้าชมเก่าด้วย: บล็อกนี้อธิบายบัญชีตามสภาพปัจจุบัน ไม่ใช่ตามสภาพตอนเกิดการเข้าชม ใช้ได้ในทุกแพ็กเกจที่เข้าถึง API ได้ (ตั้งแต่ Pro ขึ้นไป) ป้ายกำกับที่คุณส่งมาพร้อมเรคคอร์ดจะไม่ถูกส่งกลับ

บล็อกนี้จะไม่มีเมื่อการเข้าชมไม่มีบัญชีที่เชื่อมโยงไว้ เมื่อไม่มีเรคคอร์ดของบัญชีนั้น (หรือคุณล้างมันด้วยการส่งค่าว่าง) และ — ในบางโอกาส — เมื่ออ่านเรคคอร์ดไม่ได้: เซสชันยังคงถูกส่งกลับครบถ้วนแทนที่จะทำให้คำขอล้มเหลว จึงควรถือว่าบล็อกที่หายไปหมายถึง "ไม่ทราบ" ไม่ใช่ "บัญชีนี้ไม่มีอีเมล" Webhook ไม่ได้พาบล็อกนี้มาด้วย

ดึงเซสชันเดียว

รายการล่าสุด

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

คำขอนี้คืนอ็อบเจ็กต์เซสชันเปล่า ๆ ไม่ใช่อาร์เรย์ และไม่ได้ห่อไว้ในซองอื่น ผู้เข้าชมที่ไม่มี เซสชันในช่วงเวลานั้นจะคืน 404 not_found พร้อม no sessions for this visitor in the retention window

หรือค้นด้วย request_id ซึ่งเป็นตัวระบุที่ปรากฏในเพย์โหลดของ webhook ด้วย

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

ตรงนี้ visitor_id ไม่บังคับ แต่การส่งไปด้วยเมื่อคุณรู้ค่าจะทำให้การค้นหาเร็วขึ้นอย่าง เห็นได้ชัด

identification.drift_score — คะแนนพฤติกรรมที่ปรับให้เรียบแล้วซึ่งใช้ตัดสินเรื่องการยึดบัญชี สำหรับ Business ขึ้นไป — จะถูกส่งกลับเฉพาะจากการอ่านเซสชันเดียวนี้ การเบี่ยงเบนของพฤติกรรมถูกวัดระหว่างการเข้าชม หลังการระบุตัวตนครั้งแรก เส้นทางรายการและเซสชันล่าสุดจึงไม่มีค่านี้ การเข้าชมที่ไม่เคยถูกตัดสินพฤติกรรมเลยจะไม่มี drift_score ค่าเดียวกันนี้มาถึงคุณผ่าน webhook account_takeover ด้วย

คำตอบที่คุณได้สำหรับการเข้าชมที่ถูกแก้ไข

การเข้าชมหนึ่งครั้งอาจถูกส่งผ่าน webhook มากกว่าหนึ่งครั้ง: primary ก่อน แล้วตามด้วย late หรือ correction เมื่อสัญญาณที่ช้ากว่าและหลักฐานเชิงพฤติกรรมมาถึง — และเฟสที่มาทีหลังอาจกลับคำตัดสินก่อนหน้าได้ Data API ตอบจากเรคคอร์ด primary เฟสที่มาทีหลังจะไม่ถูกรวมกลับเข้าไป ดังนั้นสำหรับการเข้าชมที่ถูกแก้ไข webhook ฉบับสุดท้ายคือคำตอบที่ใหม่กว่า หากคุณดำเนินการหลังการเข้าชมไปแล้วหลายนาที ให้ยึดเฟสที่คุณได้รับล่าสุดมากกว่าการอ่านใหม่จากที่นี่

มีสิ่งหนึ่งที่ทำงานในทางกลับกัน: เมื่อตัวตรวจจับการยึดบัญชีทำงานสำหรับการเข้าชมหนึ่งแล้ว guidance ที่นี่จะสะท้อนผลนั้น ขณะที่เนื้อหา webhook identification ของการเข้าชมเดียวกันไม่ได้พาแกนนั้นมาด้วย — มันมากับการส่ง account_takeover โดยเฉพาะ

Velocity

Velocity ตอบคำถามว่า "ช่วงหลังนี้ผู้เข้าชมรายนี้ทำอะไรไปมากแค่ไหน" ซึ่งเป็นรูปแบบของการ ยิงชุดข้อมูลรับรอง การทดสอบบัตร และการสมัครสมาชิกจำนวนมาก

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

window รับค่า 1h, 24h หรือ 7d และมีค่าเริ่มต้นเป็น 24h ค่าอื่นใดจะถูกปฏิเสธด้วย 400 invalid_request พร้อม 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 นับจำนวนค่า linkedId ที่ต่างกันซึ่งคุณส่งมาให้อุปกรณ์เครื่องนี้ — ดู การเชื่อมโยงบัญชี ส่วน bot_events มีตั้งแต่ Business ขึ้นไป บน Pro จะไม่มีคีย์นี้

เมตาดาต้าบัญชี

TRACIO รู้จักบัญชีของคุณผ่าน ID ที่เว็บไซต์ของคุณส่งเป็น linkedId เท่านั้น — สตริงทึบอย่าง usr_8412 ส่งป้ายกำกับที่มนุษย์อ่านได้มาเพียงครั้งเดียว แล้วทุกหน้าจอของแดชบอร์ดที่แสดงบัญชีนั้นจะแสดงชื่อหรืออีเมลแทน ID ดิบ และอ็อบเจ็กต์เซสชันจะคืนค่าเหล่านี้ในบล็อก account ไม่มีสิ่งใดในส่วนนี้ส่งผลต่อการตรวจจับหรือการให้คะแนน มันเป็นเลเยอร์สำหรับการแสดงผล

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 }

• ที่นี่คือที่สำหรับข้อมูลส่วนบุคคลของบัญชี — ไม่ใช่ fields อีเมลหรือชื่อที่ส่งมาที่นี่จะอยู่เฉพาะในเรคคอร์ดบัญชีของ workspace คุณ: ไม่ถูกเก็บต่อการเข้าชม ไม่ถูกเขียนลงในหน้าเว็บ และการส่งครั้งเดียวจะอัปเดตทุกการเข้าชมของบัญชีนั้น
• ขอบเขตคือ workspace และสภาพแวดล้อมของคีย์ คีย์ staging จะไม่เขียนทับสิ่งที่คีย์ production เขียนไว้สำหรับ ID บัญชีเดียวกัน
• ทุกการส่งคือการเขียนทับทั้งหมด ไม่ใช่การแพตช์ ฟิลด์ที่คุณละไว้จะถูกเก็บเป็นค่าว่าง — ให้ส่งเรคคอร์ดที่ครบถ้วนทุกครั้ง นั่นก็คือวิธีล้างค่าด้วย
• ฟิลด์ที่ไม่รู้จักจะถูกปฏิเสธด้วย 400 invalid_request และรายการที่ผิดเพียงรายการเดียวจะทำให้ทั้งแบตช์ถูกปฏิเสธ — ข้อผิดพลาดจะระบุตำแหน่งของมัน ID บัญชีซ้ำกันในแบตช์เดียวไม่เป็นปัญหา: รายการสุดท้ายชนะ

ขีดจำกัด: 1000 บัญชีต่อคำขอ, เนื้อหา 1 MiB, account_id ≤ 256 อักขระ, email ≤ 320, display_name ≤ 256, ป้ายกำกับไม่เกิน 16 รายการ โดยคีย์ ≤ 64 และค่า ≤ 256 อักขระ

การแนบฟิลด์หลังการเข้าชม

เบราว์เซอร์ส่งได้เฉพาะสิ่งที่หน้าเว็บรู้ตอนเรนเดอร์ — รหัสคำสั่งซื้อได้ แต่ไม่มีทางส่งผลการตรวจสอบการชำระเงินหรือสิ่งอื่นที่ได้ข้อสรุปภายหลัง เส้นทางนี้เติมช่องว่างนั้น: ค้นหาการเข้าชมด้วยฟิลด์ที่มันมีอยู่แล้ว แล้วแนบฟิลด์เพิ่มให้มันจากฝั่งเซิร์ฟเวอร์

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 ค้นหาการเข้าชมด้วยฟิลด์ที่มันมีอยู่แล้ว ไม่ใช่ด้วย request_id ภายใน workspace และสภาพแวดล้อมของคีย์คุณ
• ช่วงเวลาค้นหาคือ 24 ชั่วโมง การเข้าชมที่เก่ากว่านั้นจะคืน 404 not_found — ให้เขียนฟิลด์ไม่นานหลังจากผลลัพธ์ได้ข้อสรุป
• updated นับจำนวนการเข้าชมที่ต่างกัน จะเกิน 1 ก็ต่อเมื่อ match ของคุณตรงกับการเข้าชมมากกว่าหนึ่งครั้ง — คู่คีย์/ค่าที่ไม่ได้เป็นเอกลักษณ์ของคำสั่งซื้อหรือตะกร้าเดียว match ที่ตรงกับเหตุการณ์มากกว่า 100 รายการจะถูกปฏิเสธด้วย 400 invalid_request แทนที่จะถูกนำไปใช้กับชุดย่อยตามอำเภอใจ
• ฟิลด์ที่เขียนที่นี่จะปรากฏในแดชบอร์ดพร้อมแท็ก server และมีลำดับความสำคัญเหนือค่าที่มีคีย์เดียวกันซึ่งเบราว์เซอร์เขียนไว้
• ไม่พบรายการที่ตรงกันคือ 404 not_found ไม่ใช่ 200 ที่ว่างเปล่า

ขีดจำกัดตรงกับช่องทางเบราว์เซอร์: 50 ฟิลด์ต่อการเรียก, คีย์ ≤ 40 ไบต์, ค่า ≤ 500 ไบต์ — ไบต์ ไม่ใช่อักขระ — ชุดอักขระของคีย์คือ A-Za-z0-9_.:-, เนื้อหา 1 MiB

การลบฟิลด์

ลบฟิลด์ที่กำหนดเอง — ไม่ลบตัวการเข้าชมเองเด็ดขาด ใช้กับค่าที่คุณไม่จำเป็นต้องแนบไว้กับการเข้าชมอีกต่อไป เช่น ยอดรวมของคำสั่งซื้อ Webhook ที่ส่งไปแล้วและการส่งออกที่ทำไปแล้วจะไม่เปลี่ยนแปลง

# 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 และ match ใช้ร่วมกันไม่ได้ — การส่งทั้งสองอย่าง หรือไม่ส่งเลย คือ 400 invalid_request ส่วน match ใช้ช่วงเวลา 24 ชั่วโมงและเพดาน 100 เหตุการณ์เดียวกับการแนบ
• deleted นับจำนวนฟิลด์ที่ถูกลบออกจากการเข้าชม (เมื่อใช้ request_id) หรือจำนวนการเข้าชมที่ฟิลด์ถูกลบออก (เมื่อใช้ match)
• การเรียกซ้ำเมื่อไม่เหลืออะไรแล้วจะคืน 404 not_found

ลิสต์ของ workspace

ลิสต์เดียวกับที่ผู้ปฏิบัติงานของคุณจัดการในแดชบอร์ด เข้าถึงได้จากระบบหลังบ้านของคุณเอง ชนิดของลิสต์คือการกระทำต่อการเข้าชมที่ตรงกัน — block, manual_review, challenge, allow — และโหมดของมันกำหนดว่าจะใช้การกระทำนั้นหรือไม่: observe แค่นับการตรงกัน ส่วน enforce นำการกระทำไปใช้กับ guidance (แกน list) ลิสต์และโหมดของลิสต์สร้างในแดชบอร์ด ส่วน Data API อ่านลิสต์และเพิ่มหรือนำรายการออก

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

นำรายการออกด้วยเนื้อหาเดียวกันที่ POST /v2/lists/{list_id}/entries/delete คำตอบคือ { "removed": true, "propagation": "immediate" }

• value_type คือสิ่งที่ใช้จับคู่ค่า: linked_id, visitor_id, device_id, ip, cidr หรือ country ค่าที่แยกวิเคราะห์ตามชนิดของมันไม่ได้คือ 400 invalid_request
• เมื่อมีหลายลิสต์ตรงกัน ชนิดที่เจาะจงที่สุดเป็นตัวตัดสิน — linked_id → visitor_id → device_id → ip → cidr → country — และภายในชนิดนั้น การกระทำที่เข้มงวดที่สุดชนะ
• ttl_minutes ไม่บังคับ หากละไว้ จะใช้ TTL เริ่มต้นของลิสต์ หากไม่มี รายการจะไม่มีวันหมดอายุ (expires_at เป็น null) การเพิ่มรายการซ้ำจะต่ออายุให้
• propagation บอกว่าการเปลี่ยนแปลงมีผลเมื่อไร: immediate หรือ ttl — ภายในประมาณห้านาที
• การลบค่าที่ไม่มีอยู่ คือ 200 พร้อม removed: false ส่วน 404 สงวนไว้สำหรับลิสต์ที่ไม่รู้จัก

ธรรมเนียมของการตอบกลับ

ฟิลด์ที่หายไปหมายถึง "ไม่มีข้อมูล" ไม่ใช่ศูนย์ ฟิลด์ที่ไม่มีค่าจะถูกตัดออกทั้งหมด แทนที่จะส่งมาเป็น 0, "" หรือ null ผู้เข้าชมที่เพิ่งมาใหม่เอี่ยมย่อมไม่มี match_confidence การเข้าชมที่สะอาดย่อมไม่มี antidetect_score หรือ suspect_score ข้อยกเว้นเดียวที่จงใจไว้คือ bot.score ซึ่งมีอยู่เสมอแม้ค่าจะเป็นศูนย์ ให้อ่านฟิลด์อย่าง ระมัดระวัง

เพย์โหลดขึ้นอยู่กับแพ็กเกจของคุณ การเข้าถึง API เริ่มที่ Pro และ Pro ได้เซสชันพื้นฐาน คือ ตัวระบุ timestamp URL IP user agent เบราว์เซอร์ OS อุปกรณ์ geo network bot identification และ decision — พร้อมด้วย identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields และ account ส่วน Business และ Enterprise เพิ่ม 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 และ environment ส่วนฟิลด์ระดับบุคคล (person_id, reputation, linked_accounts_count, linked_visitors_count) สงวนไว้สำหรับ Business และ Enterprise และจะปรากฏเมื่อเปิดใช้เลเยอร์บุคคลแล้ว — ปัจจุบันเลเยอร์นี้ทำงานในโหมดสังเกตการณ์ และฟิลด์เหล่านี้ยังไม่ถูกส่งออกมา การที่ฟิลด์ของ Business ไม่ปรากฏบนแพ็กเกจ Pro ไม่ใช่ข้อผิดพลาด

รายละเอียดภายในระดับสัญญาณจะไม่ถูกคืนกลับมาเลย ไม่ว่าจะแพ็กเกจใด ทั้งชื่อสัญญาณแต่ละ ตัว น้ำหนักของมัน เกณฑ์ที่อยู่เบื้องหลังคำตัดสิน ค่าดิบของสัญญาณ และการแจกแจงคะแนน ล้วน อยู่ฝั่งเราเท่านั้น คะแนนที่ถูกย้อนรอยกลับไปเป็นข้อมูลนำเข้าได้ ย่อมหมดประโยชน์ในฐานะ เครื่องป้องกัน

ข้อผิดพลาด

ความล้มเหลวทุกกรณีใช้ซองเดียวกัน

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

request_id ตัวนี้ไม่ใช่ตัวระบุการเข้าชม มีสองค่าที่ต่างกันแต่ใช้ชื่อเดียวกัน ภายใน เพย์โหลดของเซสชัน request_id คือ UUID ของการเข้าชม ค่าเดียวกับที่ webhook ส่งมา ส่วน ภายในซองข้อผิดพลาด มันคือตัวระบุการติดตามความยาว 24 อักขระที่สร้างขึ้นต่อหนึ่งการเรียก HTTP ตัวระบุการติดตามนี้ยังกลับมาในเฮดเดอร์ X-Request-Id ของทุกการตอบกลับ ไม่ว่าจะสำเร็จ หรือไม่ก็ตาม ให้แนบค่านี้มาด้วยเมื่อติดต่อฝ่ายสนับสนุน — เราใช้มันหาการเรียกของคุณได้ตรงตัว

การตรวจสอบทำงานตามลำดับที่ตายตัว — คีย์ก่อน แล้วแพ็กเกจ แล้วจึงขีดจำกัด คำขอที่ใช้คีย์ผิด จึงรายงานเรื่องคีย์ก่อนเสมอ ไม่เคยรายงานเป็นปัญหาโควตา ข้อมูลจาก workspace อื่นแยกไม่ออกจากข้อมูลที่ไม่มีอยู่จริง: จะได้ 404 ไม่ใช่ 403

401 สองกรณีอ่านต่างกันโดยตั้งใจ missing Authorization: Bearer <secret key> หมายความว่า เฮดเดอร์ไม่เคยมาถึง ส่วน invalid or revoked API key หมายความว่ามันมาถึงแล้วแต่ไม่ตรงกัน ส่วน 402 พา Data API requires the Pro plan or higher มาด้วย

ให้ลองใหม่สำหรับ 429 และ 503 โดยเว้นระยะรอให้นานขึ้นเรื่อย ๆ การลองใหม่กับ 4xx อื่นไม่มีประโยชน์ — มันหมายความว่าตัวคำขอเองต้องได้รับการแก้ไข

ขีดจำกัดอัตราและโควตา

การตอบกลับที่ระบบจดจำคีย์ได้แล้วจะพาสถานะปัจจุบันของคุณมาด้วย (การตอบกลับ 401 และ 402 ไม่มี และ Enterprise ซึ่งไม่มีโควตารายวันจะไม่ได้เฮดเดอร์โควตา)

• อนุญาตให้ยิงเป็นชุดสั้น ๆ ได้ ขีดจำกัดต่อวินาทีเป็นแบบ token bucket ที่ทนได้ถึงสามเท่า ของอัตราต่อเนื่องก่อนจะเริ่มปฏิเสธ
• คำขอที่ถูกปฏิเสธเพราะเกินอัตราต่อวินาทีไม่กินโควตารายวัน การยิงเป็นชุดจึงกินงบของทั้ง วันไปไม่ได้
• ขีดจำกัดของ Data API นับแยกจากทราฟฟิกการระบุตัวตน การอ่านประวัติของคุณเองไม่เคยใช้ โควตาการระบุตัวตนที่คุณจ่ายเงินซื้อไว้

ขั้นตอนถัดไป

• Webhooks — รับการระบุตัวตนแต่ละครั้งทันทีที่เกิดขึ้น
• การเชื่อมโยงบัญชี — ผูก id บัญชีของคุณเองเข้ากับอุปกรณ์
• การตรวจจับบอต — คำตัดสินเรื่องบอตเกิดขึ้นอย่างไร
• ความเป็นส่วนตัวและ GDPR — การจัดการคำร้องของเจ้าของข้อมูล