> ## 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 الحالة، ودرجة الثقة، وطريقة الكشف، وتقدير العمر، ومطابقات الوجه عبر الجلسات، وموقعه في الاستجابات.

## نظرة عامة

يلتقط **تقرير كشف الحيوية** كل ما رصده Didit أثناء التحقق من وجود شخص حقيقي وحي أمام الكاميرا — وليس صورة مطبوعة أو إعادة تشغيل عبر شاشة أو تزييفاً عميقاً. ويتضمن طريقة كشف الحيوية، ودرجة ثقة من 0 إلى 100، وصورة سيلفي مرجعية وفيديو الالتقاط، وتقديراً اختيارياً للعمر، ومقاييس جودة كشف الحيوية السلبي، وتطابقات الوجه عبر الجلسات مع سجل تطبيقك وقائمة الحظر.

يتم إنشاء التقرير بعد أن يكمل المستخدم خطوة كشف الحيوية في سير العمل (أو يستدعي endpoint الوجه المستقل). يُشغّل Didit إحدى طرق كشف الحيوية الثلاث (ثلاثية الأبعاد النشطة، أو الوميض، أو السلبية)، ويحتسب درجات الالتقاط، ويفحص أنماط الانتحال المعروفة، ويقارن الوجه بيومترياً مع كل وجه آخر ظهر في تطبيقك.

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

* **مقبولة** — تم اكتشاف الوجه، ودرجة كشف الحيوية أعلى من حد المراجعة، ولم يتم إطلاق أي تحذير للرفض التلقائي.
* **قيد المراجعة** — تم إطلاق تحذير واحد أو أكثر موجّه للمراجعة، أو أن الدرجة عند حد المراجعة أو أدنى منه ولكنها أعلى من حد الرفض.
* **مرفوضة** — تم إطلاق شرط رفض تلقائي (`NO_FACE_DETECTED`، أو `LIVENESS_FACE_ATTACK`، أو `FACE_IN_BLOCKLIST`، أو مخاطر العمر في مسارات تقدير العمر)، أو تم توجيه تحذير قابل للتهيئة إلى الرفض، أو أن الدرجة عند حد الرفض أو أدنى منه.
* **لم تكتمل** — لم يكمل المستخدم خطوة كشف الحيوية مطلقاً.

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

يظهر تقرير كشف الحيوية كـ `liveness_checks[]` في `GET /v3/session/{sessionId}/decision/` — **دائماً كمصفوفة JSON**، وليس ككائن `liveness` مفرد أبداً. تظهر إدخالات متعددة عندما يُشغّل سير العمل كشف الحيوية أكثر من مرة (على سبيل المثال، فحص أساسي بالإضافة إلى إعادة الالتقاط).

