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

نظرة عامة

يسجل تقرير مطابقة الوجه مقارنة بيومترية بنسبة 1:1 بين صورة السيلفي الحية الملتقطة أثناء كشف الحيوية وصورة مرجعية — وغالباً ما تكون الصورة الشخصية المستخرجة من مستند الهوية. ويُرجع درجة تشابه واحدة من 0 إلى 100، وعناوين URL موقّعة للصورتين اللتين تمت مقارنتهما، وجلسة المصدر للصورة المرجعية، وأي تحذيرات ناتجة عن المطابقة. يتم إصدار التقرير بعد إكمال المستخدم لكل من خطوة كشف الحيوية وخطوة المستند في سير العمل (أو، بالنسبة لمهام سير العمل القائمة على الصور الشخصية مثل المصادقة البيومترية، بعد كشف الحيوية وحده)، أو مباشرة عبر Face Match API المستقلة عندما تقدم صورتَي وجه اعتباطيتين بنفسك. يحمل كل تقرير حالة 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 بتعبئتها أيضاً عند تشغيل مسار التحقق من الهوية البديل: حيث يبلغ ذلك العنصر عن عقدة تقدير العمر كـ node_id خاص بها، نظراً لأن سير العمل لا يحتوي على عقدة Face Match خاصة به.

API قرار الجلسة — يُرجع GET /v3/session/{sessionId}/decision/ مصفوفة face_matches[] في المستوى الأعلى. راجع استرداد قرار الجلسة.
Webhooks — تتضمن كائنات payload لحدث session.status.updated نفس مصفوفة face_matches[] بمجرد أن تنتج الخطوة بيانات. راجع Webhooks.
Face Match API المستقلة — لإجراء مقارنات مباشرة بنسبة 1:1، راجع Face Match standalone API.

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

المخطط

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

الحقل	النوع	الوصف
`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` — راجع تحذيرات مطابقة الوجه.

قيم الحالة

الحالة	المعنى	التأثير اللاحق
`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.

أمثلة

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

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

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

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

المصادقة

التحقق

المراقبة

المنصة

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

نظرة عامة

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

المخطط

قيم الحالة

أمثلة

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

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

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

ملاحظة أمنية

ذات صلة

​نظرة عامة

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

​المخطط

​قيم الحالة

​أمثلة

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

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

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

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

​ذات صلة

نظرة عامة

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

المخطط

قيم الحالة

أمثلة

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

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

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

ملاحظة أمنية

ذات صلة