الانتقال إلى المحتوى الرئيسي
POST
curl

لماذا هو عديم الحالة

لا يكتب فحص المحافظ المستقل أي شيء في جدول المعاملات، لذلك لا يوجد سجل محفوظ تعرض منه endpoint هذه النتيجة. بدلًا من ذلك، تعيد إرسال نص JSON الدقيق الذي أعادته لك POST /v3/wallet-screening/، فيحوّل Didit هذه الحمولة إلى ملف PDF دون استدعاء مزوّد الخدمة مرة أخرى.

حقل report_signature

تتضمن كل استجابة من POST /v3/wallet-screening/ الآن حقل report_signature، وهو توقيع مبهم مرتبط بتطبيقك. تتحقق endpoint هذه من التوقيع قبل العرض، لذلك لا يستطيع المستدعي تعديل risk_score أو severity أو sanctions_hit أو أي حقل آخر والحصول على ملف PDF يحمل علامة Didit ويبدو سليمًا لنتيجة لم ينتجها Didit. أعد دائمًا إرسال نص الاستجابة الكامل دون تعديل، بما في ذلك report_signature. ترتيب المفاتيح مقبول، أما تغيير أي قيمة موقّعة فغير مقبول.

الفوترة

لا يتم أي استدعاء لمزوّد الخدمة ولا يُحتسب أي مبلغ. هذا الـ endpoint يعيد عرض نتيجة دفعت ثمنها بالفعل عند استدعاء POST /v3/wallet-screening/.

الأخطاء

الخطوات التالية

فحص المحفظة

نفّذ فحص المحفظة عند الطلب الذي تقوم عليه endpoint هذه، واحصل على نتيجة JSON لإعادة إرسالها هنا.

فحص المحافظ عند الطلب

نظرة عامة على endpoint فحص المحافظ المستقل ونموذج النتيجة.

التفويضات

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

كائن JSON غير المعدل الذي تم إرجاعه بواسطة POST /v3/wallet-screening/، بما في ذلك report_signature.

الشكل نفسه لاستجابة POST /v3/wallet-screening/ — قم بتمرير نص الاستجابة هذا حرفياً، بما في ذلك report_signature.

provider
string
مطلوب

المزود الذي أجرى الفحص (مثل merklescience، crystal).

screening_type
enum<string>
مطلوب

دائماً WALLET_SCREENING لهذا الـ endpoint.

الخيارات المتاحة:
WALLET_SCREENING
risk_score
integer
مطلوب

درجة مخاطر معيارية من 0 إلى 100. تعني القيمة الأعلى تعرضاً أكبر للجهات عالية المخاطر. تقيّم Merkle Science العنوان من 0 إلى 5، وهو ما يقابل 0 أو 15 أو 35 أو 55 أو 75 أو 95.

severity
enum<string>
مطلوب

فئة المخاطر المشتقة من risk_score: النطاق 0-9 هو UNKNOWN، و10-39 هو LOW، و40-69 هو MEDIUM، و70-89 هو HIGH، و90-100 هو CRITICAL. النطاق UNKNOWN هو أدنى فئة، وليس حالة مستقلة لعدم توفر البيانات: تعني قيمة risk_score البالغة 0 (الحالة الشائعة لعنوان سليم) عدم وجود تقييم سلبي، بينما تُعد الدرجة غير الصفرية في النطاق 1-9 إشارة حقيقية ولكنها أقل من مستوى LOW - اقرأ risk_score، وليس الفئة فقط. لا تعامل UNKNOWN أبداً على أنها تصنيف مؤكد لمخاطر منخفضة أو حالة خالية من المخاطر؛ ولا تعرضها كحالة اجتياز.

الخيارات المتاحة:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
status
enum<string>
مطلوب

حالة نتيجة الفحص.

الخيارات المتاحة:
SCREENED,
PENDING,
ERROR
summary
string
مطلوب

ملخص مقروء للبشر لنتيجة الفحص.

wallet_address
string
مطلوب

العنوان الذي تم فحصه، مع إعادته كما هو.

blockchain
string
مطلوب

البلوكتشين التي تم فحصها.

source_of_funds
object[]
مطلوب

الجهة التي استلم منها العنوان الأموال، منسوبة بحسب الكيان. كل إدخال يمثل تفصيلاً للتعرّض.

destination_of_funds
object[]
مطلوب

