İmkânsız Seyahat Tespiti API Referansı

POST/v1/risk/check

Sağlanan bir IP'nin konumunu, kullanıcı başına saklanan bir referans noktasıyla karşılaştırır ve ima edilen seyahat hızını sınıflandırır. Kendi dolandırıcılık iş akışınız için ham bir sinyaldir, nihai bir karar değildir — entegre etmeden önce kullanılabilirliği doğrulamak için bizimle iletişime geçin; bağımsız risk planı zorlaması ve ödeme hazırlığı doğrulanmamıştır.

Kimlik doğrulama

Sorgulama endpoint'leriyle aynı anahtar türü olan Authorization: Bearer YOUR_SECRET_KEY üzerinden gizli bir anahtar sağlayın. userId, ip ve isteğe bağlı bir commit boolean'ı (varsayılan true; saklanan referans noktasını değiştirmemesi gereken bir deneme amaçlı kontrol için false ayarlayın) içeren bir JSON gövdesi gönderin.

Yanıt alanları

risk: low, medium veya high.
impossibleTravel: Önceki ve mevcut konum arasındaki ima edilen hızın makul bir seyahat hızını aşıp aşmadığının boolean kısaltması.
distanceKm, impliedSpeedKmh, elapsedSeconds: Önceki ve mevcut gözlem arasındaki mesafe ve süre ile bunun ima ettiği hız. Karşılaştırılacak önceki bir konum olmadığında, bir kullanıcının ilk kontrolünde null'dur.
previousLocation: Bu çağrıdan önceki saklanan referans noktası için country, latitude, longitude ve observedAt. Bu userId için ilk kontrol olduğunda null'dur.
currentLocation: Bu çağrıda sağladığınız ip için country, latitude ve longitude.

Hatalar

400: Hatalı biçimlendirilmiş IP adresi veya eksik userId.
401: Eksik veya geçersiz API anahtarı.
403: Gizli anahtar yerine yayınlanabilir bir anahtar kullanıldı.
422: Sağlanan IP bir konuma çözümlenemedi.
429: Geçerli bir dakikalık pencere için hız sınırı aşıldı.

Örnek

İstek

curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

Yanıt

{
  "risk": "high",
  "impossibleTravel": true,
  "distanceKm": 8843.2,
  "impliedSpeedKmh": 4421.6,
  "elapsedSeconds": 7200,
  "previousLocation": { "country": "FR", "latitude": 48.8566, "longitude": 2.3522, "observedAt": "2026-09-06T12:00:00.000Z" },
  "currentLocation": { "country": "US", "latitude": 30.2672, "longitude": -97.7431 }
}

Sınırlar

v1, kullanıcı başına yalnızca en son tek konumu saklar, bir geçmiş penceresi değil — henüz VPN/veri merkezi farkındalıklı bir bastırma olmadığından, hızlı VPN açıp kapatma veya mobil ağ IP değişiminden kaynaklanan yanlış pozitifler bekleyin. Sonucu nihai bir karar değil, ham bir sinyal olarak değerlendirin. Bu endpoint, tek bir istek/yanıt döngüsünün ötesinde userId'ye bağlı bir konumu sakladığından, onu kullanmak Watch-IP'yi sizin adınıza bu verinin bir işleyicisi (processor) yapar — Veri İşleme Sözleşmesi Eki'ne (DPA) bakın.