استكشاف أخطاء مراقبة المعاملات (KYT) وإصلاحها في Didit

مرجع لأكثر مشكلات مراقبة المعاملات شيوعاً، مع الأعراض والسبب والحل.

​

خطأ txn_id المكرر

الأعراض. يُرجع إرسال معاملة الاستجابة 400 مع الرسالة A transaction with this transaction_id already exists. في حقل transaction_id، أو الاستجابة 409 عندما يتسابق طلبان متطابقان. السبب. قيمة txn_id (أي transaction_id الذي ترسله) فريدة لكل تطبيق. ترفض Didit معاملة ثانية بالقيمة transaction_id نفسها، ولا تُعيد السجل الموجود. الحل.

• ولّد txn_id بشكل حتمي من جهتك (مثلاً استخدم معرّف المعاملة في قاعدة بياناتك).
• عند تلقي 400 أو 409 بسبب transaction_id مكرر أثناء إعادة المحاولة، ابحث عن المعاملة الموجودة بدلاً من إعادة الإرسال: اقرأها عبر GET /v3/transactions/{uuid}/ باستخدام uuid من الاستجابة الأولى، أو استخدم transaction_id (وهو uuid الخاص بـ Didit) الذي يرسله webhook الحدث transaction.created بجانب txn_id الخاص بك.
• إذا لم يكن الطلب إعادة محاولة، فامنح المعاملة الجديدة transaction_id خاصاً بها.

​

القاعدة لا تُطلق

الأعراض. أنشأت قاعدة يفترض أن تتطابق، لكن لا تظهر أي معاملة فيها matched: true ضمن rule_runs[]. الأسباب والحلول.

• التطبيق في وضع البيئة التجريبية - تتجاوز بيئة التطبيق التجريبية تقييم القواعد، وفحص AML، والفوترة، وwebhook الحدثين transaction.created وtransaction.status.updated. تستمر عمليات تبادل Travel Rule عند تفعيلها، مع Didit Test VASP، وترسل webhook الحدث travel_rule.status.updated مع environment: sandbox. تُرجع rule_runs قائمة فارغة وتبقى الدرجة 0 مهما كان وضع قواعدك، وتبقى المعاملة في حالة APPROVED ما لم تُطبّق عملية تحويل Travel Rule عند انتهاء مهلة الانتظار قيمة timeout_outcome الخاصة بك. تحقق من environment في استجابة المعاملة: القيمة "sandbox" تعني أنها لم تُقيَّم أبداً. راجع مراقبة المعاملات في البيئة التجريبية لمعرفة كيفية التحقق من القاعدة قبل تفعيلها.
• وضع القاعدة هو DISABLED أو TEST - تحقق من Rules → [rule] → Mode. تُسهم القواعد ACTIVE فقط في الاحتساب؛ القواعد TEST تُقيَّم لكنها لا تؤثر في الحالة.
• تصفية النطاق تستثني المعاملة - مثلاً، إذا ضُبط النطاق على transaction_type = finance فلن تتطابق مع معاملات travelRule.
• نافذة التجميع أقصر مما يلزم - لن تتطابق قاعدة “20 معاملة خلال 30 يوماً” بعد 15 معاملة فقط.
• قيمة حقل الشرط هي null - مثلاً، تتحقق قاعدتك من counterparty.country_code لكنك لم ترسل طرفاً مقابلاً.
• تحويل العملة - تعتمد القاعدة على الحدود في amount_in_default_currency؛ إذا اختلفت العملة الافتراضية لتطبيقك عن عملة المعاملة، فقد يقع المبلغ المحوّل دون الحد.

استخدم ميزة Rules → [rule] → Backtest لإعادة تشغيل معاملة سابقة ومعرفة سبب إطلاق القاعدة أو عدم إطلاقها.

​

القاعدة تُطلق على كل شيء

الأعراض. تُطلق القاعدة على 90% أو أكثر من المعاملات، فتغمر قائمة المراجعة لديك. السبب. الشروط واسعة جداً، أو الحدود منخفضة جداً. الحل.

• أضف عمليات تصفية scope لتضييق نطاق التطبيق (مثلاً الحوالات الصادرة فقط، أو أنواع معاملات محددة).
• ارفع الحدود (المبالغ وعدد المعاملات خلال فترة).
• ضع القاعدة في وضع TEST لمدة أسبوع، وحلّل rule_runs لمعرفة معدل التطابق، وشدّد الشروط قبل إعادة تفعيلها.

​

انتهت مهلة فحص العملات المشفرة

الأعراض. اكتملت المعاملة بالحالة status: APPROVED، لكن المصفوفة provider_results[] تُظهر status: FAILED لمحفظة أو تجزئة معاملة أو مزوّد فحص عملات مشفرة. الأسباب.

• توقفت واجهة برمجة تطبيقات المزوّد لفترة وجيزة.
• انتهت مهلة الاستعلام (عادةً نحو 10 ثوانٍ).

الحل.

• لا تفشل المعاملات بسبب مشكلات المزوّدين، فالإثراء يعمل على أساس أفضل جهد.
• إذا فشل مزوّد بعينه مراراً، فتحقق من صفحة حالته أو افتح تذكرة دعم.
• فكّر في ضبط تفضيلات المزوّدين في Settings → Transaction Monitoring → Providers لتوجيه الطلبات إلى مزوّدين بديلين.

​

بيانات إثراء IP مفقودة

