> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> حلول لأخطاء KYT في Didit: تعارض txn_id، وعدم تفعيل القواعد، ومهلات فحص AML، وعدم تطابق توقيع webhook، مع الأسباب والإصلاحات.

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

## خطأ `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}/`](https://docs.didit.me/ar/management-api/transactions/get) باستخدام `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](https://docs.didit.me/ar/transaction-monitoring/travel-rule-sandbox.md)، وترسل webhook الحدث `travel_rule.status.updated` مع `environment: sandbox`. تُرجع `rule_runs` قائمة فارغة وتبقى الدرجة `0` مهما كان وضع قواعدك، وتبقى المعاملة في حالة `APPROVED` ما لم تُطبّق عملية تحويل Travel Rule عند انتهاء مهلة الانتظار قيمة `timeout_outcome` الخاصة بك. تحقق من `environment` في استجابة المعاملة: القيمة `"sandbox"` تعني أنها لم تُقيَّم أبداً. راجع [مراقبة المعاملات في البيئة التجريبية](https://docs.didit.me/ar/integration/sandbox-testing.md#مراقبة-المعاملات-في-البيئة-التجريبية) لمعرفة كيفية التحقق من القاعدة قبل تفعيلها.
* **وضع القاعدة هو `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](https://docs.didit.me/ar/getting-started/quick-start.md)، واشترك في webhook الخاص بالاكتمال.
* اضبط مهلة في نظامك لجعل المعاملات القديمة منتهية الصلاحية إذا لم تكتمل المعالجة أبدًا.

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

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

**الحل.**

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

راجع [تحديد المعدل](https://docs.didit.me/ar/integration/rate-limiting.md).

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

> [card] [دليل التكامل](https://docs.didit.me/ar/transaction-monitoring/integration-guide.md)
>
> أنماط التكامل الكاملة.

> [card] [القواعد](https://docs.didit.me/ar/transaction-monitoring/rules.md)
>
> كيف يعمل تقييم القواعد.

> [card] [Webhooks](https://docs.didit.me/ar/transaction-monitoring/webhooks.md)
>
> آلية webhook.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.