تقرير المصادقة البيومترية: مخطط JSON

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

Didit biometric authentication report combining liveness check and face match against a stored portrait

نظرة عامة

المصادقة البيومترية هي نوع من أنواع سير العمل (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
`face_matches[]`	عنصر واحد لكل خطوة مطابقة وجه (`null` في سير العمل المقتصر على الحيوية فقط)	data-models#face-match

يتم إرجاع كلا المصفوفتين بواسطة GET /v3/session/{sessionId}/decision/ للجلسات التي يكون نوع سير العمل فيها هو biometric_authentication. تكونان دائماً مصفوفتين — وليستا كائنات مفردة أبداً — وتكون كل منهما null حتى تُنتج خطوتها بيانات. يحمل كل عنصر node_id حتى يتمكن سير العمل متعدد المثيلات من التمييز بين الخطوات.

مرجع المخطط

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

مخطط عنصر الحيوية — status، وmethod، وscore، وreference_image، وvideo_url، وage_estimation، وmatches[]، وface_quality، وface_luminance، وwarnings[]، وnode_id.
مخطط عنصر مطابقة الوجه — status، وscore، وsource_image_session_id، وsource_image، وtarget_image، وwarnings[]، وnode_id.
شكل مدخلات التحذير — feature، وrisk، وadditional_data، وlog_type، وshort_description، وlong_description، وnode_id.

قيم الحالة

يستخدم كل من liveness_checks[].status وface_matches[].status دورة حياة الميزة المشتركة (الحالات على مستوى الميزة):

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

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

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

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

{
  "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
}

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

{
  "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.

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

{
  "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 جديدة.

تحذيرات المصادقة البيومترية

رموز التحذيرات والحدود وشروط الرفض التلقائي.

تقرير الحيوية

مرجع الحقول الكامل لعناصر liveness_checks[].

تقرير مطابقة الوجه

مرجع الحقول الكامل لعناصر face_matches[].

المصادقة

التحقق

المراقبة

المنصة

تقرير المصادقة البيومترية: مخطط JSON

نظرة عامة

أين يظهر

مرجع المخطط

قيم الحالة

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

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

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

ملاحظة أمنية

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

تحذيرات المصادقة البيومترية

تقرير الحيوية

تقرير مطابقة الوجه

​نظرة عامة

​أين يظهر

​مرجع المخطط

​قيم الحالة

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

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

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

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

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

تحذيرات المصادقة البيومترية

تقرير الحيوية

تقرير مطابقة الوجه

نظرة عامة

أين يظهر

مرجع المخطط

قيم الحالة

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

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

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

ملاحظة أمنية

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