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

# تقرير مطابقة الوجه: درجة التشابه بتنسيق JSON

> تعرّف على تقرير مطابقة الوجه 1:1 من Didit: الحالة، درجة التشابه، روابط الصور، والتحذيرات ومكان ظهور البيانات في استجابات API.

## نظرة عامة

يسجل **تقرير مطابقة الوجه** مقارنة بيومترية بنسبة 1:1 بين صورة السيلفي الحية الملتقطة أثناء كشف الحيوية وصورة مرجعية — وغالباً ما تكون الصورة الشخصية المستخرجة من مستند الهوية. ويُرجع درجة تشابه واحدة من 0 إلى 100، وعناوين URL موقّعة للصورتين اللتين تمت مقارنتهما، وجلسة المصدر للصورة المرجعية، وأي تحذيرات ناتجة عن المطابقة.

يتم إصدار التقرير بعد إكمال المستخدم لكل من خطوة كشف الحيوية وخطوة المستند في سير العمل (أو، بالنسبة لمهام سير العمل القائمة على الصور الشخصية مثل المصادقة البيومترية، بعد كشف الحيوية وحده)، أو مباشرة عبر [Face Match API](https://docs.didit.me/ar/standalone-apis/face-match.md) المستقلة عندما تقدم صورتَي وجه اعتباطيتين بنفسك.

يحمل كل تقرير حالة `status` خاصة به — مستقلة عن حالة الجلسة الإجمالية — وتوضح كيفية حسم خطوة مطابقة الوجه وحدها:

* **مقبولة** — الـ `score` أعلى من حد المراجعة ولم يتم إطلاق أي تحذير رفض تلقائي.
* **قيد المراجعة** — الـ `score` بين حدي الرفض والمراجعة، أو تعذر احتساب الدرجة وكانت قيمة `face_match_not_computed_action` هي `REVIEW`.
* **مرفوضة** — الـ `score` عند حد الرفض أو أدنى منه، أو تم إطلاق `NO_REFERENCE_IMAGE`، أو تعذر احتساب الدرجة وكانت قيمة `face_match_not_computed_action` هي `DECLINE`.
* **مطلوب إعادة التقديم** — طلب المراجع من المستخدم إعادة تقديم هذه الخطوة عبر لوحة التحكم.
* **لم تكتمل** — لم تنتج خطوة مطابقة الوجه أي نتيجة بعد (بما في ذلك أثناء محاولة المستخدم إعادة الالتقاط بعد فشل سابق).

## أين تظهر في استجابات API

يأتي تقرير مطابقة الوجه داخل مصفوفة `face_matches[]` — وهي **دائماً مصفوفة JSON**، وليست كائن `face_match` مفرداً على الإطلاق. وتكون قيمتها `null` حتى تنتج خطوة مطابقة وجه واحدة على الأقل بيانات، وتظهر عناصر متعددة عندما يشغّل سير العمل مطابقة الوجه أكثر من مرة. كما يقوم سير عمل [Adaptive Age Verification](https://docs.didit.me/ar/core-technology/age-estimation/overview.md#تقدير-العمر-التكيفي) بتعبئتها أيضاً عند تشغيل مسار التحقق من الهوية البديل: حيث يبلغ ذلك العنصر عن عقدة تقدير العمر كـ `node_id` خاص بها، نظراً لأن سير العمل لا يحتوي على عقدة Face Match خاصة به.

* **API قرار الجلسة** — يُرجع `GET /v3/session/{sessionId}/decision/` مصفوفة `face_matches[]` في المستوى الأعلى. راجع [استرداد قرار الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md).
* **Webhooks** — تتضمن كائنات payload لحدث `session.status.updated` نفس مصفوفة `face_matches[]` بمجرد أن تنتج الخطوة بيانات. راجع [Webhooks](https://docs.didit.me/ar/integration/webhooks.md).
* **Face Match API المستقلة** — لإجراء مقارنات مباشرة بنسبة 1:1، راجع [Face Match standalone API](https://docs.didit.me/ar/standalone-apis/face-match.md).

> [!NOTE]
>
> اقرأ `response.face_matches[0]` وقم بالتكرار عبر المصفوفة — فهيكل `face_match` المفرد الذي أشارت إليه بعض الشروحات القديمة غير موجود في endpoint القرار للإصدار v3.

## المخطط

يوجد المخطط المعتمد حقلاً بحقل في صفحة مرجع [نماذج البيانات](https://docs.didit.me/ar/reference/data-models.md#مطابقة-الوجه). تعكس الحقول أدناه ذلك المخطط المعتمد.

| الحقل | النوع | الوصف |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | حالة خطوة مطابقة الوجه (`FeatureStatusChoices`). |
| `node_id` | string \| null | عقدة مخطط سير العمل التي أنتجت هذا التقرير. |
| `score` | number 0–100 \| null | درجة التشابه البيومتري، مقربة إلى منزلتين عشريتين. تكون `null` عندما لا تكون المقارنة ممكنة. |
| `source_image_session_id` | string \| null | معرّف UUID للجلسة التي وفّرت صورتها الشخصية المخزنة الصورة المرجعية (المصدر) — يتم ضبطه في التدفقات القائمة على الصور الشخصية (المصادقة البيومترية، أو صورة شخصية قُدّمت عند إنشاء الجلسة). وتكون `null` عندما تكون الصورة المرجعية هي الصورة الشخصية للمستند الملتقطة في نفس الجلسة. |
| `source_image` | string (signed URL) | الصورة المرجعية (غالباً ما تكون الصورة الشخصية في المستند). عنوان URL موقّع قصير الأجل — قم بتنزيله على الفور، ولا تخزّن عنوان URL مطلقاً. |
| `target_image` | string (signed URL) | الصورة المستهدفة (غالباً ما تكون صورة السيلفي لكشف الحيوية). عنوان URL موقّع قصير الأجل — قم بتنزيله على الفور، ولا تخزّن عنوان URL مطلقاً. |
| `warnings[]` | array | تحذيرات على مستوى الوحدة. يحمل كل إدخال `feature` (دائماً `"FACEMATCH"`)، و`risk`، و`additional_data`، و`log_type`، و`short_description`، و`long_description`، و`node_id` — راجع [تحذيرات مطابقة الوجه](https://docs.didit.me/ar/core-technology/face-match/warnings-face-match.md). |

## قيم الحالة

| الحالة | المعنى | التأثير اللاحق |
| - | - | - |
| `Approved` | الدرجة أعلى من حد المراجعة ولم يتم إطلاق أي تحذير رفض تلقائي. | تُحتسب كعملية مطابقة وجه ناجحة. |
| `In Review` | الدرجة أعلى من حد الرفض ولكنها عند حد المراجعة أو أدنى منه، أو تعذر احتساب الدرجة (`FACE_MATCH_NOT_COMPUTED`، على سبيل المثال بعد فحص لا يستند إلى مستند لم يترك أي مرجع) مع تعيين `face_match_not_computed_action` إلى `REVIEW`. | تنتقل الجلسة أيضاً إلى `In Review` حتى يتخذ المراجِع إجراءً. |
| `Declined` | الدرجة عند حد الرفض أو أدنى منه، أو تم إطلاق `NO_REFERENCE_IMAGE`، أو تعذر احتساب الدرجة مع تعيين `face_match_not_computed_action` إلى `DECLINE`. | يتم رفض الجلسة ما لم يستوفِ فرع معتمد آخر متطلبات سير العمل. |
| `Resub Requested` | طلب مراجع إعادة تقديم هذه الخطوة من لوحة التحكم. | يُطلب من المستخدم التقاط الصورة مرة أخرى. |
| `Not Finished` | لم تنتج خطوة مطابقة الوجه نتيجة (كان أحد المدخلات مفقوداً، أو لم يصل سير العمل إلى خطوة المقارنة، أو لا يزال المستخدم داخل حلقة إعادة محاولة الالتقاط). | لم يكتمل الفرع. |

تتم إعادة محاولة حالات الفشل الناتجة عن انخفاض التشابه قبل أن تستقر الحالة: يحصل المستخدم على ما يصل إلى `face_match_max_attempts` من محاولات الالتقاط (3 افتراضياً)، ويتم تطبيق درجة المحاولة الأخيرة فقط. يمكن لقواعد الحالة المخصصة التي تم تكوينها على عقدة سير العمل تعديل الحالة الناتجة بشكل إضافي، مع الدمج مع الحالة المستمدة من الدرجة وفق أسبقية `Declined` > `In Review` > `Approved`.

## أمثلة

### مقبولة — مطابقة سليمة

```json theme={null}
{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}
```

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

```json theme={null}
{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.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_1"
        }
      ]
    }
  ]
}
```

### مرفوضة — لا توجد صورة مرجعية للمقارنة بها

```json theme={null}
{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "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"
        }
      ]
    }
  ]
}
```

## ملاحظة أمنية

عناوين URL الموقّعة لـ `source_image` و`target_image` تمثل بيانات بيومترية وتنتهي صلاحيتها بعد فترة صلاحية قصيرة. تعامل معها على أنها قصيرة الأجل: لا تقم بالتخزين المؤقت لها أو عرضها علناً. عادةً ما يحتاج تطبيقك فقط إلى `status` و`score` — قم بتخزين أقل قدر ممكن لتقليل البيانات البيومترية على خوادمك.

## ذات صلة

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


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