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

# تحذيرات وأكواد المصادقة البيومترية

> عالِج تحذيرات المصادقة البيومترية في Didit: درجات الحيوية وهجمات الوجه وتطابق قائمة الحظر، مع ضبط الحدود وإجراءات الرفض.

تجمع المصادقة البيومترية بين فحص كشف الحيوية ومطابقة الوجه الاختيارية بنسبة 1:1 مع الوجه المرجعي الذي تم تحديده عند إنشاء الجلسة (إما `portrait_image` المُقدّمة، أو وجه المستخدم المخزن الذي يتم البحث عنه عبر `vendor_data`). وتُصدر كل خطوة تحذيراتها الخاصة في payload القرار الخاص بـ V3. تسرد هذه الصفحة كل رمز، ومكان ظهوره، وكيفية ترجمة الحدود إلى حالة الجلسة النهائية.

## نظرة عامة

عند تشغيل جلسة مصادقة بيومترية، تقوم Didit بما يلي:

* التقاط صورة سيلفي حية باستخدام 3D Action، أو Flash، أو Passive Liveness (`method`: `ACTIVE_3D`، أو `FLASHING`، أو `PASSIVE`).
* استخراج الوجه الأكبر من الصورة الملتقطة واحتساب درجة الحيوية له.
* إذا كان سير العمل يتضمن مطابقة الوجه، فستتم مقارنة الوجه الملتقط بالوجه المرجعي للجلسة (`portrait_image` المُقدّمة أو وجه المستخدم المخزن).
* كتابة نتيجة كل خطوة بالإضافة إلى أي تحذيرات في قرار الجلسة.

تحتفظ التحذيرات ببنية [كائن التحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير) المشتركة والمستخدمة في جميع أنحاء المنصة: `feature`، و`risk`، و`additional_data`، و`log_type`، و`short_description`، و`long_description`، و`node_id`.

## أين تظهر التحذيرات

| مفتاح استجابة القرار | وسم الميزة في التحذير | متى يُطلَق |
| - | - | - |
| `liveness_checks[].warnings[]` | `LIVENESS` | احتساب درجات الحيوية، وجودة الوجه، والسطوع، وتعدد الوجوه، وفحوصات قائمة الحظر / قائمة السماح / الوجه المكرر. |
| `face_matches[].warnings[]` | `FACEMATCH` | مطابقة الوجه مع الوجه المرجعي للجلسة (`portrait_image` المُقدّمة أو وجه المستخدم المخزن). |

في جلسة المصادقة البيومترية النموذجية، يوجد عنصر واحد في كل مصفوفة. وفي مسارات العمل متعددة المثيلات، يزيل `node_id` الموجود في كل تحذير أي لبس بشأن الخطوة التي أنتجته.

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

تؤدي التحذيرات التالية دائماً إلى رفض خطوتها (`log_type: "error"`) بغض النظر عن طريقة تكوينك لسير العمل:

| المخاطر | الميزة | سبب الرفض التلقائي |
| - | - | - |
| `FACE_IN_BLOCKLIST` | `LIVENESS` | تطابق الوجه مع مدخل في قائمة حظر الوجوه لديك. |
| `NO_FACE_DETECTED` | `LIVENESS` | لم يتم تحديد موقع أي وجه أثناء التقاط الحيوية، أو استنفد المستخدم محاولات إعادة الالتقاط. |
| `LIVENESS_FACE_ATTACK` | `LIVENESS` | تم اكتشاف هجوم العرض (قناع، أو إعادة تشغيل عبر شاشة، أو انتحال من فئة التزييف العميق). |
| `NO_REFERENCE_IMAGE` | `FACEMATCH` | لم تكن هناك صورة مرجعية متاحة لإجراء المقارنة. وعند إطلاق هذا التحذير، يتم حجب `LOW_FACE_MATCH_SIMILARITY`. |

عند إطلاق `NO_FACE_DETECTED`، يتم حجب `LOW_LIVENESS_SCORE` (نظراً لعدم وجود وجه لاحتساب درجاته).

## الحدود والإجراءات القابلة للتكوين

يتم احتساب درجات هذه التحذيرات ثم تعيينها لحالة معينة من خلال الحدود والإجراءات التي تحددها لكل سير عمل:

