الانتقال إلى المحتوى الرئيسي
POST
cURL

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

multipart/form-data
user_image
file
مطلوب

صورة وجه لشخص حي أو صورة وجه مرشحة للتحقق منها (مثل صورة سيلفي). أرسل صورة أمامية واحدة مع ظهور وجه الشخص بوضوح وإضاءة جيدة. الامتدادات المسموح بها: tiff، jpg، jpeg، png، webp. أقصى حجم للرفع: 5 MB (تُرفض الملفات الأكبر بـ 400). يتم ضغط الصور تلقائيًا إلى ~0.5 MB قبل المعالجة، لذا فإن الدقة العالية جدًا لا تُحسّن الدقة.

ref_image
file
مطلوب

صورة وجه مرجعية للمقارنة معها (مثل صورة مستند الهوية أو صورة مسجلة مسبقاً). نفس قيود التنسيق والحجم الخاصة بـ user_image.

face_match_score_decline_threshold
number<float>
افتراضي:30

حد التشابه (0–100) الذي يحدد status في الاستجابة. تؤدي الدرجة المحسوبة المساوية لهذه القيمة أو الأقل منها إلى تعيين status على Declined وإضافة تحذير LOW_FACE_MATCH_SIMILARITY؛ وتُرجع الدرجة الأعلى منها تماماً حالة Approved. القيمة الافتراضية 30 متساهلة — ارفعها (على سبيل المثال 50–60) لإجراء تحقق أكثر صرامة. تُرجع القيم خارج النطاق 0–100 الرمز 400.

النطاق المطلوب: 0 <= x <= 100
مثال:

50

rotate_image
boolean
افتراضي:false

عندما تكون true، تجرب الخدمة صور الإدخال بزيادات قدرها 90 درجة (0، 90، 180، 270) وتستخدم الاتجاه الذي يحقق أفضل كشف للوجه — مفيد للصور الملتقطة عبر الهاتف مع فقدان اتجاه EXIF. يضيف تأخيراً في الاستجابة، لذا لا تفعّله إلا إذا كنت لا تستطيع ضمان أن تكون الصور بالاتجاه الصحيح للأعلى.

مثال:

false

save_api_request
boolean
افتراضي:true

عندما تكون القيمة true (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر GET /v3/session/{sessionId}/decision/ باستخدام request_id المُرجع، ويتم الإشعار بها عبر webhook لحدث status.updated. عندما تكون القيمة false، لا يتم تخزين أي شيء ويكون request_id عبارة عن معرّف UUID مؤقت للربط بالاستجابة فقط.

مثال:

true

vendor_data
string

سلسلة نصية مبهمة اختيارية (معرّف المستخدم الداخلي لديك، البريد الإلكتروني، UUID...) تُخزَّن في الجلسة المحفوظة وتُعاد في الاستجابة. استخدمها لربط استدعاءات API بسجلاتك الخاصة ولتصفية الجلسات لاحقاً.

مثال:

"user-123"

metadata
object

كائن JSON اختياري يُخزن مع الجلسة (عندما يكون save_api_request=true) ويُعاد في الاستجابة. في طلبات multipart، أرسله كحقل سلسلة نصية بترميز JSON (مثل metadata={"flow":"login"}) — حيث يتم تحليله إلى كائن.

مثال:

الاستجابة

تم احتساب مطابقة الوجه. الخاصية face_match.score عبارة عن رقم عشري بين 0 و100 (بمنزلتين عشريتين)؛ وتكون الحالة status هي Approved عندما تكون الدرجة أعلى تماماً من face_match_score_decline_threshold، وإلا فتكون Declined مع تحذير توضيحي. إذا كان الزوج ذا تشابه منخفض أو تعذر احتساب درجته فإنه يظل يُرجع 200 — تحقّق من face_match.status وface_match.warnings، وليس من رمز HTTP فقط. عندما تكون save_api_request=true، يكون request_id هو معرّف الجلسة المحفوظة.

request_id
string<uuid>

معرّف الجلسة المحفوظة عندما تكون save_api_request=true (يمكن استخدامه مع GET /v3/session/{sessionId}/decision/)؛ وإلا فسيكون UUID ارتباط مؤقت.

face_match
object
vendor_data
string | null

نسخة مطابقة من vendor_data التي أرسلتها، أو null.

metadata
object | null

نسخة مطابقة من كائن metadata الذي أرسلته، أو null.

created_at
string<date-time>

طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة، مثل 2026-06-12T01:04:42.763237+00:00.

آخر تعديل في ٧ نوفمبر ٢٠٢٦