> ## 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) وMCP

> أنشئ القواعد وعدّلها واختبرها تاريخياً وانقلها برمجياً في Didit: نقاط نهاية Management API وأدوات MCP وسير عمل الإنشاء ثم الاختبار ثم التفعيل.

## متى تستخدم كل واجهة

| الواجهة | المصادقة | الأنسب لـ |
| - | - | - |
| **وحدة تحكم الأعمال** | تسجيل الدخول إلى الوحدة | مراجعة بشرية لكل تغيير؛ وبناء القواعد بصريًا والاختبار الرجعي |
| **Management API** | `x-api-key` | الأتمتة من الخادم الخلفي، ومجموعات القواعد في الكود، ونشر القواعد المُدار عبر CI |
| **Didit MCP** | تسجيل الدخول باستخدام Didit (OAuth) | مساعدو الذكاء الاصطناعي والوكلاء: Copilot في وحدة تحكم Didit وClaude وCursor أو أي عميل MCP |

## نقاط النهاية

| نقطة النهاية | الغرض |
| - | - |
| [`GET /v3/transactions/rules/`](https://docs.didit.me/ar/management-api/transactions/rules-list) | عرض القواعد مع عوامل التصفية والترتيب حسب الأداء |
| [`POST /v3/transactions/rules/`](https://docs.didit.me/ar/management-api/transactions/rules-create) | إنشاء قاعدة مخصصة |
| [`GET /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ar/management-api/transactions/rules-get) | قراءة قاعدة واحدة مع عدادات التنفيذ |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ar/management-api/transactions/rules-update) | تحديث قاعدة مخصصة؛ وتغيير وضع أي قاعدة |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](https://docs.didit.me/ar/management-api/transactions/rules-delete) | حذف قاعدة مخصصة (نهائي) |
| [`POST /v3/transactions/rules/backtest/`](https://docs.didit.me/ar/management-api/transactions/rules-backtest) | تقييم قاعدة افتراضية على سجلك السابق |
| [`GET /v3/transactions/rules/library/`](https://docs.didit.me/ar/management-api/transactions/rules-library) | تصفح مكتبة القواعد الجاهزة (150+) مع حالة التثبيت |
| [`POST /v3/transactions/rules/install/`](https://docs.didit.me/ar/management-api/transactions/rules-install) | تثبيت القواعد الجاهزة حسب المفتاح أو الحزمة أو تقاطع الاثنين |
| [`DELETE /v3/transactions/rules/install/`](https://docs.didit.me/ar/management-api/transactions/rules-uninstall) | إلغاء تثبيت القواعد الجاهزة حسب المفتاح أو الحزمة أو تقاطع الاثنين |

أدوات MCP المقابلة هي `didit_transaction_rule_list` و`didit_transaction_rule_get` و`didit_transaction_rule_create` و`didit_transaction_rule_update` و`didit_transaction_rule_delete` و`didit_transaction_rule_backtest` و`didit_transaction_rule_library_list` و`didit_transaction_rule_install` و`didit_transaction_rule_uninstall` - راجع [مرجع أدوات MCP](https://docs.didit.me/ar/integration/mcp/tools.md).

يُوثَّق المخطط الكامل - ويشمل كتالوج الحقول، وجميع المشغّلات البالغ عددها 19، والنوافذ الزمنية لمعدل المعاملات، والشروط المجمّعة، وأنواع الإجراءات الستة - في صفحة [القواعد واحتساب الدرجات](https://docs.didit.me/ar/transaction-monitoring/rules.md) ويُضمَّن في مرجع API.

## الإنشاء والاختبار الرجعي والتفعيل

نمط الإطلاق الآمن لأي قاعدة جديدة:

**1. إنشاء القاعدة في وضع TEST**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Structuring - inbound (custom)",
    "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days",
    "category": "finance",
    "mode": "TEST",
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "actions": [{"type": "add_score", "value": 35}]
  }'
```

اقرأ الحمولة على جزأين. يصف `scope` و`conditions` **المعاملة التي يتم تقييمها**: معاملة مالية واردة بعملة EUR بقيمة `amount` الخام أقل من 10,000. وتصف مدخلات `aggregation` **نافذة الـ30 يومًا للطرف نفسه**: 20 معاملة مالية واردة على الأقل بعملة EUR، ولا تبلغ أيٌّ منها 10,000 EUR أو أكثر. يجب أن تتحقق مدخلتا التجميع معًا، بغض النظر عن قيمة `evaluation_mode` - فهذا الإعداد يحكم الشروط فقط.

يستخدم هذا المثال `amount` الخام ويثبّت `currency` على EUR في النصفين، لذا فهو لا يعتمد على توحيد أسعار الصرف. لاختبار بيانات التجربة في البيئة التجريبية بالاختبار الرجعي، أرسل 20 معاملة مالية واردة على الأقل بعملة EUR للطرف نفسه خلال 30 يومًا، ولكلٍّ منها `amount` أقل من 10,000. لا يُشترط أيٌّ من `preferred_currency_amount` أو `amount_in_default_currency`. تخزّن عملية إدخال البيانات في البيئة التجريبية هذه المعاملات؛ فشغّل الاختبار الرجعي صراحةً.

تُقيِّم القاعدة من نوع `TEST` كل معاملة جديدة وتسجل ما كانت ستطابقه، لكنها لا تمسّ أبدًا درجة المعاملة أو حالتها.

> [!NOTE]
>
> **تصفية التجميع ليست شرطًا.** لا يقرأ الشرط أبدًا إلا المعاملة التي يتم تقييمها؛ ولا تضيّق تصفية التجميع إلا نافذة السجل التاريخية، وتقارن بالمساواة أو بعضوية القائمة - لا يوجد مرشح `lt`، لذا لا يمكنك أن تحسب *التحويلات الأقل من 10,000 فقط*.
>
> مدخلة `max ... lt 10000` هي الطريقة المدعومة لوضع سقف على النافذة: إذ تشترط أن **تكون كل** معاملة في النافذة أقل من 10,000، وهذا أشدّ من احتساب الصغيرة فقط - فتحويل واحد بقيمة 12,000 بين العشرين يمنع القاعدة من التفعيل. احذف هذه المدخلة إذا كنت تفضّل أن يقوم العدّ بذاته، ثم اذكر ذلك في العنوان: بدونها تحسب القاعدة التحويلات الواردة بأي حجم، فتطابقها تسعة عشر تحويلًا بقيمة 50,000 يليها تحويل صغير واحد.

**2. الاختبار الرجعي على سجلك**

```bash theme={null}
curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "conditions": [
      {"field": "currency", "operator": "eq", "value": "EUR"},
      {"field": "amount",
       "operator": "lt", "value": 10000}
    ],
    "aggregation": [
      {
        "metric": "count", "operator": "gte", "value": 20,
        "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      },
      {
        "metric": "max", "field": "amount",
        "operator": "lt", "value": 10000, "window": "30d",
        "filters": {"direction": "INBOUND",
                    "transaction_type": "finance",
                    "currency": "EUR",
                    "subject_vendor_data": "__current__"}
      }
    ],
    "evaluation_mode": "ALL",
    "scope": {
      "transaction_types": ["finance"],
      "directions": ["INBOUND"]
    },
    "period_days": 90
  }'
```

```json theme={null}
{ "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }
```

يعني عدد `matched` غير المتوقع أن الحدود تحتاج إلى ضبط قبل أن تتمكن القاعدة من اتخاذ إجراء بشأن أي شيء.

> [!WARNING]
>
> اختبر التكوين الذي ستفعّله **بمطابقة تامة**: نفس `conditions` و`aggregation` و`evaluation_mode` و`scope`. لا تضيف `conditions` و`aggregation` و`scope` المُغفلة أي قيود خاصة بها؛ إذ قد يؤدي حذف النطاق إلى تضمين اتجاهات أو أنواع معاملات تتجاهلها القاعدة المحفوظة. القيمة الافتراضية لـ `evaluation_mode` عند حذفها هي `ALL`، لذا قد يقلل حذفها للقاعدة من نوع `ANY` عدد المطابقات. القيمة الافتراضية لـ `period_days` عند حذفها هي 90 يومًا؛ ولا تعني أنها تختار سجلًّا غير محدود.

**3. التفعيل**

```bash theme={null}
curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"mode": "ACTIVE"}'
```

تُطبَّق القاعدة فورًا على جميع المعاملات الجديدة لتطبيق **في بيئة الإنتاج**.

> [!WARNING]
>
> لا تقيّم تطبيقات البيئة التجريبية القواعد أبدًا. تُخزَّن المعاملة في البيئة التجريبية دون أي إجراء آخر، لذا فإن تفعيل قاعدة على تطبيق في البيئة التجريبية لا يغيّر أي شيء يمكنك ملاحظته. الاختبار الرجعي هو الطريقة المدعومة لتجربة القاعدة قبل أن تصبح مباشرة - راجع [مراقبة المعاملات في البيئة التجريبية](https://docs.didit.me/ar/integration/sandbox-testing.md#مراقبة-المعاملات-في-البيئة-التجريبية).

## ترحيل القواعد من مزود آخر

لأن إنشاء القاعدة استدعاء API بسيط بمخطط موثّق بالكامل، يستطيع مساعد ذكي تحويل تصدير القواعد من مزود آخر إلى قواعد Didit نيابةً عنك.

1. **تصدير** قواعدك من المزود الحالي، إذ تُصدّر معظم الأدوات إلى ملفات CSV أو Excel.
2. **ارفع الملف** إلى مساعد وحدة تحكم Didit (أو أي وكيل متصل بـ MCP، مثل Claude مع [Didit MCP](https://docs.didit.me/ar/integration/mcp/overview.md) مُرفقًا). تُحوَّل جداول البيانات إلى نص تلقائيًا.
3. يقوم المساعد **بربط كل صف** بمخطط Didit (الشروط، والنوافذ الزمنية لمعدّل المعاملات، والإجراءات)، ويعرض لك الربط، مع الإشارة إلى أي عنصر لا يقابله شيء في Didit، وذلك قبل إنشاء أي شيء.
4. بعد موافقتك، يُنشئ **القواعد في وضع TEST**، ويُجري عليها **اختبارًا رجعيًا** على سجل معاملاتك، ويُبلغ عن الصفوف التي أُنشئت وفشلت وتعذّر ربطها.
5. **راجع الأرقام وفعّل** القواعد التي تبدو صحيحة، من وحدة التحكم أو باستخدام `PATCH {"mode": "ACTIVE"}`.

مثال على تصدير من مزود آخر:

```csv theme={null}
Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline
```

يتحول إلى قواعد كهذه:

```json theme={null}
{
  "title": "Structuring - Small Transfers",
  "description": "20+ outbound EUR transfers, all under 10,000 EUR, 30 days",
  "category": "finance",
  "mode": "TEST",
  "evaluation_mode": "ALL",
  "scope": {
    "transaction_types": ["finance"],
    "directions": ["OUTBOUND"]
  },
  "conditions": [
    {"field": "currency", "operator": "eq", "value": "EUR"},
    {"field": "amount", "operator": "lt", "value": 10000}
  ],
  "aggregation": [
    {
      "metric": "count", "operator": "gte", "value": 20,
      "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    },
    {
      "metric": "max", "field": "amount",
      "operator": "lt", "value": 10000, "window": "30d",
      "filters": {"direction": "OUTBOUND",
                  "transaction_type": "finance",
                  "currency": "EUR",
                  "subject_vendor_data": "__current__"}
    }
  ],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}
```

يحمل صف CSV اتجاهًا وعملة، لذا يحمل نصفا القاعدة كليهما: `scope` و`conditions` يحصران المعاملة المُقيَّمة في تحويل صادر بعملة EUR أقل من 10,000، وفلاتر التجميع تحصر النافذة الزمنية البالغة 30 يومًا على التحويلات الصادرة بعملة EUR للجهة نفسها. الحقل `amount` الخام قابل للمقارنة داخل عملة واحدة فقط، لذا أبقِ العملة مُثبَّتة كما هو موضّح أعلاه. يتطلب الحد الأعلى عبر العملات وجود مبلغ موحّد لكل معاملة في النافذة. والتبديل إلى `preferred_currency_amount` وحده لا يضمن التوفر، إذ قد تُعامَل المبالغ الموحّدة التاريخية المفقودة على أنها صفر في التجميعات العددية.

إدخال `max` هو ما يُبقي النافذة أقل من 10,000 EUR، لأن فلتر التجميع لا يستطيع التعبير عن "أقل من 10,000"، انظر الملاحظة عن [خطوة الإنشاء](#الإنشاء-والاختبار-الرجعي-والتفعيل) أعلاه للمفاضلة التي يتضمنها ذلك. وأي شيء لا يستطيع المخطط التعبير عنه بدقة يستحق الإفصاح عنه صراحةً في `description` الخاصة بالقاعدة، بدلًا من التقريب بصمت.

> [!TIP]
>
> قبل إعادة إنشاء قاعدة مزود آخر كقاعدة مخصصة، راجع [مكتبة القواعد](https://docs.didit.me/ar/management-api/transactions/rules-library.md): تقدّم Didit 150+ قالبًا جاهزًا تغطي الأنماط الشائعة (الهيكلة، والسرعة، والتعرض للعقوبات، وإعادة استخدام الجهاز، ومخاطر العملات المشفرة)، وتثبيت القالب يتم عبر استدعاء واحد.

## أخطاء التحقق دقيقة عن قصد

تتحقق endpoint الخاصة بإنشاء القواعد وتحديثها من قيم الشروط والتجميع والنطاق مقابل ما يقبله محرك القواعد تمامًا: المشغّلات أو المقاييس غير المعروفة، ونوافذ مُشكَّلة بشكل خاطئ (`"30days"` بدلًا من `"30d"`)، واتجاهات نطاق غير صالحة، و`contains_any` بدون قائمة، و`fuzzy_match` بدون `score`، و`change_status` إلى `AWAITING_USER` بدون `workflow_id`. كل هذه الحالات تعيد `400` يذكر الفهرس والمشكلة، بدلًا من حفظ قاعدة لا تتطابق أبدًا بصمت. ينبغي للوكلاء والنصوص البرمجية قراءة نص الخطأ وتصحيح الحمولة. أما مفاتيح النطاق الإضافية بخلاف `transaction_types` و`directions` و`action_types` فتُحفظ لكن يتجاهلها المحرك، وهذا يطابق الطريقة التي كانت Business Console تحفظ بها هذه المفاتيح دائمًا.

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

> [card] [القواعد واحتساب الدرجات](https://docs.didit.me/ar/transaction-monitoring/rules.md)
>
> المخطط الكامل للقاعدة: الحقول والمشغّلات ونوافذ السرعة والإجراءات.

> [card] [واجهة برمجة تطبيقات إنشاء القاعدة](https://docs.didit.me/ar/management-api/transactions/rules-create.md)
>
> مرجع endpoint مع مخططات الطلب والاستجابة.

> [card] [مكتبة القواعد](https://docs.didit.me/ar/transaction-monitoring/rules-library.md)
>
> فهرس القوالب الجاهزة البالغ 150+ وحزمها.

> [card] [نظرة عامة على MCP](https://docs.didit.me/ar/integration/mcp/overview.md)
>
> اربط وكيلًا ذكيًا بمساحة عمل Didit الخاصة بك.


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