| المخاطر | الميزة | السلوك القابل للتكوين |
| - | - | - |
| `LOW_LIVENESS_SCORE` | `LIVENESS` | درجة عند حد المراجعة أو أقل منه ← `In Review`؛ وعند حد الرفض أو أقل منه ← `Declined`. |
| `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | درجة عند حد المراجعة أو أقل منه (الافتراضي 70) ← `In Review`؛ وعند حد الرفض أو أقل منه (الافتراضي 50) ← `Declined`. |
| `LOW_FACE_QUALITY` | `LIVENESS` | حد المراجعة (الافتراضي 15) ← `In Review`؛ حد الرفض (الافتراضي 0، أي أن الرفض معطّل) ← `Declined`. مقتصر على Passive Liveness فقط. |
| `LOW_FACE_LUMINANCE` | `LIVENESS` | أقل من الحد الأدنى للسطوع (الافتراضي 20): بدون إجراء / مراجعة (افتراضي) / رفض. مقتصر على Passive Liveness فقط. |
| `HIGH_FACE_LUMINANCE` | `LIVENESS` | أعلى من الحد الأقصى للسطوع (الافتراضي 80): بدون إجراء / مراجعة (افتراضي) / رفض. مقتصر على Passive Liveness فقط. |
| `MULTIPLE_FACES_DETECTED` | `LIVENESS` | بدون إجراء (افتراضي) / مراجعة / رفض عند التقاط أكثر من وجه واحد. مقتصر على Passive Liveness فقط. |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | إجراء مشترك واحد للوجه المكرر: بدون إجراء (افتراضي) / مراجعة / رفض للتطابقات مع وجوه المستخدمين الآخرين المقبولة أو المستوردة. |
| `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | إجراء خاص (`face_liveness_duplicated_face_name_mismatch_action`): بدون إجراء / مراجعة (افتراضي) / رفض. يُطلَق جنباً إلى جنب مع `DUPLICATED_FACE` عندما لا تتطابق هوية الجلسة التي حدث معها التطابق مع الاسم المحدد لهذه الجلسة — راجع [تحذيرات كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/warnings-liveness.md#مطابقة-الوجه-عبر-الجلسات). |

إنّ `POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) **غير** قابل للتكوين — إذ يتم دائماً توجيه التطابق ذي الثقة الأقل في قائمة الحظر إلى المراجعة (`log_type: "warning"`).

## محاولات إعادة الالتقاط

تدخل حالات الفشل الناتجة فقط عن مخاطر جودة الالتقاط القابلة للإصلاح (درجة منخفضة، عدم وجود وجه، الجودة، السطوع، الوجوه المتعددة — والتشابه المنخفض في مطابقة الوجه) في حلقة إعادة المحاولة قبل تثبيت الحالة: يحصل المستخدم على ما يصل إلى إجمالي محاولات `face_liveness_max_attempts` / `face_match_max_attempts` (الافتراضي 3، وقابل للتكوين من 2 إلى 5 لكل عقدة سير عمل). وعند استنفاد هذا العدد، يتم تطبيق الحالة المحسوبة للمحاولة الأخيرة ويتم تسجيل `LIVENESS_MAX_ATTEMPTS_EXCEEDED` أو `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` كـ `information` لتوثيق ذلك.

## تحذيرات كشف الحيوية

تُرجع API نصوص `short_description` و `long_description` الدقيقة التالية:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_LIVENESS_SCORE` | درجة حيوية منخفضة | أدى فحص الحيوية إلى درجة منخفضة، مما يشير إلى احتمال استخدام تمثيلات وجهية غير حية أو بيانات بيومترية رديئة الجودة. |
| `NO_FACE_DETECTED` | لم يتم اكتشاف أي وجه في كشف الحيوية | لم يتمكن النظام من التعرف على وجه أثناء فحص الحيوية، وهو ما قد يعود إلى ضعف جودة الصورة، أو الوضعية غير الصحيحة، أو مشكلات فنية. |
| `LIVENESS_FACE_ATTACK` | هجوم على كشف حيوية الوجه | اكتشف النظام محاولة محتملة لتجاوز فحص الحيوية. |
| `FACE_IN_BLOCKLIST` | الوجه مدرج في قائمة الحظر | حدد النظام وجهاً في قائمة الحظر، مما يعني أنه لا يُسمح بالتحقق من هذا الوجه. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | احتمال وجود الوجه في قائمة الحظر | حدد النظام احتمال وجود الوجه في قائمة الحظر، مما يعني أنه لا يُسمح بالتحقق من هذا الوجه. |
| `FACE_IN_ALLOWLIST` | الوجه مدرج في قائمة السماح | تطابق الوجه مع قائمة السماح للوجوه الخاصة بالتطبيق، لذا تم تخطي إجراءات الوجوه المكررة لهذه الإشارة. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | احتمال وجود الوجه في قائمة السماح | تطابق الوجه على الأرجح مع قائمة السماح للوجوه الخاصة بالتطبيق، لذا تم تخطي إجراءات الوجوه المكررة المحتملة لهذه الإشارة. |
| `DUPLICATED_FACE` | وجه مكرر من جلسة مقبولة أخرى | حدد النظام وجهاً مكرراً من جلسة مقبولة أخرى، مما يتطلب مزيداً من التحقيق. |
| `POSSIBLE_DUPLICATED_FACE` | احتمال وجود وجه مكرر من جلسة مقبولة أخرى | حدد النظام وجهاً مكرراً محتملاً من جلسة مقبولة أخرى، مما يتطلب مزيداً من التحقيق. |
| `DUPLICATED_FACE_NAME_MISMATCH` | وجه مكرر باسم مختلف | تم قبول نفس الوجه بالفعل في جلسة أخرى، ولكن باسم مختلف. الهوية وراء الوجه المكرر لا تتطابق مع الهوية المعلنة في هذه الجلسة، وهو مؤشر قوي على الاحتيال في الهوية. |
| `MULTIPLE_FACES_DETECTED` *(للوضع السلبي فقط)* | تم اكتشاف وجوه متعددة | تم اكتشاف وجوه متعددة في صورة كشف الحيوية. يستخدم النظام الوجه الأكبر للتحقق من الحيوية ومقارنة الوجه، ولكن وجود وجوه متعددة قد يتطلب مراجعة إضافية. |
| `LOW_FACE_QUALITY` *(للوضع السلبي فقط)* | جودة وجه منخفضة | جودة صورة الوجه أقل من الحد المقبول، مما قد يؤثر على موثوقية كشف الحيوية. قد يرجع ذلك إلى دقة الكاميرا، أو التركيز، أو تشوهات الضغط. |
| `LOW_FACE_LUMINANCE` *(للوضع السلبي فقط)* | إضاءة وجه منخفضة | صورة الوجه مظلمة للغاية، مما قد يؤثر على دقة كشف الحيوية. يُوصى بظروف إضاءة أفضل. |
| `HIGH_FACE_LUMINANCE` *(للوضع السلبي فقط)* | إضاءة وجه عالية | صورة الوجه ساطعة للغاية أو ذات تعريض ضوئي مفرط، مما قد يؤثر على دقة كشف الحيوية. يُوصى بتقليل الإضاءة أو تجنب الضوء المباشر. |
| `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | تم تجاوز الحد الأقصى لمحاولات كشف الحيوية | تم الوصول إلى الحد الأقصى لعدد محاولات التقاط كشف الحيوية. تم تطبيق الحالة المحسوبة للمحاولة الأخيرة (مرفوضة أو قيد المراجعة). |

تحمل حالات التطابق مع قائمة الحظر وقائمة السماح والوجوه المكررة كائن `additional_data` يتضمن الجلسة المطابقة (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`، ورقم الجلسة المطابق `*_session_number`، و`api_service`). يظهر رمز واحد فقط من هذه الرموز الستة في كل تقرير. ويُعد `DUPLICATED_FACE_NAME_MISMATCH` هو الاستثناء: حيث يصدر **بالإضافة إلى** `DUPLICATED_FACE`، ولا يحل محله مطلقاً، وذلك عندما لا تتطابق هوية الجلسة المطابقة مع الاسم المحدد لهذه الجلسة. ويضيف كائن `additional_data` الخاص به الحقل `name_match_score` إلى نفس حقول الجلسة المكررة. لا يُعد الاسم المكتوب بنظام كتابة مختلف في كل جانب عدم تطابق إذا كانت مستندات التحقق من الهوية لكلا الجلستين تشترك في دولة الإصدار، ورقم مستند مطابق تماماً أو رقم شخصي مطابق تماماً، وتاريخ ميلاد غير متناقض. راجع [تحذيرات كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/warnings-liveness.md#مطابقة-الوجه-عبر-الجلسات).

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

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | تشابه منخفض في مطابقة الوجه | لا تتطابق ملامح الوجه في الصورة المقدمة بشكل وثيق مع الصورة المرجعية، مما يشير إلى احتمال عدم تطابق الهوية. |
| `NO_REFERENCE_IMAGE` | لم يتم العثور على صورة مصدر لإجراء مطابقة الوجه | الصورة المرجعية لمقارنة الوجه مفقودة، مما يمنع النظام من إكمال عملية مطابقة الوجه. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | تم تجاوز الحد الأقصى لمحاولات مطابقة الوجه | تم الوصول إلى الحد الأقصى لعدد محاولات التقاط مطابقة الوجه. تم تطبيق الحالة المحسوبة للمحاولة الأخيرة (مرفوضة أو قيد المراجعة). |

## مثال — مرفوضة بسبب هجوم على كشف الحيوية

```json theme={null}
{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}
```

## مثال — قيد المراجعة بسبب انخفاض درجة التشابه

```json theme={null}
{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "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"
        }
      ]
    }
  ]
}
```

تقع الدرجة (58.70) بين حد الرفض (الافتراضي 50) وحد المراجعة (الافتراضي 70)، لذا يحمل التحذير القيمة `log_type: "warning"` وتكون حالة مطابقة الوجه هي `In Review`. في هذا المثال، تم إطلاق التحذير في جلسة كان معرّفها `session_id` هو `11111111-2222-3333-4444-555555555555` — ويحمل `source_image_session_id` المعرّف الخاص بالجلسة نفسها لأن الصورة المرجعية جاءت من الصورة الشخصية المخزنة عند إنشاء الجلسة.

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

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

## صفحات ذات صلة

> [card] [تقرير المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/report-biometric-authentication.md)
>
> أين تظهر `liveness_checks[]` و `face_matches[]` في قرار V3.

> [card] [تحذيرات كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/warnings-liveness.md)
>
> المرجع الكامل لتحذيرات كشف الحيوية بما في ذلك مطابقة الوجه المكرر.

> [card] [تحذيرات مطابقة الوجه](https://docs.didit.me/ar/core-technology/face-match/warnings-face-match.md)
>
> المرجع الكامل لتحذيرات مطابقة الوجه للمقارنات بنسبة 1:1.


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