API Reference

API למניעת הונאות

SDK לדפדפן לזיהוי, webhooks חתומים לאירועים בזמן אמת ו-Server API לקריאה בלבד להיסטוריה. כל מה שאתם צריכים כדי לעצור הונאה ברמת המכשיר.

קבלו מפתח API API Playground

Endpoints

SDK@tracio/sdk

זהו מבקר בדפדפן באמצעות ה-SDK בצד הלקוח. מחזיר מזהה מבקר יציב והכרעת בוט ללא סבב שרת. בטוח לשלוח את המפתח הציבורי בקוד בצד הלקוח.

בקשה

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

תגובה

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

TRACIO מספקת אירוע חתום ל-endpoint שלכם בכל זיהוי. אמתו את כותרת X-Tracio-Signature, ואז פעלו לפי מטען ה-JSON השטוח. זהו משטח ה-push: אינכם צריכים לבצע polling. אם בכל זאת תצטרכו לקרוא ביקור בדיעבד, ה-Server API עונה לפי requestId.

בקשה

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

תגובה

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

משכו את מפתחות Ed25519 הציבוריים של הפלטפורמה המשמשים לאימות מסירות webhook. נתיב זה אינו דורש אימות ונשמר במטמון למשך חמש דקות. שדה ה-kid בכותרת החתימה מציין באיזה מפתח להשתמש.

בקשה

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

תגובה

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

GET/v1/visitors/{visitorId}

קראו את ההיסטוריה של מבקר מה-Server API באמצעות המפתח הסודי שלכם. זמין מתוכנית Pro. החלון מוגבל לפי התוכנית שלכם, והחלון שבאמת קיבלתם מדווח חזרה ב-meta. תומך בבקשות זכות-גישה לפי GDPR.

בקשה

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

תגובה

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

אימות

TRACIO משתמשת בשלושה אישורים, אחד לכל משטח: מפתח ציבורי ל-SDK בדפדפן, מפתח סודי (tracio_sk_…) הנשלח כ-Authorization: Bearer ל-Server API, וסוד חתימת HMAC לאימות מסירות webhook. המפתח הסודי נוצר בלוח הבקרה, מוצג פעם אחת, ואסור לו להגיע לדפדפן — ה-Server API במכוון אינו מחזיר כותרות CORS.

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

מגבלות קצב

המגבלות הן לכל workspace. קריאות Server API נספרות בנפרד מזיהויים, כך שקריאת ההיסטוריה שלכם לעולם אינה מבזבזת את המכסה שאתם משלמים עליה. כל תגובה נושאת את X-RateLimit-Limit, X-RateLimit-Remaining ו-X-RateLimit-Reset, ובנוסף Retry-After בשגיאת 429. ה-Server API אינו חלק מתוכנית Free.

תוכנית	קצב Server API	Server API ליום	נקודות קצה של webhook	חלון שאילתה
חינם	לא כלול	לא כלול	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	ללא הגבלה	100	365 days

קודי שגיאה

כל שגיאה מחזירה את אותה מעטפת: אובייקט error עם code מסוג מחרוזת, message קריא לבני אדם, ו-requestId של הקריאה שנכשלה.

400Bad Requestפרמטרי שאילתה שגויים, חלון שאינו נתמך, או מזהה שאינו מזהה מבקר תקין.

401Unauthorizedאישורים חסרים או לא תקינים — מפתח ציבורי (SDK), מפתח סודי (Server API) או חתימת webhook.

402Upgrade Requiredהתוכנית שלכם אינה כוללת גישה ל-Server API. הגישה מתחילה בתוכנית Pro.

404Not Foundאין מבקר או סשן עם המזהה הזה בתוך חלון השאילתה של התוכנית שלכם.

405Method Not Allowedה-Server API הוא לקריאה בלבד. כל נתיב עונה ל-GET ולשום דבר אחר.

429Rate Limitedיותר מדי בקשות לשנייה, או שהמכסה היומית נוצלה. בדקו את כותרת Retry-After ואת מגבלות התוכנית שלכם.

500Internal Errorשגיאת שרת. נסו שוב עם exponential backoff. אם הבעיה נמשכת, פנו לתמיכה עם ה-requestId.

503Service Unavailableה-API אינו יכול לענות באופן זמני. נסו שוב עם exponential backoff.

פורמט תגובת שגיאה

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

התחילו לבנות

קבלו את מפתח ה-API שלכם ובצעו את בקשת הזיהוי הראשונה שלכם בפחות מ-5 דקות.

קבלו מפתח API תיעוד API מלא