الجهة التي أرسل إليها العنوان الأموال، منسوبة بحسب الكيان. نفس هيكل عناصر source_of_funds مع exposure_direction = outgoing.

counterparty_connections
object[]
مطلوب

الكيانات التي ينسب إليها المزود العنوان المفحوص. بالنسبة لـ Merkle Science، تأتي هذه من علامات المالك والمستخدم الخاصة بالعنوان نفسه، لذا يمكن أن يظهر الكيان نفسه مرتين، ولا تحمل تدفقات أموال: الحقول received_usd وsent_usd وreceived_hops وsent_hops تكون null والنسبة percentage تكون 0. لا تعتمد في التوجيه على risk_level أو is_direct هنا: استخدم sanctions_hit وdominant_risk_category وrisk_factors[].is_high_risk للقرار، واستخدم exposure_type في source_of_funds/destination_of_funds لمعرفة مدى المباشرة.

sanctions_hit
boolean
مطلوب

تكون القيمة True إذا كان العنوان مرتبطاً بتعرّض مباشر أو غير مباشر للعقوبات.

dominant_risk_category
string | null
مطلوب

فئة المخاطر العالية ذات الوزن الأعلى، أو null عند عدم وجود فئة مهيمنة (مثل sanctioned أو mixer أو stolen_funds).

report_signature
string
مطلوب

توقيع HMAC-SHA256 مبهم لهذه النتيجة بالذات، ونطاقه محدد لتطبيقك. ليس له معنى بمفرده — أعد إرسال جسم الاستجابة بالكامل، دون تعديل وبما يشمل هذا الحقل، إلى POST /v3/wallet-screening/pdf/ لعرضه كملف PDF. يرفض الـ endpoint الخاص بـ PDF الطلب برمز 400 إذا كان report_signature مفقوداً أو إذا تم تعديل أي حقل موقّع (مثل risk_score، severity، sanctions_hit) قبل إعادة الإرسال.

transaction_hash
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

block_timestamp
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

total_value_usd
number | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

fee_usd
number | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

sender_rows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

receiver_rows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

transaction_flows
object[]

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون فارغاً في نتيجة فحص المحافظ.

transaction_flows_status
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

transaction_flows_error
string | null

حقل فحص المعاملات، مشترك مع هيكل النتيجة. دائماً ما يكون null في نتيجة فحص المحافظ.

network_nodes
object[]

عقد مخطط التعرض لفحص المعاملات. تكون فارغة في نتيجة فحص المحافظ.

network_edges
object[]

حواف مخطط التعرض لفحص المعاملات. تكون فارغة في نتيجة فحص المحافظ.

pep_counterparty
boolean | null

التعرض لشخص معرض سياسياً. تكون null عندما لا تتوفر أي نتيجة متعلقة بـ PEP، وهي كل النتائج اليوم لعدم وجود أي مزود يبلغ عن ذلك؛ وتكون false فقط عند وجود نتيجة فحص سلبية صريحة. لا تعتبر null بمثابة فحص PEP مكتمل.

risk_factors
object[]

تفسير مرتب لـ risk_score: ما أدى إلى هذا القرار. يقيّم المزودون العنوان بناءً على نموذجهم الخاص ويُرجعون قراراً فقط (تُرجع Merkle Science عدداً صحيحاً من 0 إلى 5)، وبالتالي فإن الدرجة وحدها لا تكفي لاتخاذ إجراء. مرتبة حسب مستوى المخاطر، بدءاً بالمخاطر الأعلى، ثم حسب القيمة المنقولة عبر كل محرك، بحد أقصى أقوى خمسة محركات؛ يحتوي كل من source_of_funds وdestination_of_funds دائماً على التفصيل الكامل. يعني وجود risk_score مرتفع دون إدخال is_high_risk أن المزود لم يُبلغ عن أي عقوبات أو تطابق مع كيان منسوب، وقام بتقييم العنوان بالكامل بناءً على نموذج التعرض الخاص به - يوضح summary ذلك صراحةً.

raw_response
object

الـ payload الخاص بالمزود نفسه. بنيته خاصة بالمزود ويمكن أن تتغير دون إشعار مسبق: اقرأ الحقول الموحدة بدلاً من تحليله برمجياً.

الاستجابة

مستند PDF المُصيَّر، يتم إرجاعه مباشرة كملف ثنائي application/pdf — لا يوجد غلاف JSON.

The response is of type file.

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