> ## 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.

# تحذيرات مطابقة الوجه ورموز الأخطاء

> كل تحذير تُصدره وحدة مطابقة الوجه 1:1 من Didit، مثل انخفاض التشابه، وغياب الصورة المرجعية، واستنفاد المحاولات، مع السبب والخطورة والحل.

## نظرة عامة

تحدد التحذيرات في تقرير مطابقة الوجه كل حالة لاحظتها Didit أثناء إجراء مقارنة الوجه بنسبة 1:1. وتظهر هذه التحذيرات في مصفوفة `warnings[]` لكل عنصر ضمن `face_matches[]` (راجع [تقرير مطابقة الوجه](https://docs.didit.me/ar/core-technology/face-match/report-face-match.md)). يحمل كل إدخال أيضاً `feature: "FACEMATCH"` و `node_id` لعقدة سير العمل التي أصدرته.

يتضمن كل تحذير ثلاث طبقات:

1. **رمز `risk`** — معرّف ثابت يمكنك مطابقته برمجياً في الكود الخاص بك.
2. **نوع السجل `log_type`** — `information` أو `warning` أو `error`، وهو مشتق من حدود درجة التشابه المحددة في سير العمل لديك.
3. **التأثير على القرار** — يُحدد بناءً على حدود المراجعة والرفض لدرجة التشابه في سير العمل.

صُممت وحدة مطابقة الوجه لتكون صغيرة عن قصد — إذ توجد خمسة رموز مخاطر بالضبط، وهي موضحة بالكامل أدناه.

## شروط الرفض التلقائي

يؤدي الخطر التالي دائماً إلى تحويل تقرير مطابقة الوجه (والجلسة) إلى `Declined`:

| الخطر | المُشغِّل |
| - | - |
| `NO_REFERENCE_IMAGE` | إحدى الصورتين مفقودة، إما `source_image` (المرجعية) أو `target_image` (صورة سيلفي)، وبالتالي تعذرت المقارنة. |

عند تفعيل `NO_REFERENCE_IMAGE`، يتم حجب `LOW_FACE_MATCH_SIMILARITY` (نظراً لعدم وجود ما يمكن احتساب درجته).

هناك استثناء واحد.
عند اكتمال خطوة التحقق من الهوية عبر [البحث غير المستندي](https://docs.didit.me/ar/core-technology/id-verification/non-doc-lookup.md) الذي لا يُرجع سجله أي صورة شخصية ولا يتحقق من أي وجه، فإن مطابقة الوجه لا تجد ما تقارن به الصورة المباشرة بحكم طبيعة العملية.
يتم الإبلاغ عن ذلك كـ `FACE_MATCH_NOT_COMPUTED` مع درجة `null`، ويُبت فيه بواسطة `face_match_not_computed_action` (أدناه)، وليس كرفض تلقائي.

## إعدادات التحقق القابلة للتكوين

في لوحة تحكم Didit، تخضع درجة تشابه مطابقة الوجه لحدين اثنين (دون وجود مفتاح تبديل بين القبول/المراجعة/الرفض):

| الإعداد | الافتراضي | السلوك |
| - | - | - |
| `face_match_score_review_threshold` | 70 | عندما تكون `score` ≤ هذه القيمة، يتم إطلاق `LOW_FACE_MATCH_SIMILARITY` وتنتقل الحالة إلى `In Review`. |
| `face_match_score_decline_threshold` | 50 | عندما تكون `score` ≤ هذه القيمة، يتم تصعيد التحذير نفسه إلى `error` وتنتقل الحالة إلى `Declined`. |

قم برفع حد المراجعة إذا لاحظت عدداً كبيراً جداً من الموافقات الخاطئة؛ وقم بخفض حد الرفض إذا لاحظت عدداً كبيراً جداً من حالات الرفض الخاطئة.

يتحكم إعداد منفصل فيما يحدث عندما **يتعذر احتساب درجة التشابه على الإطلاق**: لم يتم اكتشاف أي وجه في إحدى الصور، أو لم يترك البحث غير المستندي أي مرجع للمقارنة به:

| الإعداد | الافتراضي | السلوك |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | الإجراء المطبق بمجرد أن تصبح نتيجة "تعذر الاحتساب" نهائية. يرسل `REVIEW` التقرير إلى `In Review`؛ بينما يحدده `DECLINE` كـ `Declined`. (لا يوجد خيار للموافقة التلقائية — فالدرجة التي لم تُحتسب مطلقاً لا يتم تمريرها أبداً دون تنبيه). |

يحكم هذا الإجراء كلاً من `FACE_MATCH_NOT_COMPUTED` (عدم وجود وجه في صورة المستند الشخصية، أو عدم وجود أي مرجع على الإطلاق بعد بحث غير مستندي) وحالة استنفاد محاولات `NO_FACE_IN_SELFIE` (عدم وجود وجه في صورة سيلفي بعد محاولات إعادة التقاط المستخدم). عندما تكون المشكلة متعلقة بصورة سيلفي، يُطلب من المستخدم أولاً إعادة التقاطها — راجع أدناه — ولا يُطبق الإجراء إلا إذا استمر تعذر اكتشاف الوجه بعد نفاد عدد المحاولات المتاحة.

تدخل حالات الفشل الناتجة عن انخفاض التشابه أيضاً في حلقة إعادة محاولة التقاط قبل تثبيت الحالة: يحصل المستخدم على ما يصل إلى `face_match_max_attempts` من إجمالي المحاولات (الافتراضي 3، قابل للتكوين من 2 إلى 5 لكل عقدة سير عمل) لإعادة الالتقاط. وتستخدم حالة فشل `NO_FACE_IN_SELFIE` حلقة إعادة المحاولة نفسها، نظراً لأن إعادة التقاط صورة سيلفي أوضح قد يحل المشكلة. أما فشل `FACE_MATCH_NOT_COMPUTED` **فلا** يخضع لإعادة المحاولة — إذ لا يمكن إعادة التقاط صورة المستند الشخصية في هذه الخطوة. وعند نفاد عدد المحاولات فقط، تُطبق حالة المحاولة الأخيرة — ويتم تسجيل `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` لتوثيق ذلك.

في [Face Match API](https://docs.didit.me/ar/standalone-apis/face-match.md) المستقل، يوجد حد رفض فقط (خيار الطلب `face_match_score_decline_threshold`، والافتراضي 30)؛ ويؤدي إطلاق أي تحذير إلى رفض الطلب، ويتم إطلاق `NO_REFERENCE_IMAGE` عندما يتعذر مقارنة أي وجه على الإطلاق.

## التحذيرات الصادرة

| المخاطر | السبب | مستوى الخطورة | هل تؤثر على الحالة؟ | المعالجة |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. يتم كتمه عند وجود `NO_REFERENCE_IMAGE` أيضاً. | `warning` بين الحدود؛ و`error` عند حد الرفض أو أدنى منه | `In Review` بين الحدود؛ و`Declined` عند حد الرفض أو أدنى منه | ضبط الحدود، أو القبول عبر مراجعة يدوية. |
| `FACE_MATCH_NOT_COMPUTED` | تعذر احتساب درجة التشابه لعدم اكتشاف أي وجه في **صورة المستند الشخصية**، أو لأن خطوة التحقق من الهوية كانت [بحثاً بدون مستند](https://docs.didit.me/ar/core-technology/id-verification/non-doc-lookup.md) لم يترك أي مرجع للمقارنة معه (سجل لا يُرجع صورة شخصية ولا يتحقق من أي وجه). يتم كتمه عند وجود `NO_REFERENCE_IMAGE` أيضاً. | `warning` عندما تكون قيمة `face_match_not_computed_action` هي `REVIEW`؛ و`error` عندما تكون `DECLINE` | `In Review` أو `Declined`، وفقاً لـ `face_match_not_computed_action` | لا يمكن إعادة التقاط صورة المستند في هذه الخطوة: قم بالحل عبر مراجعة يدوية، أو أعد التقاط المستند في مرحلة سابقة من مسار التحقق. بعد البحث المقتصر على البيانات فقط، اضبط `face_match_not_computed_action` على النتيجة التي تريدها، أو اطلب مستنداً في الدول التي تكون فيها المطابقة البيومترية مهمة. |
| `NO_FACE_IN_SELFIE` | تعذر احتساب درجة التشابه لعدم اكتشاف أي وجه في **صورة السيلفي** الخاصة بالمستخدم. يُطلب من المستخدم إعادة التقاط صورة السيلفي قبل تثبيت هذا التحذير. | `warning` عندما تكون قيمة `face_match_not_computed_action` هي `REVIEW`؛ و`error` عندما تكون `DECLINE` | `In Review` أو `Declined`، وفقاً لـ `face_match_not_computed_action`، بعد استنفاد محاولات الإعادة | يعيد المستخدم التقاط صورة سيلفي أكثر وضوحاً، وبإضاءة جيدة، ومواجهة للكاميرا. |
| `NO_REFERENCE_IMAGE` | إما أن الصورة المرجعية أو الصورة المستهدفة مفقودة (باستثناء المرجع الذي لم يُنتجه البحث بدون مستند مطلقاً، والذي يُعد `FACE_MATCH_NOT_COMPUTED`). | `error` | **رفض تلقائي** | تأكد من التقاط كل من الصورة الشخصية في المستند وصورة سيلفي كشف الحيوية. بالنسبة لـ API المستقل، قم بتمرير صورتين صالحتين للوجه. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | استنفد المستخدم رصيد محاولات إعادة الالتقاط المتاحة (`face_match_max_attempts`) بعد حالات فشل متكررة بسبب انخفاض التشابه. | `information` | لا — يسجل أنه تم تطبيق الحالة المحتسبة للمحاولة الأخيرة (الرفض أو المراجعة) | ارفع قيمة `face_match_max_attempts` في عقدة سير العمل، أو قم بالحل عبر مراجعة يدوية. |

## أمثلة

### قيد المراجعة — تشابه حدي

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### قيد المراجعة — تعذر احتساب مطابقة الوجه

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### رفض تلقائي — مرجع مفقود

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]
```

### استنفاد محاولات الإعادة — تطبيق حالة المحاولة الأخيرة

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]
```

> [!NOTE]
>
> تُرجع [واجهة API لمطابقة الوجه](https://docs.didit.me/ar/standalone-apis/face-match.md) المستقلة نفس بنية التحذير مطروحاً منها `node_id` (حيث لا تكون المقارنة مرتبطة بعقدة سير عمل).

## أنواع التحذيرات

يتم تعيين مستوى خطورة لكل خطر بناءً على تهيئة تطبيقك. ومستويات الخطورة الثلاثة هي:

## مواضيع ذات صلة

* [تقرير مطابقة الوجه](https://docs.didit.me/ar/core-technology/face-match/report-face-match.md) — مخطط التقرير الكامل وحالاته.
* [تحذيرات كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/warnings-liveness.md) — تحذيرات سابقة مرتبطة بالتقاط صورة السيلفي.
* [webhook](https://docs.didit.me/ar/integration/webhooks.md) — يحمل `session.status.updated` التحذيرات فور انتهاء الخطوة.
* [نماذج البيانات — مطابقة الوجه](https://docs.didit.me/ar/reference/data-models.md#مطابقة-الوجه) — المخطط القياسي.
* [نماذج البيانات — كائن التحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير) — بنية كل إدخال في `warnings[]`.


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