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

> حلّل استجابات المصادقة البيومترية في Didit، بما فيها كشف الحيوية ومطابقة الوجه الاختيارية مع صورة مخزنة، والنتائج تُعاد عبر liveness_checks وface_matches.

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

![Didit biometric authentication report combining liveness check and face match against a stored portrait](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/biometric-auth-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=c02e5558780972797d4b2feea685bc73)

## نظرة عامة

المصادقة البيومترية هي نوع من أنواع سير العمل (`workflow_type: "biometric_authentication"`)، وليست كائن استجابة منفصلاً. عندما يتم تشغيل سير العمل، فإنه يُصدر:

* **فحص حيوية** واحدًا يلتقط صورة سيلفي مباشرة ويحتسب درجة احتمالية الانتحال لها.
* **مطابقة وجه** واحدة تقارن الوجه الملتقط بالوجه المرجعي المحدد عند إنشاء الجلسة (فقط عند تفعيل مطابقة الوجه في سير العمل).

كلما تضمن سير العمل مطابقة الوجه، تتطلب عملية إنشاء الجلسة وجهاً مرجعياً. أرسل `portrait_image` (صورة مرمزّة بـ base64، بحد أقصى 2MB)، أو اتركها وستعيد Didit استخدام الوجه المخزن مسبقاً للمستخدم المرتبط بـ `vendor_data`: وجه الحيوية المقبول أولاً، ثم صورة شريحة جواز السفر الإلكتروني (ePassport)، ثم الصورة الشخصية من مستند الهوية، ثم وجه الملف الشخصي المُسجّل يدوياً. إذا لم تكن `portrait_image` ولا الوجه المخزن متاحين، فإن إنشاء الجلسة يُرجع رمز الخطأ `400` مع `{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}`. في كلتا الحالتين، يتم تسجيل المرجع المحدد تحت الجلسة الجديدة، لذا يتم تعيين `source_image_session_id` لعنصر مطابقة الوجه على `session_id` الخاص بتلك الجلسة نفسها (يوضح لك ذلك أن المرجع جاء من الصورة الشخصية المخزنة للجلسة بدلاً من صورة شخصية لمستند تم التقاطها في الجلسة نفسها، والتي كانت ستترك الحقل كـ `null`).

## أين يظهر

