الانتقال إلى المحتوى الرئيسي
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 (لا يُسمح بملفات PDF). الحد الأقصى لحجم الرفع: 5 MB (تُرفض الملفات الأكبر حجماً برمز 400). تُضغط الصور تلقائياً إلى نحو 0.3 MB قبل المعالجة، لذا فإن الدقات العالية جداً لا تزيد من الدقة.

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

حد كشف الحيوية (0–100). تضيف قيمة score الخاصة بكشف الحيوية التي تكون عند أو أقل من هذه القيمة تحذير LOW_LIVENESS_SCORE ويتم الرفض. ارفعها لمكافحة أكثر صرامة للانتحال؛ تُرجع القيم خارج النطاق 0–100 الخطأ 400.

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

30

age_estimation_decline_threshold
integer
افتراضي:18

الحد الأدنى المقبول للعمر التقديري بالسنوات. العمر التقديري الأقل من هذه القيمة يضيف تحذير AGE_BELOW_MINIMUM ويؤدي إلى الرفض. عيّن 0 لتعطيل التحقق من العمر (يقوم الاستدعاء بعد ذلك بتشغيل كشف الحيوية + تقدير العمر فقط دون اتخاذ قرار بناءً على العمر).

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

18

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":"age-gate"}) — حيث يتم تحليله إلى كائن.

مثال:

الاستجابة

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

request_id
string<uuid>

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

age_estimation
object
vendor_data
string | null

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

metadata
object | null

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

created_at
string<date-time>

طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة.

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