Data API

ה-Data API (שתועד כאן בעבר בשם Server API) מאפשר לשרת שלכם לקרוא את נתוני הזיהוי ש-TRACIO כבר אספה עבור ה-workspace שלכם: ההיסטוריה של מבקר, סשנים בודדים ומוני velocity על חלון קצר. כמה נתיבים גם כותבים — רשומות חשבון, שדות מותאמים אישית ורשומות ברשימות — כדי שהשרת שלכם יוכל להעשיר את מה ש-TRACIO יודעת.

הוא משלים את Webhooks ולא מחליף אותם:

שני המשטחים זמינים החל מתוכנית Pro ומעלה.

כתובת הבסיס

https://api.tracio.ai/v2

זהו מארח שונה מנקודת הקצה של הדפדפן (edge.tracio.ai) ומלוח הבקרה (app.tracio.ai). שלושתם נפרדים: הדפדפן מדבר עם ה-edge באמצעות המפתח הציבורי שלכם, והשרת שלכם מדבר עם ה-Data API באמצעות המפתח הסודי שלכם.

מעבר מ-v1

הנתיבים /v1 הוסרו. השתמשו ב-/v2: הנתיבים זהים, וכל מפתח JSON וכל פרמטר שאילתה כתובים ב-snake_case (visitor_id, risk_score, min_risk_score). המפתחות בתוך המילונים fields ו-labels שלכם הם הנתונים שלכם ושומרים על האיות המקורי שלהם. ה-SDK של JavaScript שומר על הממשק שלו ב-camelCase.

אימות

כל בקשה נושאת את המפתח הסודי שלכם כאסימון bearer:

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

ה-Data API מיועד לתקשורת שרת-לשרת בלבד. כותרות CORS אינן מוחזרות במכוון, ולכן דפדפן אינו יכול לקרוא לו — וזה מה ששומר את המפתח הסודי שלכם מחוץ לקוד צד-הלקוח. לעולם אל תשלחו את המפתח הסודי לדפדפן.

קבלת מפתח סודי

צרו אותו בלוח הבקרה תחת API Keys, ובחרו בסוג secret.

• המפתח המלא מוצג בדיוק פעם אחת, ביצירה. אצלנו נשמר רק hash שלו, ולכן מפתח שאבד אינו ניתן לשחזור — במקום זאת החליפו אותו.
• מפתח סודי נראה כך: tracio_sk_ ואחריו 43 תווים, 53 בסך הכול. לוח הבקרה מציג אותו לפי מספר התווים הראשונים שלו כדי שתוכלו להבחין בין מפתחות.
• מפתחות סודיים דורשים תוכנית Pro ומעלה; המפתח הציבורי שבו משתמש סוכן הדפדפן הוא ערך נפרד ולא סודי באורך 40 תווים.
• מפתח קשור לסביבה: מפתח ייצור אינו רואה מבקר מ-staging — התגובה היא 404, בדיוק כמו עבור נתונים שאינם קיימים.

החלפת מפתח סודי

החלפה מנפיקה מפתח חדש ומשאירה את הישן פעיל למשך 7 ימים, כך שתוכלו להטמיע אותו בלי זמן השבתה. פרסו את המפתח החדש, ודאו שהתעבורה עברה אליו ותנו לישן לפוג. מפתחות ציבוריים אינם ניתנים להחלפה — הם אינם סודות והם גלויים בקוד המקור של העמוד שלכם במכוון.

נקודות הקצה

אותו מפתח ואותו מארח משרתים גם את ממשקי ה-API להחלטות, כולם ב-snake_case:

התוצאות שלהם מגיעות אליכם גם כאירועי webhook: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked ו-affiliate_threshold_crossed.

לוכסן בסוף הנתיב מתקבל ומתעלמים ממנו. נתיב לא מוכר או מתודה שגויה מחזירים את אותה מעטפת שגיאת JSON כמו כל דבר אחר, לעולם לא עמוד HTML או טקסט פשוט.

החלון הזמני

כל קריאה תחומה בחלון זמן, שנשלט על ידי שני פרמטרי שאילתה אופציונליים:

• תאריך בלבד ב-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 הוא true. ייתכן שהעמוד האחרון לא יכלול את 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 ומעלה. כל רשומה היא אובייקט:

ממצא מדווח רק לאחר שעבר את בדיקות האמון שלנו — סביבה שמשיבה „מותקנת“ לכל בדיקה, או אצווה ארוכה מיותר משנים עשר שמות, נפסלת כבלתי אמינה. לכן רשימה ריקה או חסרה פירושה „לא הצלחנו לאשר דבר“, ולא „לא מותקנות הרחבות“. קראו אותה כראיה, לא כמצאי.

שדות מותאמים אישית

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 ומעלה). תוויות ששלחתם עם הרשומה אינן מוחזרות.

הבלוק נעדר כאשר לביקור אין חשבון מקושר, כאשר אין עבורו רשומה (או שניקיתם אותה בשליחת ערכים ריקים), ו — לעיתים רחוקות — כאשר לא ניתן היה לקרוא את הרשומה: הסשן עדיין מוחזר במלואו במקום שהבקשה תיכשל, לכן התייחסו לבלוק חסר כ„לא ידוע“, ולא כ„לחשבון הזה אין אימייל“. Webhooks אינם נושאים את הבלוק הזה.

שליפת סשן יחיד

העדכני ביותר:

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 עונה על השאלה „כמה המבקר הזה עשה לאחרונה“ — זו הצורה של credential stuffing, בדיקת כרטיסים והרשמות בכמות.

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 מכירה את החשבונות שלכם רק לפי המזהה שהאתר שלכם מעביר כ-linkedId — מחרוזת אטומה כמו usr_8412. שלחו את התוויות האנושיות פעם אחת, וכל מסך בלוח הבקרה שמציג את החשבון הזה יציג את השם או האימייל במקום המזהה הגולמי, ואובייקט הסשן יחזיר אותם בבלוק 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 לעולם אינו דורס את מה שמפתח ייצור כתב עבור אותו מזהה חשבון.
• כל שליחה היא דריסה מלאה, לא תיקון חלקי. שדות שהשמטתם נשמרים ריקים — שלחו את הרשומה המלאה בכל פעם. כך גם מנקים ערך.
• שדות לא מוכרים נדחים עם 400 invalid_request, ורשומה פגומה אחת דוחה את כל האצווה — השגיאה מציינת את מיקומה. מזהי חשבון כפולים באצווה אחת תקינים: האחרון מנצח.

מגבלות: 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.

מחיקת שדות

מוחק שדות מותאמים אישית — לעולם לא את הביקור עצמו. השתמשו בו עבור ערכים שאינכם צריכים עוד מצורפים לביקור, כמו סכום הזמנה. Webhooks שכבר נשלחו וייצואים שכבר בוצעו אינם משתנים.

# 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

אותן רשימות שהמפעילים שלכם מנהלים בלוח הבקרה, נגישות מה-back office שלכם. הסוג של רשימה הוא הפעולה שלה על ביקור תואם — 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 מקבלת את הסשן הבסיסי — מזהים, חותמת זמן, URL, IP, user agent, דפדפן, מערכת הפעלה, מכשיר, מיקום, רשת, בוט, זיהוי והכרעה — יחד עם 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 — קבלו כל זיהוי ברגע שהוא מתרחש
• קישור חשבונות — צרפו מזהה חשבון משלכם למכשיר
• זיהוי בוטים — כיצד מיוצרת ההכרעה בנוגע לבוט
• פרטיות ו-GDPR — טיפול בבקשות של נושאי מידע