الانتقال إلى المحتوى الرئيسي
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 قبل المعالجة، لذا فإن دقة الصور العالية جداً لا تحسّن دقة النتائج. يجب أن تحتوي الصورة على وجه واحد قابل للاكتشاف على الأقل — وإلا فسيُرجع endpoint الرمز 400. عند وجود عدة وجوه، يتم البحث عن الوجه الأكبر ويُضاف تحذير MULTIPLE_FACES_DETECTED.

search_type
enum<string>
افتراضي:most_similar

سياسة البحث. يقوم most_similar (الافتراضي) بترتيب كل وجه مسجل في تطبيقك حسب درجة التشابه. بينما يقصر blocklisted_or_approved المرشحين على الوجوه المدرجة في قائمة الحظر، والوجوه المدرجة في القائمة المسموح بها، والوجوه من الجلسات المقبولة، والوجوه المستوردة من الملفات التعريفية للمستخدمين — مع ترتيب الإدخالات المدرجة في قائمة الحظر أولاً.

الخيارات المتاحة:
most_similar,
blocklisted_or_approved
مثال:

"most_similar"

rotate_image
boolean
افتراضي:false

عندما تكون true، تجرب الخدمة تدوير الإدخال بزيادات قدرها 90 درجة وتستخدم الاتجاه الذي يحقق أفضل كشف للوجه. مفيد عند فقدان اتجاه EXIF. يضيف تأخيراً في الاستجابة.

مثال:

false

save_api_request
boolean
افتراضي:true

عندما تكون true (الافتراضي)، يتم حفظ الاستدعاء كجلسة من نوع API، وإرسال webhook من نوع status.updated، وتوقيع قيم match_image_url مسبقاً، وتسجيل الوجه الذي تم البحث عنه في فهرس البحث بالوجه الخاص بك (تُستثنى عمليات تسجيل البحث بالوجه من عمليات البحث المستقبلية). عندما تكون false، يكون البحث لمرة واحدة فقط — لا يتم تخزين أي جلسة ولا يتم تسجيل الوجه.

مثال:

true

vendor_data
string

معرّف مبهم اختياري (معرّف المستخدم لديك، البريد الإلكتروني، UUID...) يتم تخزينه في الجلسة المحفوظة وإعادته. لا يستبعد وجوه نفس المستخدم من نتائج البحث.

مثال:

"user-123"

metadata
object

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

مثال:

الاستجابة

اكتمل البحث بالوجه. يحتوي الحقل face_search.matches على ما يصل إلى 5 وجوه مشابهة مرتبة حسب درجة التشابه؛ وتشير المصفوفة الفارغة إلى عدم تجاوز أي وجه مُسجّل للحد الأدنى من التشابه. تكون الحالة status هي Declined فقط عند التطابق مع قائمة الحظر — أما التطابقات المكررة وحدها فترجع Approved، لذا تحقّق من matches وwarnings، وليس من status فقط. عندما تكون save_api_request=true، يكون request_id هو معرّف الجلسة المحفوظة. يحمل كل تطابق source (سواء session، أو imported، أو list_entry، أو retained_template)، وvendor_user_id، وbiometric_template_id؛ ويأتي التطابق من نوع retained_template من قالب بيومتري خالٍ من الصور يتم الاحتفاظ به بعد حذف الجلسة المصدرية وتكون حقول الجلسة وmatch_image_url وuser_details الخاصة به بقيمة null.

request_id
string<uuid>

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

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.

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