Server API

Server API, arka ucunuzun TRACIO'nun workspace'iniz için hâlihazırda topladığı kimlik tespiti verilerini okumasını sağlar: bir ziyaretçinin geçmişi, tekil oturumlar ve kısa pencereli velocity sayaçları.

Webhooks sayfasının yerini almaz, onu tamamlar:

Her iki yüzey de Pro planı ve üzerinde kullanılabilir.

Temel URL

https://api.tracio.ai/v1

Bu, tarayıcı uç noktasından (edge.tracio.ai) ve panelden (app.tracio.ai) farklı bir sunucudur. Üçü de ayrıdır: tarayıcı genel anahtarınızla edge ile, arka ucunuz ise gizli anahtarınızla Server API ile konuşur.

Kimlik doğrulama

Her istek gizli anahtarınızı bir bearer token olarak taşır:

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

Server API yalnızca sunucudan sunucuya kullanılır. CORS başlıkları bilinçli olarak döndürülmez; bu yüzden bir tarayıcı onu çağıramaz — gizli anahtarınızı istemci tarafı koddan uzak tutan da budur. Gizli anahtarı asla tarayıcıya göndermeyin.

Gizli anahtar edinme

Panelde API Keys altında, secret türünü seçerek oluşturun.

• Anahtarın tamamı, oluşturma sırasında tam olarak bir kez gösterilir. Bizim tarafımızda yalnızca bir hash saklanır; bu nedenle kaybolan bir anahtar kurtarılamaz — onun yerine rotasyona sokun.
• Gizli bir anahtar tracio_sk_ ve ardından 43 karakter, toplam 53 karakter biçimindedir. Panel, anahtarları birbirinden ayırabilmeniz için onu ilk birkaç karakteriyle listeler.
• Gizli anahtarlar Pro planı veya üzerini gerektirir; tarayıcı ajanının kullandığı genel anahtar ise ayrı, gizli olmayan, 40 karakterlik bir değerdir.

Gizli anahtar rotasyonu

Rotasyon yeni bir anahtar üretir ve eskisini 7 gün boyunca çalışır durumda tutar; böylece kesinti yaşamadan geçiş yapabilirsiniz. Yeni anahtarı yayına alın, trafiğin ona geçtiğini doğrulayın ve eskisinin süresinin dolmasını bekleyin. Genel anahtarlar rotasyona sokulamaz — bunlar gizli değildir ve tasarım gereği sayfanızın kaynağında görünürler.

Uç noktalar

Her rota bir GET'tir. Server API'de yazma işlemi yoktur: veriyi okur, yapılandırmanız ise panelde yaşar.

Sondaki eğik çizgi kabul edilir ve yok sayılır. Bilinmeyen bir yol ya da yanlış bir yöntem, her şeyde olduğu gibi aynı JSON hata zarfını döndürür; asla bir HTML veya düz metin sayfası değil.

Zaman penceresi

Her okuma, iki isteğe bağlı sorgu parametresiyle denetlenen bir zaman penceresiyle sınırlıdır:

• to olarak verilen yalın bir tarih o günün tamamını kapsar.
• Bunun dışındaki her şey 400 invalid_request ve time must be YYYY-MM-DD or RFC3339 mesajıyla reddedilir.
• Hiçbirini geçmediğinizde pencere, şimdi biten, planınızın tam saklama süresidir.
• Planınızın izin verdiğinden daha geriye uzanan bir pencere reddedilmek yerine sessizce kırpılır. Fiilen kullanılan pencere her zaman meta içinde bildirilir; bu yüzden isteğinizin harfi harfine karşılandığını varsaymak yerine meta.from ve meta.to alanlarını kontrol edin.

Bir ziyaretçiyi arama

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

Yanıt toplu geçmişi taşır ve en son oturumu gömer; böylece yaygın durum iki değil tek bir istek gerektirir:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "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",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Saklama penceresi içinde verisi bulunmayan bir ziyaretçi, visitor not found in the retention window mesajıyla 404 not_found döndürür — bu entegrasyonunuzdaki bir hata değildir; ziyaretçinin yeni olduğu ya da verisinin süresinin dolduğu anlamına gelir.

Karar alanları

Oturum iki karar taşır ve bunlar farklı sorulara yanıt verir — istemcinin otomatikleşmiş olup olmadığı ve risk motorunun genel olarak neye vardığı:

bot.score ve decision.riskScore değerlerinin ikisi de 0..100 aralığındadır. Business ve üzerinde guidance, bunları allow → challenge → review → deny merdiveni üzerinde senaryo başına önerilere çevirir — her basamağın ne anlama geldiği için Guidance bölümüne bakın.

Bir ziyaretçinin oturumlarını listeleme

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

Oturumlar en yeniden başlayarak döner:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Sayfalama

