> ## 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:N وأكواد الأخطاء

> شرح رموز تحذيرات البحث بالوجه 1:N في Didit: تطابقات قائمة الحظر، والوجوه المكررة، وتعدد الوجوه، والبوابة التي ترفض الصور التي لا يُكتشف فيها أي وجه.

## نظرة عامة

يُصدر البحث بالوجه (Face Search) مجموعة صغيرة من التحذيرات حتى يتمكن فريقك من معرفة **سبب** إرجاع البحث للحالة `Approved` أو `Declined`. تُعاد التحذيرات في مصفوفة `face_search.warnings[]` ضمن استجابة `POST /v3/face-search/` (راجع [تقرير البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/report-face-search.md)).

تستخدم التحذيرات هنا **هيكلاً مصغراً** مقارنة بتحذيرات سير العمل: لا يوجد `node_id`. يحدد عقد الاستجابة الموثق خمسة حقول — `risk` و`additional_data` و`log_type` و`short_description` و`long_description` — كما يحمل payload وقت التشغيل بشكل إضافي حقل `feature`، والذي يكون دائماً `"LIVENESS"` في هذا الـ endpoint.

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

| الخطر | السبب | مستوى الخطورة (`log_type`) | التأثير على الحالة | الإجراء الموصى به لمعالجة المشكلة |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | تطابقت صورة البحث مع وجه في قائمة الحظر الخاصة بوجوه تطبيقك بنسبة تتجاوز نطاق التشابه عالي الثقة. | `error` | يفرض الحالة `Declined`. | رفض المستخدم. التحقيق في الجلسة المرتبطة عبر `additional_data.blocklisted_session_id`. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | تطابق وجه مدرج في قائمة الحظر ضمن نطاق التشابه "المحتمل" الأدنى، تحت نطاق الثقة العالية. | `error` | يفرض الحالة `Declined` في واجهة برمجة تطبيقات البحث بالوجه المستقلة (أكثر صرامة من فحص الحيوية في سير العمل، والذي يرسل هذا الخطر إلى المراجعة). | مراجعة يدوية. تأكد من صحة التطابق بالرجوع إلى أدلة قائمة الحظر الأصلية قبل اتخاذ أي إجراء. |
| `MULTIPLE_FACES_DETECTED` | تم العثور على أكثر من وجه واحد في صورة البحث المرسلة. يستمر تشغيل البحث باستخدام أكبر وجه تم اكتشافه. | `warning` | لا يوجد — لا يؤدي للرفض بمفرده أبداً. | إعادة التقاط الصورة مع وجود شخص واحد فقط في الإطار إذا لم يكن الوجه الأكبر هو الوجه المقصود. |
| `DUPLICATED_FACE` | تطابق الوجه، فوق نطاق الثقة العالية، مع وجه من جلسة مقبولة أو وجه ملف تعريف مستخدم مستورد. لا يستثني الـ endpoint المستقل الجلسات التي لها نفس `vendor_data`، لذلك سيتطابق المستخدم العائد مع جلساته السابقة. | `information` | لا يوجد — تظهر التكرارات كإشارة فقط، وليس كحالات رفض. | التحقيق في الجلسة المرتبطة عبر `additional_data.duplicated_session_id`. اتخاذ قرار بشأن حظر الحسابات أو دمجها من جانبك. |
| `POSSIBLE_DUPLICATED_FACE` | مماثل للتحذير `DUPLICATED_FACE` ولكن التشابه يقع ضمن نطاق "محتمل" الأدنى بدلاً من نطاق الثقة العالية. | `information` | لا يوجد. | مراجعة يدوية قبل التعامل مع السجلين على أنهما للشخص نفسه. |

المُنتِج: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`)؛ اشتقاق الحالة: `get_face_search_status` (`apis/views/face_search.py:242-248`)، والذي يرفض **فقط** عند وجود أحد خطري قائمة الحظر.

قواعد إصدار التحذيرات الجديرة بالمعرفة:

* **قائمة الحظر لها الأولوية على التكرارات.** يؤدي التطابق المؤكد مع قائمة الحظر إلى كتم `DUPLICATED_FACE`، ويؤدي التطابق المحتمل مع قائمة الحظر إلى كتم `POSSIBLE_DUPLICATED_FACE` — فلن تحصل أبداً على كلا طرفي الزوج لنفس نطاق الثقة.
* **يشير `additional_data` إلى أول وجه مطابق فقط**، حتى لو كانت `matches[]` تحتوي على عدة وجوه. تحمل تحذيرات قائمة الحظر `{blocklisted_session_id, blocklisted_session_number, api_service}`؛ وتحمل تحذيرات التكرار `{duplicated_session_id, duplicated_session_number, api_service}`؛ بينما يحمل `MULTIPLE_FACES_DETECTED` القيمة `null`. تكون قيمة `api_service` بالأحرف الكبيرة (مثل `PASSIVE_LIVENESS`) أو `null` لجلسات سير العمل.
* **الوجوه المدرجة في قائمة السماح تكتم تحذيرات التكرار** — يؤدي تطابق قائمة السماح عالي الثقة إلى إزالة `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (ولا يؤدي أبداً إلى إزالة تحذيرات قائمة الحظر).