الأعراض. إما أن applicant.ip_enrichment للمعاملة غائب أو جزئي. الأسباب.

• لا يوجد applicant.device.ip في الإرسال.
• عنوان IP خاص أو محجوز (غير قابل للتوجيه).
• كان جميع مزوّدي الإثراء غير متاحين مؤقتاً.

الحل.

• اجمع عنوان IP للمرسل في عميلك أو خادمك، ومرّره مع كل معاملة.
• استخدم عناوين IP القابلة للتوجيه فقط، فتتجاهل Didit النطاقات الخاصة دون إشعار.
• تحقق من حالة المزوّدين في Settings → Status داخل الواجهة.

​

عدم تطابق توقيع webhook

الأعراض. يرفض نقطة الاستقبال لديك الأحداث لأن التوقيع لا يتطابق. الأسباب.

• تغيّر الجسم الخام للطلب (أُعيدت تسلسل JSON بمسافات بيضاء مختلفة).
• سر خاطئ.
• وجود وجهات متعددة بالعنوان نفسه؛ فالتواقيع تختلف من وجهة إلى أخرى.

الحل.

• وقّع على الجسم الخام للطلب، وليس على JSON المحلل. تُتيح كثير من الأطر وسيطاً للوصول إلى الجسم الخام.
• بدّل السر إذا تعرّض للاختراق: Webhook destinations → [destination] → Rotate secret.
• احتفظ بوجهة واحدة لكل عنوان URL لتجنب الالتباس في الأسرار.

​

webhook لا يصل

الأعراض. تُنشأ المعاملات، لكن لا يصل أي webhook. الأسباب.

• قيمة enabled للوجهة هي false.
• عنوان URL غير متاح للوصول من الإنترنت العام.
• عُطّلت الوجهة تلقائياً بعد إخفاقات متكررة.
• الحدث غير موجود في subscribed_events.

الحل.

• أرسل حدثاً تجريبياً: Webhook destinations → [destination] → Send test.
• تحقق من عمليات التسليم الأخيرة: Webhooks → [destination] → Deliveries. راجع الاستجابات 4xx و5xx مع الجسم والرؤوس.
• أعد تفعيل الوجهات المعطّلة.

​

يبدو تحويل العملة غير صحيح

الأعراض. لا يطابق amount_in_default_currency السعر الذي تتوقعه. الأسباب.

• سعر الصرف هو سعر السوق المتوسط عند txn_date.
• تستخدم المعاملات المؤرخة بأثر رجعي سعر الصرف التاريخي في ذلك التاريخ.
• تتمتع بعض العملات (العملات الأجنبية النادرة) بفترات تحديث أطول.

الحل.

• استخدم amount وcurrency (العملة الأصلية) للعرض.
• استخدم amount_in_default_currency فقط لتطبيق حدود القواعد داخلياً.
• لأغراض التدقيق، يحفظ سجل المعاملة سعر التحويل المستخدم وقت التقييم.

​

عدم تطابق الطرف المقابل مع قائمة الحظر لديّ

الأعراض. أدرجت شركة في قائمة الحظر باستخدام vendor_data، لكن معاملة مع هذا الطرف المقابل تمت مع ذلك. الأسباب.

• الطرف المقابل في حمولة المعاملة لا يحتوي على vendor_data، وقد خُزّن كلقطة خارجية.
• حالة الأحرف في vendor_data مختلفة.

الحل.

• مرّر دائمًا counterparty.vendor_data عندما يكون الطرف المقابل كيانًا على منصتك.
• استخدم حالة الأحرف نفسها في كل مكان، فـ vendor_data حساس لحالة الأحرف.

​

المعاملات العالقة في AWAITING_USER

الأعراض. المعاملات عالقة في AWAITING_USER لأن المستخدم لا يُكمل جلسة المعالجة أبدًا. الأسباب.

• لم يفتح المستخدم رابط جلسة المعالجة.
• انتهت صلاحية جلسة المعالجة.
• المعاملة تحويل Travel Rule، وقد نقلتها قاعدة من المكتبة مثل travel-rule-pending-action إلى AWAITING_USER. لا تنشئ Didit جلسة المعالجة الافتراضية لمعاملة Travel Rule، لذلك ما لم تسمِّ القاعدة سير عمل المعالجة الخاص بها فلا يوجد رابط لإرساله.

الحل.

• الرابط الذي يُرسَل هو remediation_session_url في استجابة المعاملة. أعد إرساله إلى المستخدم.
• بالنسبة لمعاملة Travel Rule، حُلّ التحويل من علامة التبويب Travel rule، ثم غيّر حالة المعاملة بنفسك، لأن حلّ التحويل لا ينقل المعاملة وحدَه خارج AWAITING_USER.
• تتبع جلسات المعالجة النمط نفسه في البدء السريع لـ KYC، واشترك في webhook الخاص بالاكتمال.
• اضبط مهلة في نظامك لجعل المعاملات القديمة منتهية الصلاحية إذا لم تكتمل المعالجة أبدًا.

​

حد المعدل عند الإنشاء

الأعراض. يظهر الخطأ 429 Too Many Requests أثناء فترات الارتفاع المفاجئ في حجم الطلبات. الحل.

• التزم بالرأس Retry-After.
• قيّد معدل الطلبات من جهة العميل أثناء فترات الارتفاع المفاجئ في حجم الطلبات.
• تواصل مع الدعم للحصول على حدود أعلى بناءً على حجم إنتاج مثبت.

راجع تحديد المعدل.

​

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