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://verify.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). Tam olarak bir tanımlayıcı iletin: verdict_id (sayfanın aldığı karardan) veya cid (tıklama token'lı trafik için click id).

bash

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

found, bir kararın bulunup bulunmadığını belirtir. true olduğunda data, Karar Referansı'nda açıklanan karar alanlarını içerir:

json

{
  "found": true,
  "data": {
    "cid": null,
    "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "reasons": ["automation", "network"],
    "consistency": { "ok": false },
    "degraded": false,
    "created_at": "2026-06-25 00:00:00"
  }
}

Hiçbir şey eşleşmezse yanıt {"found": false} olur. Ne verdict_id ne de cid içeren bir istek HTTP 400 ile reddedilir.

TIP

Kararlar üretildikten birkaç saniye sonra saklanır; bu nedenle ziyaretten hemen sonra yapılan bir sorgu found: false döndürebilir. Bir ziyareti gerçek zamanlı kontrol etmek için bunun yerine Bir karar token'ını doğrula kullanın.

Bir karar token'ını doğrula

Sayfanızın Web SDK'dan aldığı bir verdict_token değerini kontrol edin. İçeriği sunucunuzda koşula bağlamak için kullanın (bkz. Sunucu tarafı doğrulama). Kontrol anında yanıtlanır ve saklanan verilere bağlı değildir.

bash

POST /v1/bot/verdict/verify
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "token": "vt1.eyJ2Ijoi...", "ip": "203.0.113.7", "consume": false }

Parametre	Zorunlu	Açıklama
`token`	evet	Karardaki `verdict_token`.
`ip`	hayır	Sunucunuzun gördüğü şekliyle ziyaretçinin IP adresi. Verildiğinde token, ziyaretle aynı ağdan gelmelidir. Önerilir.
`consume`	hayır	`true` = token yalnızca bir kez kullanılabilir; ikinci kontrol `already_used` döndürür. Varsayılan `false`: token süresi dolana kadar yeniden kontrol edilebilir.

json

{
  "valid": true,
  "error": null,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "expired": false,
  "expires_at": 1767225600,
  "ip_match": true,
  "verdict": {
    "is_bot": false,
    "level": "low",
    "action": "record_only",
    "score": 12,
    "degraded": false,
    "reasons": [],
    "issued_at": 1767225000
  }
}

Alan	Açıklama
`valid`	Token gerçek olduğunda, uygulamanıza ait olduğunda, süresi dolmadığında, `ip` ile eşleştiğinde (verildiyse) ve `consume` ile birlikte daha önce kullanılmadığında `true`. `valid` yalnızca token'ın gerçek olduğunu söyler. Ziyaretçinin insan olduğunu söylemez; bu yüzden `verdict` alanını da kontrol edin.
`error`	`null` veya token'ın neden geçerli olmadığı: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (tek seferlik kontrol tamamlanamadı; yeniden deneyin).
`expired` / `expires_at`	Süre dolma durumu ve süre dolma zamanı (Unix saniye).
`ip_match`	`ip` verildiğinde `true` / `false`, aksi halde `null`.
`verdict`	İmzalı karar: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. Token okunamadığında `null`.

Tipik bir geçit, valid true ve verdict.is_bot false olduğunda içeriği sunar. verdict.degraded değerini ve hiç token içermeyen istekleri nasıl ele alacağınıza siz karar verin. Hata durumunda açık bırakırsanız (fail open), kesinti sırasında gerçek ziyaretçiler yine geçer. Kapalı tutarsanız (fail closed), geçerli bir token olmadan hiçbir şey geçmez.

Token'ların süresi varsayılan olarak 10 dakika sonra dolar. Yenisini almak için SDK'yı yeniden çalıştırın (örneğin bir sonraki sayfa yüklemesinde).

Toplu istatistikler

Bir zaman aralığı boyunca sayımları çekin (toplamlar, botlar ve level ile güne göre dağılım), kontrol panelleri ve kalite raporları için.

bash

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

json

{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "cleaned": true,
  "total": 124500,
  "bots": 18230,
  "by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 },
  "by_day": [
    { "date": "2026-06-01", "total": 4100, "bots": 590 }
  ]
}

from / to varsayılan olarak son 7 gündür.

Dışa aktarma

Çevrimdışı mutabakat için bir zaman aralığındaki ziyaret başına karar satırlarını dışa aktarın. Satırlar en yeniden eskiye, sayfalar halinde döndürülür.

bash

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

Parametre	Açıklama
`from` / `to`	Tarih aralığı (`YYYY-MM-DD`). İsteğe bağlı.
`limit`	Sayfa başına satır, 1–5000 (varsayılan 1000).
`cursor`	Sonraki sayfayı almak için önceki sayfanın `next_cursor` değerini iletin.

json

{
  "rows": [
    {
      "id": 1042, "cid": null, "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
      "is_bot": false, "score": 12, "level": "low", "action": "record_only",
      "reasons": [], "consistency": { "ok": true }, "degraded": false,
      "created_at": "2026-06-25 00:00:00", "rescored": false
    }
  ],
  "next_cursor": 1042
}