### نصوص التحذيرات الدقيقة

| الخطر | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | وجه في قائمة الحظر | حدد النظام وجهاً في قائمة الحظر، مما يعني أنه لا يُسمح بالتحقق من هذا الوجه. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | وجه محتمل في قائمة الحظر | حدد النظام وجهاً محتملاً في قائمة الحظر، مما يعني أنه لا يُسمح بالتحقق من هذا الوجه. |
| `DUPLICATED_FACE` | وجه مكرر من جلسة مقبولة أخرى | حدد النظام وجهاً مكرراً من جلسة مقبولة أخرى، مما يتطلب مزيداً من التحقيق. |
| `POSSIBLE_DUPLICATED_FACE` | وجه مكرر محتمل من جلسة مقبولة أخرى | حدد النظام وجهاً مكرراً محتملاً من جلسة مقبولة أخرى، مما يتطلب مزيداً من التحقيق. |
| `MULTIPLE_FACES_DETECTED` | تم اكتشاف عدة وجوه | تم اكتشاف عدة وجوه في صورة كشف الحيوية. يستخدم النظام أكبر وجه للتحقق من الحيوية ومقارنة الوجه، ولكن وجود عدة وجوه قد يتطلب مراجعة إضافية. |

### بوابة التحقق من صورة البحث

عند عدم اكتشاف أي وجه في `user_image`، ترفض واجهة برمجة التطبيقات الطلب برمز HTTP `400` و`{"error": "No face detected in the image"}` **قبل** إنشاء كائن `face_search` — وبالتالي لا يظهر تحذير `NO_FACE_DETECTED` أبداً في استجابة بحث بالوجه ناجحة. يُعاد هذا كرسالة `error` في المستوى الأعلى، وليس ضمن `warnings[]`.

## الإعدادات القابلة للتهيئة

نطاقات التشابه التي تفصل بين التطابقات المؤكدة (`FACE_IN_BLOCKLIST` و`DUPLICATED_FACE`) والتطابقات المحتملة (`POSSIBLE_FACE_IN_BLOCKLIST` و`POSSIBLE_DUPLICATED_FACE`) ثابتة داخلياً — إذ ينطبق ضبط الحدود لكل تطبيق على فحص الحيوية في سير العمل، وليس على هذا الـ endpoint. الخيارات التي يمكنك التحكم فيها لكل طلب هي:

* **`search_type`** (القيمة `most_similar`، الافتراضية | `blocklisted_or_approved`) — يرتب خيار `most_similar` جميع الوجوه المسجلة بحسب درجة التشابه؛ بينما يقصر خيار `blocklisted_or_approved` المرشحين على الوجوه المدرجة في قائمة الحظر، والوجوه المدرجة في قائمة السماح، والوجوه المستخرجة من الجلسات المقبولة، ووجوه ملفات تعريف المستخدمين المستوردة، مع ترتيب المدخلات المدرجة في قائمة الحظر أولاً.
* **`save_api_request`** (القيمة الافتراضية `true`) — يحفظ الاستدعاء كجلسة من نوع API ويسجل الوجه الذي تم البحث عنه في فهرس البحث بالوجه الخاص بك. يتم استبعاد الوجوه المسجلة عبر استدعاءات البحث بالوجه من نتائج البحث بالوجه المستقبلية. عيّنه على `false` للاستعلام دون حفظ أو تسجيل.
* **`rotate_image`** (القيمة الافتراضية `false`) — يجرّب تدويرات للصورة بزاوية 90 درجة ويحتفظ بالاتجاه الذي يحقق أفضل اكتشاف للوجه؛ وهو مفيد عندما تكون بيانات اتجاه EXIF مفقودة.

## أمثلة

### مطابقة في قائمة الحظر (تفرض `Declined`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}
```

### إشارة تكرار (تبقى الحالة `Approved`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}
```

## ذات صلة

* [تقرير البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/report-face-search.md) — شكل الاستجابة الكامل
* [مرجع API للبحث بالوجه](https://docs.didit.me/ar/standalone-apis/face-search.md) — معلمات الطلب
* [تحذيرات مطابقة الوجه](https://docs.didit.me/ar/core-technology/id-verification/warnings-id-verification.md) — تحذيرات المقارنة بنسبة 1:1 بين صورة السيلفي والمستند (منفصلة عن البحث بالوجه)
* [نماذج البيانات — البحث بالوجه](https://docs.didit.me/ar/reference/data-models.md#البحث-بالوجه) — المخطط القياسي

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


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