* **API قرار الجلسة** — يُرجع `GET /v3/session/{sessionId}/decision/` مصفوفة `liveness_checks[]` في المستوى الأعلى. راجع [استرداد قرار الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md).
* **webhook** — تتضمن payload الخاصة بـ `session.status.updated` مصفوفة `liveness_checks[]` نفسها بمجرد أن تُنتج الخطوة بيانات. راجع [webhook](https://docs.didit.me/ar/integration/webhooks.md).
* **API كشف الحيوية المستقل** — راجع [API كشف الحيوية المستقل](https://docs.didit.me/ar/standalone-apis/passive-liveness.md).

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

## المخطط

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

| الحقل | النوع | الوصف |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | حالة خطوة كشف الحيوية (انظر أدناه). |
| `node_id` | string \| null | عقدة مخطط سير العمل التي أنتجت هذا التقرير. |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | طريقة كشف الحيوية التي أنتجت هذا الالتقاط. |
| `score` | number 0–100 \| null | درجة الثقة لكشف الحيوية، مقربة إلى منزلتين عشريتين. |
| `reference_image` | string (signed URL) \| null | صورة سيلفي مرجعية مستخرجة من الالتقاط. رابط موقّع مع نافذة صلاحية محدودة. |
| `video_url` | string (signed URL) \| null | فيديو التقاط كشف الحيوية الكامل (الطرق النشطة). رابط موقّع مع نافذة صلاحية محدودة. |
| `age_estimation` | number \| null | العمر المقدر بالسنوات لأكبر وجه في الصورة المرجعية. |
| `face_quality` | number 0–100 \| null | جودة الوجه لكشف الحيوية السلبي، مضبوطة كنسبة مئوية. تُملأ فقط عندما يكون `method = "PASSIVE"`. |
| `face_luminance` | number 0–100 \| null | إضاءة الوجه لكشف الحيوية السلبي، مضبوطة من 0–255 كنسبة مئوية. تُملأ فقط عندما يكون `method = "PASSIVE"`. |
| `matches[]` | array | مطابقات الوجه عبر الجلسات (انظر أدناه). |
| `warnings[]` | array | تحذيرات على مستوى الوحدة — انظر [تحذيرات كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/warnings-liveness.md). يتبع كل إدخال هيكل [كائن التحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير) (`feature`، `risk`، `additional_data`، `log_type`، `short_description`، `long_description`، `node_id`). |

### مطابقات الوجه عبر الجلسات

يسرد `matches[]` الوجوه في سجل تطبيقك التي تجاوزت حد التشابه البيومتري مقارنةً بصورة السيلفي هذه — ما يصل إلى 5 إدخالات، الوجوه المدرجة في قائمة الحظر وقائمة السماح أولاً، ثم بترتيب تنازلي للتشابه. المرشحون المؤهلون هم الوجوه المدرجة في قائمة الحظر، والوجوه المدرجة في قائمة السماح، والوجوه من الجلسات المقبولة (`Approved`)، والوجوه المستوردة لمستخدمي المورّد لديك. تُستبعد الوجوه التي تنتمي إلى نفس المستخدم (نفس `vendor_data`، أو نفس مستخدم المورّد عند توفره) من عملية البحث **بأكملها** — سواء في اكتشاف التكرار أو فحص قائمة الحظر.

يتضمن كل إدخال:

| الحقل | النوع | الوصف |
| - | - | - |
| `session_id` | string (UUID) \| null | الجلسة المطابقة. `null` عندما يكون `source` هو `imported` أو `list_entry`. |
| `session_number` | number \| null | رقم الجلسة التسلسلي للجلسة المطابقة. `null` للمصادر غير المرتبطة بجلسة. |
| `similarity_percentage` | number 0–100 | درجة التشابه البيومتري، محصورة بين 0–100. |
| `vendor_data` | string \| null | بياناتك المرجعية من الجلسة المطابقة (أو مستخدم المورّد، للوجوه المستوردة). |
| `verification_date` | string (ISO 8601) \| null | وقت إنشاء الجلسة المطابقة (أو الوجه المستورد). |
| `user_details` | object \| null | `{ full_name, document_type, document_number }` من KYC للجلسة المطابقة. تُملأ الوجوه المستوردة `full_name` فقط (حقلا المستند يكونان `null`)؛ ويكون `null` عند عدم وجود تفاصيل مسجلة. |
| `match_image_url` | string (signed URL) \| null | الوجه المرجعي من الجلسة المطابقة، أو الوجه المستورد، أو إدخال القائمة. |
| `status` | string \| null | حالة الجلسة المطابقة (مثل `"Approved"`). `null` للمصادر غير المرتبطة بجلسة. |
| `is_blocklisted` | boolean | `true` عندما يكون الوجه المطابق مدرجاً في قائمة حظر الوجوه لديك. |
| `is_allowlisted` | boolean | `true` عندما يكون الوجه المطابق مدرجاً في قائمة سماح الوجوه لديك (يتم تخطي إجراءات الوجه المكرر). |
| `api_service` | string \| null | يتم تعيينه عندما يأتي الوجه المطابق من استدعاء API مستقل (مثل `"PASSIVE_LIVENESS"`)؛ ويكون `null` لجلسات سير العمل والمصادر غير المرتبطة بجلسة. |
| `source` | `"session" \| "imported" \| "list_entry"` | مصدر الوجه المطابق: جلسة تحقق أخرى، أو وجه تم تحميله لمستخدم مورّد، أو وجه من قائمة السماح/الحظر التي تديرها المؤسسة. |

## قيم الحالة

تأتي الحالات من التعداد المشترك لحالات الميزات (`FeatureStatusChoices`).

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

## أمثلة

### مقبولة — التقاط active-3D سليم

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### قيد المراجعة — كشف حيوية سلبي، والتقاط منخفض الجودة، وتكرار محتمل

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

هنا تكون جودة الوجه (12.4) أقل من حد المراجعة الافتراضي (15)، والإضاءة (18.7) أقل من الحد الأدنى الافتراضي (20)، وإجراء الوجه المكرر في سير العمل مضبوط على المراجعة — لذا تحمل التحذيرات الثلاثة `log_type: "warning"` ويستقر التقرير على `In Review`.

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

تُعد مقاطع فيديو وصور السيلفي الخاصة بكشف الحيوية بيانات بيومترية — فالروابط الموقّعة مؤقتة وتنتهي صلاحيتها (بعد 4 ساعات افتراضياً). تعامل معها كعناصر قصيرة الأجل: لا تقم بتخزينها مؤقتاً أو عرضها علناً. عادةً ما يحتاج تطبيقك فقط إلى `status` و`score` والتحذيرات — خزّن أقل قدر ممكن لتقليل البيانات البيومترية على خوادمك.

## ذات صلة

* [تحذيرات كشف الحيوية](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/core-technology/face-match/report-face-match.md) — مطابقة الوجه المرافقة بنسبة 1:1 مع الصورة الشخصية في المستند.


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