Sayfalama imleç tabanlıdır. page veya offset parametresi yoktur: aldığınız nextCursor değerini cursor olarak geri gönderin ve hasMore true olduğu sürece devam edin.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/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(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

İmleci opak kabul edin — içeriği bir uygulama ayrıntısıdır ve değişebilir. Düzenlenmiş bir imleç, 400 invalid_request ve malformed cursor mesajıyla reddedilir.

Tek bir oturumu getirme

En yenisi:

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

Bu, çıplak bir oturum nesnesi döndürür — bir dizi değil ve bir zarfa sarılmış da değil. Pencerede hiç oturumu olmayan bir ziyaretçi, no sessions for this visitor in the retention window ile 404 not_found döndürür.

Ya da webhook payload'ında da görünen tanımlayıcı olan requestId ile:

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

visitorId burada isteğe bağlıdır, ancak biliyorken göndermek aramayı belirgin biçimde hızlandırır.

Velocity

Velocity, "bu ziyaretçi son zamanlarda ne kadar iş yaptı" sorusuna yanıt verir — credential stuffing, kart deneme ve toplu kayıtların biçimi budur.

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

window, 1h, 24h veya 7d değerlerini kabul eder ve varsayılanı 24h'dir. Başka herhangi bir değer, 400 invalid_request ve window must be one of: 1h, 24h, 7d ile reddedilir.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts, bu cihaz için gönderdiğiniz farklı linkedId değerlerini sayar — bkz. Hesap eşleme. botEvents Business ve üzerindedir.

Yanıt kuralları

Eksik bir alan "veri yok" demektir, asla sıfır değil. Değeri olmayan alanlar 0, "" ya da null olarak gönderilmek yerine tamamen çıkarılır: yepyeni bir ziyaretçinin matchConfidence değeri, temiz bir ziyaretin de antidetectScore veya suspectScore değeri yoktur. Bilinçli tek istisna, sıfır olduğunda bile her zaman bulunan bot.score'dur. Alanları savunmacı biçimde okuyun.

Payload planınıza bağlıdır. API erişimi olan her plan temel oturumu alır — tanımlayıcılar, zaman damgası, URL, IP, user agent, tarayıcı, işletim sistemi, cihaz, coğrafi konum, ağ, bot, kimlik tespiti ve karar. Pro, identification.matchType, identification.matchConfidence ve bot.antidetectScore alanlarını ekler. Business ve Enterprise ise geo.isp, network.asn, decision.suspectScore, identification.driftScore, reasons, behavior, guidance, deviceInfo ve kişi düzeyindeki alanları (personId, reputation, linkedAccountsCount, linkedVisitorsCount) ekler. Pro planında bir Business alanının bulunmaması hata değildir.

Sinyal düzeyindeki iç ayrıntılar hiçbir planda döndürülmez: tekil sinyal adları, ağırlıkları, bir kararın ardındaki eşikler, ham sinyal değerleri ve skor dökümleri bizde kalır. Tersine mühendislikle girdilerine dönüştürülebilen bir skor, savunma olarak işlevini yitirir.

Hatalar

Her başarısızlık tek bir zarf kullanır:

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

Bu requestId, ziyaret tanımlayıcısı değildir. İki farklı değer aynı adı paylaşır: bir oturum payload'ının içinde requestId, webhook'un ilettiğiyle aynı olan ziyaretin UUID'sidir; bir hata zarfının içinde ise her HTTP çağrısı için üretilen 24 karakterlik bir izleme tanımlayıcısıdır. İzleme tanımlayıcısı ayrıca başarılı olsun olmasın her yanıtta X-Request-Id başlığında geri döner. Destek ekibiyle iletişime geçtiğinizde onu da ekleyin — tam olarak sizin çağrınızı böyle buluyoruz.

Kontroller sabit bir sırayla yapılır — önce anahtar, sonra plan, sonra limitler — bu yüzden hatalı anahtarla gelen bir istek her zaman önce anahtarı bildirir, asla bir kota sorununu değil.

İki 401 durumu bilinçli olarak farklı okunur: missing Authorization: Bearer <secret key> başlığın hiç gelmediği anlamına gelirken invalid or revoked API key başlığın geldiği ama eşleşmediği anlamına gelir. 402 ise Data API requires the Pro plan or higher mesajını taşır.

Hız sınırları ve kotalar

Kimliği doğrulanmış her yanıt mevcut durumunuzu taşır:

• Kısa patlamalara izin verilir: saniyelik limit, reddetmeye başlamadan önce sürdürülen hızın üç katına kadar tolerans gösteren bir token bucket'tır.
• Saniyelik hızı aştığı için reddedilen bir istek günlük kotayı tüketmez; bu yüzden bir patlama günün bütçesini yiyemez.
• Server API limitleri kimlik tespiti trafiğinden ayrı sayılır. Kendi geçmişinizi okumak, bedelini ödediğiniz kimlik tespitlerini asla harcamaz.

Sonraki Adımlar

• Webhooks — her kimlik tespitini gerçekleştiği anda alın
• Hesap eşleme — kendi hesap kimliğinizi bir cihaza iliştirin
• Bot Tespiti — bot kararının nasıl üretildiği
• Gizlilik ve GDPR — veri sahibi taleplerinin işlenmesi