تقرير كشف الحيوية: درجة الثقة، الطريقة والمطابقات

نظرة عامة

يلتقط تقرير كشف الحيوية كل ما رصده 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[] في المستوى الأعلى. راجع استرداد قرار الجلسة.
webhook — تتضمن payload الخاصة بـ session.status.updated مصفوفة liveness_checks[] نفسها بمجرد أن تُنتج الخطوة بيانات. راجع webhook.
API كشف الحيوية المستقل — راجع API كشف الحيوية المستقل.

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

المخطط

يوجد المخطط المعتمد حقلاً بحقل في صفحة مرجع نماذج البيانات. تعكس الحقول أدناه هذا المخطط المعتمد.

الحقل	النوع	الوصف
`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	تحذيرات على مستوى الوحدة — انظر تحذيرات كشف الحيوية. يتبع كل إدخال هيكل كائن التحذير (`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`	طلب المراجِع إعادة إرسال هذه الخطوة من لوحة التحكم.	مؤقتة — يتم استبدالها بمجرد قيام المستخدم بإعادة الالتقاط.

أمثلة

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

{
  "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 والتحذيرات — خزّن أقل قدر ممكن لتقليل البيانات البيومترية على خوادمك.

المصادقة

التحقق

المراقبة

المنصة

تقرير كشف الحيوية: درجة الثقة، الطريقة والمطابقات

نظرة عامة

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

المخطط

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

قيم الحالة

أمثلة

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

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

ملاحظة أمنية

ذات صلة

​نظرة عامة

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

​المخطط

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

​قيم الحالة

​أمثلة

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

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

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

​ذات صلة

نظرة عامة

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

المخطط

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

قيم الحالة

أمثلة

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

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

ملاحظة أمنية

ذات صلة