> ## 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:1 عبر API: صورة السيلفي بمستند الهوية

> قارن صورة سيلفي بمستند الهوية مع Didit. دفع بالطلب مقابل $0.05، و$10 مجاناً شهرياً، ودرجة تطابق بأقل من 2s لعمليات KYC والتسجيل.

تقارن ميزة مطابقة الوجه (Face Match) من Didit بين وجهين بنسبة 1:1، وعادةً ما تتم المقارنة بين صورة سيلفي مأخوذة من فحص كشف الحيوية والصورة الشخصية الموجودة على مستند هوية المستخدم، وتعيد درجة تشابه تتراوح بين 0 و100. وتحدد الحدود التي تضبطها ما إذا كان الفحص ناجحاً؛ وترفض واجهة برمجة التطبيقات المستقلة `POST /v3/face-match/` أي درجة تبلغ 30 أو أقل بشكل افتراضي.في درس Didit Academy حول قراءة نتيجة التحقق، يغطي الفصل عند الدقيقة 6:16 فحص مطابقة الوجه داخل جلسة حقيقية.[Face match — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

موجه تكامل مطابقة الوجه
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

POST https://verification.didit.me/v3/face-match/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

\# See also
\- Canonical schema: /reference/data-models#face-match
\- Per-feature report: /core-technology/face-match/report-face-match
\- Risk catalogue: /core-technology/face-match/warnings-face-match
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

الصق في

![نظرة عامة على خطوات التحقق من الهوية](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## إعادة المحاولة والملاحظات القابلة للتنفيذفي جلسة Didit، فإن عملية مطابقة الوجه التي تفشل بسبب **سبب التقاط يمكن إصلاحه** (مثل كون صورة سيلفي مظلمة للغاية، أو ضبابية، أو غير متمركزة، أو أن نسبة التشابه على حافة القبول) لا تؤدي إلى الرفض الفوري. يُطلب من المستخدم **إعادة المحاولة مع إرشادات توجيهية**، حتى عدد محدد من المحاولات القابلة للتهيئة — وهو نفس النموذج المستخدم في [كشف الحيوية](https://docs.didit.me/ar/core-technology/liveness/overview.md).* **رصيد المحاولات** — يتحكم `face_match_max_attempts` في إجمالي عدد عمليات إرسال مطابقة الوجه لكل جلسة. القيمة الافتراضية هي **3** (محاولة أولية واحدة بالإضافة إلى محاولتي إعادة)، وهي قابلة للتهيئة لكل عقدة سير عمل (النطاق 1–3).

* **ملاحظات إعادة المحاولة** — طالما بقيت محاولات متاحة، فإن الفشل القابل لإعادة المحاولة يُبقي المستخدم في نفس الخطوة ويعيد `feedback_codes` (تعرض حزم SDK للويب وللهواتف المحمولة هذه الرموز كرسائل توجيهية تلقائياً):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **استنفاد المحاولات** — بمجرد استنفاد الرصيد المتاح، يتم تطبيق الحالة المحسوبة (`Declined` أو `In Review`).> [!NOTE]
>
> تنطبق إعادة المحاولة على **مسار الجلسة** فقط. أما endpoint المستقل `POST /v3/face-match/` فهو عديم الحالة ويعمل بمحاولة واحدة فقط — حيث يعيد درجة التشابه مباشرة دون أي رصيد لإعادة المحاولة.## كيف يعمل**1. الالتقاط الذكي**ابدأ عملية التحقق بكل سهولة من خلال نظام الالتقاط السهل الاستخدام والمدعوم بالذكاء الاصطناعي.يقوم المستخدمون بتحميل مستندات الهوية أو تصويرها مع مساعدة في الوقت الفعلي:| الميزة | الوصف |
| - | - |
| **الكشف التلقائي** | يتعرف على نوع المستند ودولة الإصدار تلقائياً |
| **إرشادات في الوقت الفعلي** | إشارات مرئية لتحقيق أفضل وضعية وإضاءة وتركيز |
| **الالتقاط الذكي** | التقاط تلقائي عندما تصبح الظروف مثالية — دون الحاجة إلى إعادة المحاولة يدوياً |
| **دعم واسع** | جوازات السفر، ورخص القيادة، وبطاقات الهوية الوطنية، وتصاريح الإقامة |> [!NOTE]
>
> *أهمية هذه الميزة*: يقلل نظام الالتقاط الذكي لدينا من الصعوبات التي تواجه المستخدم ويضمن عمليات إرسال عالية الجودة من المحاولة الأولى، مما يعزز معدلات التحويل والثقة.**2. معالجة البيانات المتقدمة**استخرج بيانات الهوية وتحقق منها بدقة لا مثيل لها.**استخراج البيانات** — تعالج التقنيات المتطورة جميع الحقول الأساسية:| القدرة | التفاصيل |
| - | - |
| **استخراج الحقول** | الاسم الكامل، وتاريخ الميلاد، ورقم المستند، وتواريخ الإصدار/الانتهاء، والجنسية، والمزيد |
| **OCR** | تقنية التعرف الضوئي على الحروف عالية الدقة للنصوص |
| **تحليل MRZ** | تحليل المنطقة المقروءة آلياً وفك تشفير الباركود |**التحقق من صحة البيانات**:* مطابقة البيانات بين المناطق المرئية، وMRZ، والباركود للتأكد من اتساقها
* مطابقة التنسيق والأنماط لاكتشاف أي حالات شاذة
* استعلامات في الوقت الفعلي عبر قواعد البيانات الحكومية (حيثما كان ذلك مسموحاً) للتحقق الموثوق> [!NOTE]
>
> *أهمية هذه الميزة*: تضمن المعالجة الشاملة للبيانات الدقة وتزيل الأخطاء، مما يمنحك الثقة في كل عملية تحقق.**3. التحليل المتقدم**يقوم نظامنا المدعوم بالذكاء الاصطناعي بإجراء فحوصات شاملة:- التحقق من أصالة المستند
- اكتشاف التلاعب وتحليل سلامة الصورة
- التحقق من ميزات الأمان (الصور المجسمة، والعلامات المائية، وما إلى ذلك)
- مطابقة القالب مع قاعدة بيانات معتمدةيمنع **كشف حيوية المستند** الاحتيال الناتج عن:| نوع الهجوم | الوصف |
| - | - |
| **لقطات الشاشة** | مستندات رقمية ملتقطة من شاشة |
| **إعادة عرض على شاشة** | صور لمستندات معروضة على شاشات |
| **النسخ المطبوعة** | نسخ مادية من المستندات الأصلية |
| **الصور الشخصية المعدلة** | مستندات تم التلاعب بها عبر استبدال الصور أو تعديلها |**4. نتائج وتكامل سلس**احصل على رؤى قابلة للتنفيذ على الفور مع خيارات تسليم مرنة.**نتائج في الوقت الفعلي**:| القناة | الوصف |
| - | - |
| **لوحة التحكم** | تحديثات فورية عبر لوحة تحكم سهلة الاستخدام |
| **webhook** | إشعارات webhook فورية لمهام سير العمل المؤتمتة |
| **REST API** | تكامل سلس مع أنظمتك الحالية |**تقارير شاملة**:* تقارير PDF مفصلة تحتوي على نتائج التحقق والأدلة
* سجلات تدقيق للامتثال وحفظ السجلات
* خيارات قابلة للتخصيص لتتوافق مع متطلباتك التشغيلية> [!NOTE]
>
> *أهمية هذه الميزة*: تتيح النتائج السريعة وسهلة الوصول لفريقك اتخاذ الإجراءات بسرعة مع الحفاظ على عملية آمنة وقابلة للتدقيق.***## متطلبات المستندلتحقيق أفضل نسبة نجاح للتحقق، يجب أن تستوفي المستندات هذه المعايير:#### المتطلبات العامة- صادر عن جهة حكومية وصالح ضمن فترة الصلاحية المحددة له
- سليم مادياً (خالٍ من التلف أو الخدوش أو البقع التي قد تحجب التفاصيل)
- جميع المعلومات الأساسية (الاسم الكامل، تاريخ الميلاد، MRZ، وغيرها) مقروءة بوضوح
- اتساق البيانات عبر جميع المستندات المقدمة#### متطلبات الصورة- صورة أصلية ملتقطة في الوقت الفعلي (ليست لقطات شاشة أو نسخاً ممسوحة ضوئياً أو نسخاً رقمية)
- الصيغ المدعومة: JPG، JPEG، PNG، PDF
- الحجم الأقصى للملف: 5MB
- صورة ملونة بالكامل مع ظهور جميع زوايا المستند
- خالية من الوهج، أو الظلال، أو التعديل الرقمي، أو التلاعب
- يلزم تقديم مستندات مادية (لا تُدعم الهويات الرقمية إلا في مناطق محددة يُعترف بها فيها رسمياً)## إعدادات إضافية حسب الدولة ونوع المستنداضبط قواعد دقيقة حسب الدولة ونوع المستند مباشرةً من لوحة التحكم. تتيح لك عناصر التحكم هذه تخصيص معايير القبول وتفضيلات النسخ وفقاً لاحتياجات الامتثال لديك.![لوحة الإعدادات المتقدمة لمطابقة الوجه من Didit لحدود التشابه وقواعد القبول](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **وضع انتهاء الصلاحية**: اختر كيفية التعامل مع المستندات ذات تواريخ الانتهاء الماضية.
  * **رفض المستندات المنتهية الصلاحية**: إذا كان تاريخ انتهاء المستند يسبق اليوم، فسيتم تمييزه بأنه منتهي الصلاحية ورفضه.
  * **السماح بالمستندات المنتهية الصلاحية**: عدم تمييز أو حظر المستندات ذات تاريخ الانتهاء الماضي.
* **تنسيق الأحرف المفضل**: حدد كيفية تطبيع الأسماء والحقول المستخرجة.
  * **تفضيل الأحرف اللاتينية (A–Z)**: مثال: "Mohammed"
  * **تفضيل نظام الكتابة الأصلي (غير اللاتيني)**: مثال: "محمد"
* **الدعم الإقليمي والأنواع الفرعية**: قم بتمكين المستندات حسب المنطقة وحدد الأنواع الفرعية المقبولة عندما يحتوي نوع المستند على تنويعات متعددة.
  * مثال: بالنسبة لرخص القيادة في الولايات المتحدة، حدد الأنواع الفرعية الدقيقة التي تقبلها (على سبيل المثال، Arizona Commercial Driver License وIndiana Operator License (REAL ID) وNew York Enhanced Driver License وما إلى ذلك).
  * استخدم عنصر التحكم "الأنواع الفرعية المقبولة" لتضمين/استبعاد العديد من التنويعات بسرعة (على سبيل المثال، "تم تحديد 128").> نصيحة: تنطبق هذه الإعدادات حسب الدولة ونوع المستند، بحيث يمكنك أن تكون صارماً في بعض الأسواق وأكثر تساهلاً في أسواق أخرى.


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