Watch-IP

Referensi API deteksi perjalanan mustahil

POST/v1/risk/check

Membandingkan lokasi dari sebuah IP yang dikirim dengan baseline per-pengguna yang tersimpan dan mengklasifikasikan kecepatan perjalanan yang tersirat. Sebuah sinyal mentah untuk alur kerja fraud Anda sendiri, bukan putusan akhir — hubungi kami untuk mengonfirmasi ketersediaan sebelum melakukan integrasi; penerapan paket-risiko independen dan kesiapan checkout belum diverifikasi.

Autentikasi

Sediakan secret key lewat Authorization: Bearer YOUR_SECRET_KEY, jenis key yang sama seperti endpoint pencarian. Kirim isi JSON berisi userId, ip, dan boolean commit opsional (default true; set false untuk pemeriksaan spekulatif yang tidak boleh mengubah baseline tersimpan).

Field respons

risk
low, medium, atau high.
impossibleTravel
Boolean singkat untuk menyatakan apakah kecepatan tersirat antara lokasi sebelumnya dan saat ini melampaui kecepatan perjalanan yang masuk akal.
distanceKm, impliedSpeedKmh, elapsedSeconds
Jarak dan waktu antara observasi sebelumnya dan saat ini, serta kecepatan yang tersirat darinya. Null pada pemeriksaan pertama seorang pengguna, saat belum ada lokasi sebelumnya untuk dibandingkan.
previousLocation
country, latitude, longitude, dan observedAt untuk baseline tersimpan sebelum panggilan ini. Null saat ini adalah pemeriksaan pertama untuk userId tersebut.
currentLocation
country, latitude, dan longitude untuk ip yang Anda kirim pada panggilan ini.

Error

400
Alamat IP salah bentuk atau userId hilang.
401
API key hilang atau tidak valid.
403
Publishable key digunakan, bukan secret key.
422
IP yang dikirim tidak bisa diselesaikan ke sebuah lokasi.
429
Rate limit terlampaui untuk jendela satu menit saat ini.

Contoh

Request

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

Respons

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

Batas

v1 hanya menyimpan satu lokasi paling terkini per pengguna, bukan jendela riwayat — perkirakan adanya positif palsu dari pergantian VPN yang cepat atau perputaran IP jaringan seluler, karena belum ada penekanan yang sadar VPN/datacenter. Perlakukan hasilnya sebagai sinyal mentah, bukan putusan akhir. Karena endpoint ini menyimpan lokasi yang terkait dengan userId melampaui satu siklus request/respons, menggunakannya menjadikan Watch-IP sebagai pemroses data tersebut atas nama Anda — lihat Adendum Pemrosesan Data (DPA).

Halaman terkait