الانتقال إلى المحتوى الرئيسي
POST
curl
Use POST /v3/ip/risk/ عندما يكون لدى الخادم الخلفي عنوان IP بالفعل ويحتاج إلى قرار مخاطر من الخادم إلى الخادم. تتضمن الاستجابة تحديد الموقع الجغرافي، وملكية الشبكة، ومؤشرات VPN/Tor ومراكز البيانات، وبيانات التهديدات، وcountry_mismatch عندما ترسل دولة مُدّعاة.

تفسير الاستجابة

  • تكون قيمة status هي In Review عندما تتعارض الدولة المحددة مع claimed_country، أو عندما يرتبط العنوان ببنية تحتية لـ VPN أو Tor أو مراكز البيانات. وفي غير ذلك تكون Approved.
  • يحتوي ip.ip_country_code على رمز الدولة المحددة. قارن الدول عبر ip.country_mismatch بدلاً من مقارنة أسماء الدول الخام بنفسك.
  • يمثل ip.latitude وip.longitude تحديداً جغرافياً تقريبياً للشبكة، وليس موقعاً دقيقاً للجهاز.
  • ip.is_vpn_or_tor وip.is_data_center وip.proxy_type وip.threat تحمل أدلة على مخاطر الشبكة.
  • ip.asn_number وip.asn_organization وip.connection_type وip.carrier تصف الشبكة التي ينتمي إليها العنوان.
  • request_id هو معرّف جلسة API. خزّنه مع vendor_data إذا احتجت إلى ربط النتيجة بعمليات webhook لاحقة أو بنشاط لوحة التحكم.
الإثراء بالبيانات يتم بأفضل جهد ممكن. إذا لم يُرجع أي مصدر إثراء بيانات قابلة للاستخدام، تعيد endpoint استجابة مقبولة تتضمن ip.ip_address: null وip.country_mismatch: null وكائن ip.threat فارغاً. قد تكون حقول الإثراء الفردية أيضاً null عندما تكون غير متاحة.

استخبارات الجهاز

واجهة IP Risk API هي endpoint من الخادم إلى الخادم فقط. أما تحديد بصمة الجهاز فليس كذلك، لأن الخادم الخلفي لا يستطيع رصد إشارات المتصفح أو الجهاز بمفرده. بالنسبة إلى جلسات التدفق المستضاف وجلسات SDK، تعرض Didit حقول الجهاز التي جُمعت مسبقاً في استجابة الجلسة، ومنها device_fingerprint وتفاصيل الجهاز والمتصفح وuser_agent والبيانات الخام للجهاز والتطابقات عبر الجلسات.

سلوك البيئة التجريبية

تتحقق مفاتيح البيئة التجريبية من الطلب وتعيد بيانات مقبولة حتمية. لا تتصل هذه المفاتيح بخدمات الاستخبارات الخارجية، ولا تستهلك الرصيد، ولا تنشئ جلسة، ولا تساهم في Networks.

الفوترة

تبلغ تكلفة استدعاءات IP Risk API ‏$0.02 بحسب سعر القائمة. يصبح الطلب الفعلي قابلاً للفوترة بمجرد بدء البحث.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json
ip_address
string<ip>
مطلوب

عنوان IPv4 أو IPv6 لاحتساب درجته.

مثال:

"8.8.8.8"

claimed_country
string

دولة اختيارية وفق معيار ISO 3166-1 alpha-2 أو alpha-3 يدّعيها المستخدم أو الجلسة. تُستخدم لحساب country_mismatch.

Maximum string length: 3
مثال:

"ESP"

user_agent
string

وكيل المستخدم الذي رصدته الواجهة الخلفية لديك. يتم تخزينه كسياق للطلب؛ ولا يوفر بصمة للجهاز.

Maximum string length: 512
vendor_data
string

مرجعك الثابت لهذا الطلب. يتم تخزينه في جلسة API وإعادته في الاستجابة.

metadata
object | null

البيانات الوصفية بتنسيق JSON غير الحساسة الخاصة بك. يتم تخزينها في جلسة API وإعادتها في الاستجابة.

الاستجابة

اكتمل تقييم المخاطر. افحص status لمعرفة القرار؛ رمز HTTP دائماً ما يكون 200 لعمليات البحث المكتملة.

request_id
string<uuid>
مطلوب

معرّف جلسة API التي تم إنشاؤها لهذا الطلب. احفظه مع vendor_data إذا كنت بحاجة إلى ربط النتيجة بـ webhooks اللاحقة أو نشاط لوحة التحكم.

status
enum<string>
مطلوب

القرار لجلسة API هذه: In Review عند وجود مخاطر تتعلق بالشبكة أو عدم تطابق الدولة، وإلا فـ Approved.

الخيارات المتاحة:
Approved,
In Review
created_at
string<date-time>
مطلوب

الطابع الزمني لهذه الاستجابة.

vendor_data
string | null

نسخة مطابقة من vendor_data التي أرسلتها، وتكون null عند عدم إرسال أي منها.

metadata
object | null

نسخة مطابقة من metadata التي أرسلتها، وتكون null عند عدم إرسال أي منها.

ip
object

نتيجة مخاطر عنوان IP. قد تكون حقول الإثراء الفردية null عندما لا يُرجع البحث أي بيانات قابلة للاستخدام.

آخر تعديل في ٧ نوفمبر ٢٠٢٦