Her satır, ziyaretin tanımlayıcılarını, zaman damgasını ve karar alanlarını taşır; böylece bunu kendi günlüklerinizle birleştirebilirsiniz. Son sayfada next_cursor null olur.

Temizlenmiş rakamlar

İstatistikler ve dışa aktarımlar varsayılan olarak temizlenmiş esasa göre raporlanır: daha sonra geçersiz olarak tespit edilen trafik sürekli yeniden değerlendirilir ve rakamlardan çıkarılır. Bu işlem eşzamansız gerçekleşir; bu nedenle çok yakın zaman aralıklarına ait rakamlar hâlâ biraz değişebilir. Temizlenmemiş rakamları görmek için ?raw=1 iletin; export içinde her satır ayrıca bir rescored bayrağı taşır.

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). Her cid tekrar saldırısına karşı korumalıdır: aynı ziyaretçinin sayfayı yeniden yüklemesi sorun değildir, ancak başka bir yerde yeniden kullanılan bir token işaretlenir. 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)}`

Postback (sunucudan sunucuya)

Data API'yi yoklamak yerine, kararların oluştukları anda kendi uç noktanıza gönderilmesini sağlayabilirsiniz — her ziyareti gerçek zamanlı olarak kaydetmek veya mutabakatını yapmak isteyen satış ortaklığı izleyicileri ve reklamveren arka uçları için kullanışlıdır.

Etkinleştirin

Panelde uygulamanızı açın → Fraud Prevention → Postback URL değerini ayarlayın (bot_postback_url). Ayarlandıktan sonra her karar, üretilmesinden kısa süre sonra bu URL'ye POST edilir. Teslimat eşzamansız ve yalıtılmıştır — yavaş veya hata veren bir uç nokta, sayfa SDK'sına zaten döndürülmüş kararı asla etkilemez.

Ne zaman tetiklenir

Uygulama için karar üreten her doğrulamada. Teslimat, birkaç otomatik yeniden denemeyle en iyi çaba esasına göre yapılır; bunu en az bir kez (at-least-once) olarak ele alın ve verdict_id üzerinden tekilleştirin.

İstek

POST <your bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>

Gövde (JSON):

json

{
  "cid": "CID_OF_THE_VISIT",
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "is_bot": 1,
  "score": 87,
  "level": "high",
  "action": "flag",
  "advertiser_app_id": 12,
  "provider_app_id": 34,
  "created_at": "2026-06-25 00:00:00"
}

alan	açıklama
`cid`	ziyaretin mutabakat anahtarı (tıklama token'ı yoksa `null` olabilir)
`verdict_id`	kararın kimliği; sayfanın aldığı değerle aynıdır
`is_bot`	`1` / `0`
`score`	risk puanı
`level`	`low` / `medium` / `high` / `critical`
`action`	sunucu tarafından belirlenen eylem (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	doğrulamanın çalıştırıldığı uygulamanın kimliği
`provider_app_id`	tıklama token'ı ile atfedildiğinde trafik sağlayıcısı kimliği, aksi halde `null`
`created_at`	karar zamanı (UTC)

İmzayı doğrulayın

X-Bot-Signature başlığı, isteğin gerçekten bizden geldiğini doğrulamanızı sağlar. Biçimi t=<unix_ts>,v=<hex> şeklindedir; burada:

hex = HMAC_SHA256( "<unix_ts>." + raw_request_body , bot_hmac_secret )

bot_hmac_secret, Fraud Prevention → İmzalama anahtarı oluştur altında oluşturduğunuz imzalama gizli anahtarının aynısıdır. Doğrulamak için aldığınız ham gövde üzerinden HMAC'i yeniden hesaplayın (JSON'u yeniden serileştirmeyin) ve sabit zamanlı karşılaştırın. İsteğe bağlı olarak, tekrar saldırısını sınırlamak için t değeri saatinizden çok uzak olan istekleri reddedin.

// Express example
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // "t=" prefix
const v  = vPart.slice(2)              // "v=" prefix
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody is the unparsed request body
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

Sonraki adımlar

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

Fraud Prevention Data API ​

Temel URL ​

Kimlik doğrulama ​

Uç noktalar ​

Bir karar getir ​

Bir karar token'ını doğrula ​

Toplu istatistikler ​

Dışa aktarma ​

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

İmzalama kimlik bilgilerinizi alın ​

Token biçimi ​

Yük alanları ​

Bağlantıya ekleyin ​

Örnek (sözde kod) ​

Postback (sunucudan sunucuya) ​

Etkinleştirin ​

Ne zaman tetiklenir ​

İstek ​

İmzayı doğrulayın ​

Sonraki adımlar ​

Fraud Prevention Data API

Temel URL

Kimlik doğrulama

Uç noktalar

Bir karar getir

Bir karar token'ını doğrula

Toplu istatistikler

Dışa aktarma

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

İmzalama kimlik bilgilerinizi alın

Token biçimi

Yük alanları

Bağlantıya ekleyin

Örnek (sözde kod)

Postback (sunucudan sunucuya)

Etkinleştirin

Ne zaman tetiklenir

İstek

İmzayı doğrulayın

Sonraki adımlar