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

# تقرير البحث بالوجه 1:N: نتائج التطابق بتنسيق JSON

> مرجع تقرير البحث بالوجه 1:N من Didit: معرفات الجلسات المتطابقة، نسب التشابه، إشارات قائمة الحظر، وتفاصيل المستخدم للتحقيق في الاحتيال.

## نظرة عامة

البحث بالوجه هو بحث بيومتري بنسبة **1:N**: تأخذ Didit أكبر وجه تم اكتشافه في `user_image` وتبحث عنه في فهرس البحث بالوجه الخاص بتطبيقك — الوجوه المسجلة من جلسات التحقق، واستدعاءات API المستقلة المحفوظة، وعمليات رفع الوجوه المباشرة في الملف الشخصي للمستخدم، وقوائم الحظر/السماح الخاصة بك. وهو يختلف عن مطابقة الوجه، التي تكون بنسبة **1:1** — تقارن مطابقة الوجه صورة سيلفي بالصورة الشخصية على مستند محدد، بينما يبحث البحث بالوجه عمّا إذا كنا قد رأينا هذا الشخص في أي مكان من قبل.

يجدر بك فهم سلوكين قبل تحليل التقرير:

* **تطابقات قائمة الحظر وحدها هي التي تؤدي إلى الرفض.** تكون قيمة `face_search.status` هي `Declined` فقط عند إطلاق تحذير `FACE_IN_BLOCKLIST` أو `POSSIBLE_FACE_IN_BLOCKLIST`. أما التطابقات المكررة وحدها فترجع `Approved` — افحص `matches` و`warnings`، وليس مجرد `status`.
* **الحفظ والتسجيل الاختياريان.** عندما تكون قيمة `save_api_request=true` (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API ويتم تسجيل الوجه الذي تم البحث عنه في فهرس البحث بالوجه الخاص بك. الوجوه المسجلة بواسطة استدعاءات البحث بالوجه **تُستثنى من نتائج البحث بالوجه المستقبلية**، لذا لن تتطابق عمليات البحث المتكررة مع بعضها البعض أبدًا. مرّر `save_api_request=false` لإجراء استعلام لمرة واحدة: لن يتم تخزين أي شيء ولن يتم تسجيل الوجه.

## أين تظهر النتائج

البحث بالوجه هو API مستقل. وتُعاد نتائج البحث **بشكل متزامن، في استجابة `POST /v3/face-search/` فقط**، ككائن `face_search` فردي في المستوى الأعلى:

```text theme={null}
POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }
```

لا توجد مصفوفة بصيغة الجمع `face_searches[]` في أي مكان — فإن اصطلاح المصفوفات بصيغة الجمع المستخدم في `id_verifications[]` و`aml_screenings[]` و`liveness_checks[]` على endpoint الخاص بقرار الجلسة لا ينطبق هنا.

عندما تكون قيمة `save_api_request=true` (الافتراضية)، يتم حفظ الاستدعاء أيضًا كجلسة من نوع API:

* **Business Console** — تظهر الجلسة في قائمة الجلسات مع صورة البحث والتطابقات والتحذيرات.
* **`GET /v3/session/{sessionId}/decision/`** — يمكن استرجاعها باستخدام `request_id` المُعاد كمعرّف للجلسة. تظهر البيانات المحفوظة كمدخل `FACE_SEARCH` في `features[]` وكعنصر في `liveness_checks[]` يحمل `matches` المخزنة (مع قيم `match_image_url` موقعة حديثًا) و`warnings` — **وليس** ككائن `face_search`.

عندما تكون قيمة `save_api_request=false`، يكون `request_id` معرّف ارتباط UUID مؤقتًا: لا يتم تخزين الجلسة مطلقًا، لذا لا يمكن جلبها من وحدة التحكم أو من endpoint القرار.

## المخطط

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

```typescript theme={null}
interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}
```

ملاحظات الحقول:

* **الحد الأقصى لمصفوفة `matches[]` هو 5** مدخلات أعلى من الحد الأدنى للتشابه، مرتبة تنازليًا حسب التشابه (يرتب `search_type=blocklisted_or_approved` المدخلات المدرجة في قائمة الحظر أولاً، ثم المدرجة في قائمة السماح، ثم حسب التشابه).
* **`source`** يوضح لك المكان الذي تم تسجيل الوجه المتطابق منه: `session` — جلسة تحقق أو استدعاء API مستقل محفوظ؛ `imported` — وجه تم رفعه مباشرة إلى ملف تعريف المستخدم؛ `list_entry` — وجه مرتبط بإحدى قوائمك؛ `retained_template` — [قالب بيومتري](https://docs.didit.me/ar/management-api/biometric-templates/overview.md) خالٍ من الصور احتفظ به التطبيق بعد حذف الجلسة المصدر. تكون قيم `session_id` و`session_number` و`status` و`api_service` هي `null` لتطابقات `imported` و`list_entry` و`retained_template`.
* **تطابقات `retained_template`** تحمل `vendor_user_id` و`vendor_data` و`biometric_template_id`، ودائمًا ما تكون `null` لكل من `match_image_url` و`user_details` وكل ما يتعلق بالجلسة: فالجلسة التي أنشأت الوجه لم تعد موجودة ولا يحتوي القالب على أي صورة أو بيانات هوية. تكون قيمة `is_blocklisted` دائمًا `false` للقالب المحتفظ به؛ ويتم الإبلاغ عن الوجه المدرج في قائمة الحظر بشكل منفصل كتطابق `list_entry`. أزل القالب نهائيًا باستخدام `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** هو نوع API المستقل للجلسة المتطابقة (بأحرف كبيرة، مثل `PASSIVE_LIVENESS`) ويكون `null` عندما يكون الوجه المتطابق قادمًا من جلسة تحقق عادية في سير العمل.
* **`user_details`** يأتي من التحقق من المستند الخاص بالجلسة المتطابقة. بالنسبة لتطابقات `source: imported`، يتم ملؤه من الملف الشخصي للمستخدم بدلاً من ذلك (يتم تعيين `full_name`، وتكون قيمة `document_type`/`document_number` هي null)؛ ويكون `null` عند عدم وجود بيانات هوية (على سبيل المثال جلسات كشف الحيوية فقط).
* **تستخدم التحذيرات شكلاً مصغرًا** مقارنةً بتحذيرات سير العمل: لا يوجد `node_id`. يحدد عقد الاستجابة الموثق (`FaceSearchResponseSerializer`) الحقول الخمسة `risk` و`additional_data` و`log_type` و`short_description` و`long_description`؛ كما يحمل الـ payload في وقت التشغيل حقل `feature` إضافيًا، والذي يكون دائمًا `"LIVENESS"` هنا. راجع [تحذيرات البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/warnings-face-search.md).
* **لا يتم استبعاد تطابقات نفس المستخدم** — على عكس اكتشاف التكرار في سير العمل، لا يقوم الـ endpoint المستقل بتصفية الجلسات السابقة التي تحمل نفس `vendor_data`، لذلك فإن المستخدم الشرعي العائد سيتطابق مع جلساته السابقة.

## قيم الحالة

يتم اشتقاق `face_search.status` في المستوى الأعلى من `warnings[]`. تعكس قيمة `status` على مستوى التطابق نتيجة التحقق من **الجلسة المتطابقة** وهي مستقلة.

| القيمة | متى تظهر |
| - | - |
| `Approved` | لم يتم إطلاق أي تحذير لقائمة الحظر. يشمل ذلك حالة العثور على تطابقات مكررة — فالتطابقات المكررة هي إشارات معلوماتية وليست حالات رفض. |
| `Declined` | تم إطلاق تحذير `FACE_IN_BLOCKLIST` أو `POSSIBLE_FACE_IN_BLOCKLIST` — تطابقت صورة البحث مع وجه في قائمة الحظر الخاصة بك. |

ملاحظة: عندما لا تحتوي صورة البحث على وجه يمكن اكتشافه، يعيد الـ API الرمز HTTP `400` مع `{"error": "No face detected in the image"}` **قبل** إنشاء كائن `face_search` — ولا توجد حالة `Declined` لتلك الحالة. كما يؤدي عدم كفاية الرصيد إلى إرجاع HTTP `403` قبل أي معالجة للصور.

## أمثلة

### Approved — تطابق مكرر، لا وجود لقائمة الحظر

```json theme={null}
{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### Declined — تطابق مع قائمة الحظر

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

## ذات صلة

* [تحذيرات البحث بالوجه](https://docs.didit.me/ar/core-technology/face-search/warnings-face-search.md) — كل رمز تحذير يمكن أن يصدر عن عملية البحث
* [مرجع API الخاص بالبحث بالوجه](https://docs.didit.me/ar/standalone-apis/face-search.md) — معامِلات الطلب وأنماط `search_type`
* [نماذج البيانات — البحث بالوجه](https://docs.didit.me/ar/reference/data-models.md#البحث-بالوجه) — المخطط المعتمد
* [webhook](https://docs.didit.me/ar/integration/webhooks.md) — بيانات payload لـ `status.updated` للجلسات المحفوظة

> [!NOTE]
>
> عندما تكون `save_api_request=true`، تكون قيم `match_image_url` عبارة عن عناوين URL موقّعة وقصيرة الأجل — أعد استدعاء endpoint لقرار الجلسة باستخدام `request_id` المُعاد للحصول على روابط جديدة. وعندما تكون `save_api_request=false`، فإنها تكون مسارات تخزين داخلية وليست قابلة للتنزيل مباشرةً. قم بتخزين معرّف الجلسة المتطابقة، والحالة، و`similarity_percentage` فقط من جانبك — ولا تحتفظ بالصورة البيومترية الأصلية.


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