| مفتاح استجابة القرار | الجمع | مخطط العنصر |
| - | - | - |
| `liveness_checks[]` | عنصر واحد لكل خطوة حيوية (عادةً 1 في المصادقة البيومترية) | [data-models#liveness-check](https://docs.didit.me/ar/reference/data-models.md#فحص-الحيوية) |
| `face_matches[]` | عنصر واحد لكل خطوة مطابقة وجه (`null` في سير العمل المقتصر على الحيوية فقط) | [data-models#face-match](https://docs.didit.me/ar/reference/data-models.md#مطابقة-الوجه) |

يتم إرجاع كلا المصفوفتين بواسطة [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/ar/sessions-api/retrieve-session) للجلسات التي يكون نوع سير العمل فيها هو `biometric_authentication`. تكونان دائماً مصفوفتين — وليستا كائنات مفردة أبداً — وتكون كل منهما `null` حتى تُنتج خطوتها بيانات. يحمل كل عنصر `node_id` حتى يتمكن سير العمل متعدد المثيلات من التمييز بين الخطوات.

## مرجع المخطط

تُحدَّد القائمة الكاملة للحقول مرة واحدة في صفحة نماذج البيانات بحيث تشترك جميع التقارير التي تعرض هذه الميزات في مصدر موثوق واحد:

* [مخطط عنصر الحيوية](https://docs.didit.me/ar/reference/data-models.md#فحص-الحيوية) — `status`، و`method`، و`score`، و`reference_image`، و`video_url`، و`age_estimation`، و`matches[]`، و`face_quality`، و`face_luminance`، و`warnings[]`، و`node_id`.
* [مخطط عنصر مطابقة الوجه](https://docs.didit.me/ar/reference/data-models.md#مطابقة-الوجه) — `status`، و`score`، و`source_image_session_id`، و`source_image`، و`target_image`، و`warnings[]`، و`node_id`.
* [شكل مدخلات التحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير) — `feature`، و`risk`، و`additional_data`، و`log_type`، و`short_description`، و`long_description`، و`node_id`.

## قيم الحالة

يستخدم كل من `liveness_checks[].status` و`face_matches[].status` دورة حياة الميزة المشتركة ([الحالات على مستوى الميزة](https://docs.didit.me/ar/reference/data-models.md#حالات-مستوى-الميزة)):

| الحالة | المعنى |
| - | - |
| `Not Finished` | لم تُنتج الخطوة نتيجة نهائية بعد (لم يُكملها المستخدم، أو تسرّب). قبل أن تبدأ الخطوة على الإطلاق، تكون مصفوفتها ببساطة `null` في استجابة القرار. |
| `Approved` | اجتاز الفحص جميع الحدود المضبوطة. |
| `In Review` | وقعت الدرجة ضمن نطاق المراجعة، أو تم ضبط تحذير قابل للتكوين ليتحول إلى مراجعة. |
| `Declined` | وقعت الدرجة عند حد الرفض أو دونه، أو تم إطلاق تحذير رفض تلقائي (هجوم على الوجه، لم يتم اكتشاف أي وجه، الوجه مدرج في قائمة الحظر، لا توجد صورة مرجعية لمطابقة الوجه). |
| `Resub Requested` | طلب المراجِع من المستخدم إعادة محاولة هذه الخطوة. |

تجمع حالة `status` الإجمالية للجلسة كلا العنصرين: أي ميزة بحالة `Declined` تؤدي إلى رفض الجلسة، وأي ميزة بحالة `In Review` تضع الجلسة في `In Review`، وخلاف ذلك تكون `Approved` (بعد اكتمال كل ميزة).

لمعرفة سلوك الحدود والقائمة الكاملة لرموز التحذيرات، راجع [تحذيرات المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/warnings-biometric-authentication.md).

## مثال — الحيوية + مطابقة الوجه (مقبولة)

الأمثلة موجزة: يحمل غلاف القرار الكامل أيضاً `session_url`، و`metadata`، و`callback`، و`reviews`، و`contact_details`، و`expected_details`، و`environment`، و`created_at`، و`expires_at`.

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}
```

## مثال — الحيوية فقط (مطابقة الوجه معطلة في سير العمل)

```json theme={null}
{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "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": []
    }
  ],
  "face_matches": null
}
```

وضع الحيوية فقط هو تكوين في سير العمل: عند تعطيل مطابقة الوجه، لا يلزم وجود وجه مرجعي عند إنشاء الجلسة ويبقى `face_matches` كـ `null`. وعندما **تكون** مطابقة الوجه مفعلة، فإن ترك `portrait_image` لا يُحوّل الجلسة إلى وضع الحيوية فقط: بل تعيد Didit استخدام الوجه المخزن للمستخدم المرتبط بـ `vendor_data`، وإذا لم يكن هناك وجه مخزن، يفشل إنشاء الجلسة بالرمز `400`.

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

```json theme={null}
{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "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": "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"
        }
      ]
    }
  ]
}
```

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

تُعد `reference_image` و`video_url` و`source_image` و`target_image` عناوين URL موقعة تنتهي صلاحيتها بعد فترة زمنية محدودة (4 ساعات افتراضياً). وهي تشير إلى بيانات بيومترية — لا تقم بتخزينها مؤقتاً أو عرضها للعامة. قم بتخزين نتيجة التحقق (الحالة، والدرجة، و`source_image_session_id`) في جانبك؛ وأعد استدعاء endpoint الخاص بالقرار إذا كنت بحاجة إلى عناوين URL جديدة.

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

> [card] [تحذيرات المصادقة البيومترية](https://docs.didit.me/ar/core-technology/biometric-auth/warnings-biometric-authentication.md)
>
> رموز التحذيرات والحدود وشروط الرفض التلقائي.

> [card] [تقرير الحيوية](https://docs.didit.me/ar/core-technology/liveness/report-liveness.md)
>
> مرجع الحقول الكامل لعناصر `liveness_checks[]`.

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


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