مرجع واجهة برمجة كشف التنقل المستحيل

POST/v1/risk/check

تُقارن موقع عنوان IP المُقدَّم بخط أساس (baseline) مخزَّن لكل مستخدم، وتُصنِّف سرعة التنقل الضمنية. إشارة خام لسير عمل مكافحة الاحتيال الخاص بك، لا حكمًا نهائيًا — تواصل معنا لتأكيد الإتاحة قبل التكامل؛ فإنفاذ خطة المخاطر بشكل مستقل وجاهزية الدفع لم يُتحقق منهما بعد.

المصادقة

قدِّم مفتاحًا سريًا عبر Authorization: Bearer YOUR_SECRET_KEY، وهو نوع المفتاح نفسه المستخدم في نقاط نهاية البحث. أرسِل محتوى JSON يتضمن userId وip وقيمة منطقية اختيارية commit (القيمة الافتراضية true؛ اضبطها على false لفحص استكشافي لا ينبغي أن يُغيِّر خط الأساس المخزَّن).

حقول الاستجابة

risk: low أو medium أو high.
impossibleTravel: اختصار منطقي (Boolean) لما إذا كانت السرعة الضمنية بين الموقع السابق والحالي تتجاوز سرعة تنقل معقولة.
distanceKm, impliedSpeedKmh, elapsedSeconds: المسافة والزمن بين الرصدين السابق والحالي، والسرعة التي يُشير إليها ذلك. تكون null عند أول فحص للمستخدم على الإطلاق، عندما لا يوجد موقع سابق للمقارنة معه.
previousLocation: country وlatitude وlongitude وobservedAt لخط الأساس المخزَّن قبل هذا الاستدعاء. تكون null عندما يكون هذا أول فحص على الإطلاق لهذا الـ userId.
currentLocation: country وlatitude وlongitude لعنوان ip الذي قدَّمته في هذا الاستدعاء.

الأخطاء

400: عنوان IP غير صحيح التنسيق أو userId مفقود.
401: مفتاح API مفقود أو غير صالح.
403: تم استخدام مفتاح قابل للنشر بدلًا من مفتاح سري.
422: تعذر تحديد موقع لعنوان IP المُقدَّم.
429: تم تجاوز حد المعدل لنافذة الدقيقة الواحدة الحالية.

مثال

الطلب

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

الاستجابة

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

الحدود

يُخزِّن الإصدار v1 الموقع الأحدث فقط لكل مستخدم، لا نافذة سجل تاريخي — تُتوقع نتائج إيجابية كاذبة من التبديل السريع لشبكات VPN أو تغيّر عناوين IP لشبكات الجوال، إذ لا يوجد حتى الآن قمع (suppression) واعٍ لـ VPN/مراكز البيانات. تعامل مع النتيجة كإشارة خام، لا كحكم نهائي. ولأن هذه النقطة تُخزِّن موقعًا مرتبطًا بـ userId يتجاوز دورة طلب/استجابة واحدة، فإن استخدامها يجعل Watch-IP معالجًا (processor) لتلك البيانات نيابة عنك — راجع ملحق معالجة البيانات (Data Processing Addendum).