İçeriğe geç

API Referansı

Dolandırıcılık Önleme API'si

Tanımlama için bir tarayıcı SDK'sı, gerçek zamanlı olaylar için imzalı webhook'lar ve bir çalışma alanı yönetim API'si. Dolandırıcılığı cihaz düzeyinde durdurmak için ihtiyacınız olan her şey.

API Anahtarı AlınAPI Playground

Uç Noktalar

SDK@tracio/sdk

İstemci SDK'sı ile tarayıcıda bir ziyaretçiyi tanımlayın. Sunucuya gidiş dönüş olmadan kararlı bir ziyaretçi kimliği ve bot kararı döndürür. Genel anahtarın istemci tarafı kodda gönderilmesi güvenlidir.

İstek

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

Yanıt

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}
POST/webhook/tracio

TRACIO, her tanımlamada uç noktanıza imzalı bir olay iletir. X-Tracio-Signature başlığını doğrulayın, ardından düz JSON yükü üzerinde harekete geçin. Bu, sunucu tarafı olay yüzeyidir — requestId ile yoklama yapan bir REST okuması yoktur.

İstek

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Yanıt

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}
POST/api/v1/workspaces/{workspaceId}/webhooks

Çalışma alanı yönetim API'si aracılığıyla bir webhook uç noktası kaydedin. Pano oturumu (Clerk) JWT'nizle kimlik doğrulanır ve çalışma alanı rolünüze göre kontrol edilir. İmzalama gizli anahtarı oluşturma sırasında bir kez döndürülür.

İstek

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

Yanıt

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}
GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

Çalışma alanı yönetim API'si aracılığıyla, pano oturumu (Clerk) JWT'nizle kimlik doğrulanarak bir ziyaretçinin saklanan geçmişini sorgulayın. GDPR erişim hakkı taleplerini destekler.

İstek

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

Yanıt

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

Kimlik Doğrulama

TRACIO, her yüzey için birer tane olmak üzere üç kimlik bilgisi kullanır: tarayıcı SDK'sı için bir genel anahtar, çalışma alanı yönetim API'si için pano oturumu (Clerk) JWT'niz ve webhook iletimlerini doğrulamak için bir HMAC imzalama gizli anahtarı. Bağımsız bir API gizli anahtarı yoktur.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

Hız Sınırları

Sınırlar çalışma alanı başınadır. Yönetim API'si yanıtları X-RateLimit-Limit, X-RateLimit-Remaining ve Retry-After başlıklarını içerir.

PlanTanımlamalarWebhook olaylarıYönetim API'siZiyaretçi sorguları
Ücretsiz100/day100/day50/day100/day
Pro1,000/min1,000/min500/min1,000/min
Enterprise10,000/min10,000/min5,000/min10,000/min

Hata Kodları

Tüm hatalar code, message ve details alanlarını içeren bir JSON gövdesi döndürür.

400Hatalı İstekBozuk istek gövdesi veya eksik zorunlu alanlar.
401YetkisizEksik veya geçersiz kimlik bilgileri — genel anahtar (SDK), Clerk JWT (yönetim API'si) veya webhook imzası.
403YasakÇalışma alanı rolünüz (RBAC) bu işlem için izne sahip değil.
404BulunamadıZiyaretçi kimliği veya webhook çalışma alanınızda bulunamadı.
429Hız SınırlıÇok fazla istek. Retry-After başlığını ve plan sınırlarınızı kontrol edin.
500Dahili HataSunucu hatası. Üstel geri çekilme ile yeniden deneyin. Devam ederse, destek ile iletişime geçin.

Hata Yanıtı Formatı

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

Geliştirmeye Başlayın

API anahtarınızı alın ve ilk tanımlama isteğinizi 5 dakikadan kısa sürede yapın.

API Anahtarı AlınTam API Dokümanları