Fraud Prevention Data API

Data API, Web SDK'nın sunucu tarafı karşılığıdır. Kararları çekmek, istatistikleri toplamak ve raporlama ve mutabakat için veri dışa aktarmak üzere kullanın — kendi sistemlerinizin üzerinde mutabık kaldığı sayıları çekin.

Temel URL

https://apiv1.captcha.la

Kimlik doğrulama

Tüm Data API istekleri, başlık olarak gönderilen Fraud Prevention uygulama kimlik bilgilerinizle doğrulanır:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret yalnızca sunucu tarafıdır. Onu asla tarayıcılara, mobil uygulamalara veya genel depolara açığa çıkarmayın. Sayfa SDK'sı yalnızca herkese açık appKey değerini kullanır.

Uç noktalar

Bir karar getir

Tek bir ziyaretin kararını getirin (ör. belirli bir ziyareti mutabık kılmak için).

GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Yanıttaki data, bir BotVerdict nesnesidir:

{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}

Toplu istatistikler

Bir zaman aralığı boyunca kovalanmış sayımları çekin — toplamlar, bot payı ve action/level bazında dağılım — kontrol panelleri ve kalite raporları için.

GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}

Dışa aktarma

Çevrimdışı mutabakat için bir zaman aralığındaki ziyaret başına karar satırlarını dışa aktarın.

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Her satır, ziyaretin tanımlayıcısını, zaman damgasını ve karar alanlarını (is_bot, score, level, action) taşır; böylece bunu kendi günlüklerinizle birleştirebilirsiniz.

Tıklama başına mutabakat

Ücretli trafik senaryolarında, tek bir ziyaret belirli bir teslim edilmiş tıklamaya geri bağlanabilir; böylece iki taraf bunun üzerinde mutabık kalabilir. Bu, bir tıklama token'ı kullanır ve Reklam dolandırıcılığı kılavuzunda ele alınır.

Tıklama token'ı referansı (trafik sağlayıcıları için)

Bir trafik sağlayıcısı, kendi sunucusunda bir tıklama token'ı imzalar ve bunu hedef URL'ye ekler; böylece elde edilen ziyaretin kararı sağlayıcıya geri atfedilir. İmzalama çevrimdışı yapılır — herhangi bir API çağrısı gerekmez.

İmzalama kimlik bilgilerinizi alın

Panelde uygulamanızı açın → Fraud Prevention → İmzalama anahtarı oluştur. Şunları alırsınız:

• bot_kid — genel anahtar kimliğiniz (token'a pkid olarak girer).
• bot_hmac_secret — imzalama gizli anahtarınız, yalnızca bir kez gösterilir. Sunucu tarafında saklayın.

Token biçimi

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body, JSON yükünün base64url biçimidir; imza bu body dizesi üzerinden hesaplanır.

Yük alanları

alan	gerekli	açıklama
pkid	evet	bot_kid değeriniz; arka uç bunu gizli anahtarınızı bulmak ve imzayı doğrulamak için kullanır
cid	evet	bu tıklama için benzersiz kimlik; mutabakat anahtarı. Her tıklama için yeni ve benzersiz bir değer üretin
aud	hayır	hedef reklamverenin app_key değeri. Ayarlandığında token yalnızca o reklamverenin sayfasında kabul edilir. Herhangi bir reklamveren sayfasının kabul etmesi için boş bırakın
click_ts	hayır	tıklamanın gerçekleştiği unix saniye cinsinden zaman
exp	hayır	unix saniye cinsinden son kullanma zamanı; süresi dolmuş token'lar reddedilir

Bağlantıya ekleyin

Token'ı reklamverenin hedef URL'sine _ctk sorgu parametresi olarak ekleyin:

https://advertiser.example/lp?_ctk=ct.<...>.<...>

Reklamverenin SDK'sı _ctk değerini otomatik olarak okur (tokenParam ile yapılandırılabilir). Bir cid yalnızca bir kez talep edilebilir (tekrar saldırısına karşı korumalı). Bkz. Güvenlik modeli.

Örnek (sözde kod)

const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`

Sonraki adımlar

• Karar Referansı — bu uç noktaların döndürdüğü alanlar
• Web SDK — kararları sayfanızda toplayın