İç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 geçmiş için salt okunur bir Server API. 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": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "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, push yüzeyidir: bunun için yoklama yapmanız gerekmez. Bir ziyareti sonradan okumanız gerekirse, Server API requestId ile yanıt verir.

İstek

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

Yanıt

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

Webhook iletimlerini doğrulamak için kullanılan platform Ed25519 genel anahtarlarını alın. Bu rota kimlik doğrulama gerektirmez ve beş dakika önbelleğe alınır. İmza başlığındaki kid, hangi anahtarı kullanacağınızı söyler.

İstek

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

Yanıt

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}
GET/v1/visitors/{visitorId}

Bir ziyaretçinin geçmişini gizli anahtarınızla Server API'den okuyun. Pro planından itibaren kullanılabilir. Pencere planınıza göre sınırlanır ve gerçekten aldığınız pencere meta içinde bildirilir. GDPR erişim hakkı taleplerini destekler.

İstek

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

Yanıt

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

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, Server API için Authorization: Bearer olarak gönderilen bir gizli anahtar (tracio_sk_…) ve webhook iletimlerini doğrulamak için bir HMAC imzalama gizli anahtarı. Gizli anahtar panoda oluşturulur, bir kez gösterilir ve asla bir tarayıcıya ulaşmamalıdır — Server API bilerek CORS başlığı döndürmez.

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

Hız Sınırları

Sınırlar çalışma alanı başınadır. Server API çağrıları tanımlamalardan ayrı sayılır, bu yüzden kendi geçmişinizi okumak ödediğiniz kotayı hiçbir zaman harcamaz. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını, 429 durumunda ayrıca Retry-After başlığını taşır. Server API, Free planına dahil değildir.

PlanServer API hızıGünlük Server APIWebhook uç noktalarıSorgu penceresi
ÜcretsizDahil değilDahil değil07 days
Pro10 req/s10,000530 days
Business50 req/s100,0002090 days
Enterprise200 req/sSınırsız100365 days

Hata Kodları

Her hata aynı zarfı döndürür: bir dize code, okunabilir bir message ve başarısız çağrının requestId değerini içeren bir error nesnesi.

400Hatalı İstekBozuk sorgu parametreleri, desteklenmeyen bir pencere veya geçerli bir ziyaretçi kimliği olmayan bir tanımlayıcı.
401YetkisizEksik veya geçersiz kimlik bilgileri — genel anahtar (SDK), gizli anahtar (Server API) veya webhook imzası.
402Yükseltme GerekliPlanınız Server API erişimini içermiyor. Pro planıyla başlar.
404BulunamadıPlanınızın sorgu penceresi içinde bu tanımlayıcıya sahip bir ziyaretçi veya oturum yok.
405Yönteme İzin VerilmiyorServer API salt okunurdur. Her rota yalnızca GET yanıtlar, başka hiçbir şeyi değil.
429Hız SınırlıSaniyede çok fazla istek ya da günlük kota tükendi. 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, requestId ile birlikte destekle iletişime geçin.
503Hizmet KullanılamıyorAPI geçici olarak yanıt veremiyor. Üstel geri çekilme ile yeniden deneyin.

Hata Yanıtı Formatı

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

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ı