الانتقال إلى المحتوى الرئيسي
POST
Python
يوضح هذا الدليل كيفية اختيار مسار الاستيراد المناسب عند نقل بياناتك من مزود آخر إلى Didit. يُطلق العملاء غالباً اسم «استيراد» على مهمتين مختلفتين:
  • استيراد عمليات التحقق التاريخية: إعادة إنشاء سجلات KYC وKYB ومراقبة المعاملات أو سجلات قواعد سير العمل المكتملة، بحيث تعرض Didit سجل المزود السابق. استخدم POST /v3/session/imports/.
  • استيراد بيانات التشغيل: إنشاء المستخدمين والشركات وصور الوجه الشخصية وإدخالات قائمة الحظر أو قائمة السماح، حتى تتمكن Didit من استخدامها في الفحوصات المستقبلية. استخدم واجهات برمجة الكيانات وواجهات الوجوه والقوائم.
تُنشئ عمليات استيراد التحقق سجلات تاريخية بقيمة session_type: "MIGRATED" لـ KYC وKYB. لا ترسل رسائل بريد إلكتروني إلى المستخدمين النهائيين، ولا توجّه المستخدمين إلى التدفق المستضاف، ولا تعيد تشغيل عملية التحقق الأصلية. تظهر السجلات المستوردة في قوائم الجلسات وملفات الكيانات وعروض المعاملات، وفي GET /v3/session/{session_id}/decision/ حيثما ينطبق ذلك.

أيّ مسار استيراد تستخدم؟

إذا كنت تحتاج فقط إلى ملف مستخدم أو شركة للفحوصات المستقبلية، فلا تستورد جلسة تحقق تاريخية. استخدم واجهات برمجة كيانات المستخدم أو الشركة. وإذا كنت تريد أن يظهر قرار المزود السابق أو حقول المستندات أو التحذيرات أو الأدلة كسجل امتثال في Didit، فاستخدم POST /v3/session/imports/.

ما الذي يمكن ترحيله من كل مزوّد

يقبل Didit ملف CSV أو NDJSON بالمخطط القياسي، لذا يمكنك الترحيل من أي مزوّد بعد تصدير البيانات وتحويلها. عقد الاستيراد هو دائماً مخطط Didit القياسي.

سير عمل الترحيل

  1. حدّد ما إذا كنت تستورد السجل التاريخي أو الملفات الشخصية أو الوجوه أو القوائم أو المعاملات أو القواعد.
  2. صدّر البيانات من المزوّد القديم بنفسك. لا ترسل مفاتيح API الخاصة بالمزوّد القديم إلى Didit.
  3. حوّل تصدير المزوّد إلى قالب CSV أو NDJSON المطابق من Didit.
  4. في الترحيلات الكبيرة، فضّل NDJSON وقسّم الملفات إلى ملفات يمكن إعادة محاولتها بشكل مستقل.
  5. أنشئ مهمة الاستيراد واستعلم عن تقدمها.
  6. اجلب أخطاء الصفوف، وأصلح الصفوف الفاشلة فقط، ثم أعد محاولتها. جميع مهام الاستيراد تتمتع بخاصية idempotency على أساس معرّفها الخارجي الطبيعي.

إنشاء مهمة استيراد

أنشئ مهمة استيراد بطلب multipart واحد:
استخدم CSV للترحيلات الأصغر المعتمدة على الجداول، واستخدم NDJSON للترحيلات الكبيرة. بالنسبة لـ 100k+ صف، يكون NDJSON أسهل في البث والتقسيم والتحقق وإعادة المحاولة. يمكن للتطبيق تشغيل ما يصل إلى 4 مهام استيراد في الوقت نفسه، لذا قسّم الترحيل الكبير إلى عدة ملفات، وابدأ مهمة لكل ملف. تُنزّل كل مهمة ملفات الوسائط الخاصة بالصف بالتوازي. والمهمة التي تتوقف بسبب عملية نشر أو إعادة تشغيل للعامل تكمل تلقائياً من آخر صف تم استيراده، لذا لا تحتاج إلى إعادة تشغيلها. بالنسبة لاستيراد المعاملات، احذف workflow_id:

حقول الطلب

كيفية تتبّع السجلات وإزالة التكرار

لا يوجد في الطلب حقل لمصدر البيانات، إذ يستخدم كل استيراد مخطط Didit القياسي. ويحفظ كل سجل مستورد القيمة metadata.imported_from = "generic" لأغراض التتبع. تُزيل استيرادات user_verification وbusiness_verification تكرار الصفوف حسب external_id داخل التطبيق، لذا لن تُنشئ إعادة محاولة الملف نفسه سجلات مكررة. أما استيرادات transactions فتُزيل التكرار حسب transaction_id. يخزّن ترحيل المزوّد (source=provider) كل سجل بالصيغة <provider>:<id>، مثل sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. يُعامَل استيراد ملف التحقق من المستخدمين الذي أرسل المعرّف الخام للمزوّد (5f8c0e2a9b1d4c3e2f1a0b9c) على أنه السجل نفسه في الاتجاهين. لذلك يمكنك بدء الترحيل عبر الملفات وإنهاءه بترحيل المزوّد، أو العكس، دون استيراد أي سجل مرتين.

استيراد صور المستندات والفيديوهات وأدلة السيلفي

بالنسبة إلى import_type=user_verification، يمكنك استيراد صور المستندات الأصلية، وفيديوهات التقاط المستند والحيوية، وصورة سيلفي من المزوّد السابق. استخدم هذه الأعمدة المعيارية: بالنسبة إلى عمليات الترحيل الكبيرة، استخدم روابط HTTPS. تُنزّل Didit كل ملف، وتتحقق من أن الرابط آمن، وتخزّن نسخة مملوكة لـ Didit، وتربطها بالجلسة المستوردة. تُضغط الصور، أما الفيديوهات فتُخزَّن كما هي. يُقبل ترميز base64 المضمّن للصور في عمليات الاستيراد الصغيرة، لكن يجب دائماً تقديم الفيديوهات كروابط URL، لأن base64 سيزيد حجم كل فيديو بنحو 33% وسيتجاوز بسرعة حد الاستيراد لكل ملف. مثال على صف NDJSON يحتوي على روابط وسائط مستضافة لدى المزوّد:
قواعد الوسائط المهمة:
  • يجب أن تستخدم الروابط البروتوكول https.
  • يجب ألا تُحلّ الروابط إلى عناوين IP خاصة أو إلى localhost أو نطاقات الارتباط المحلي أو مضيفي البيانات الوصفية الداخلية.
  • تقبل الصور إما عمود رابط أو بديله *_base64، وإذا تم ضبط الاثنين معاً تكون الأولوية لـ base64. الفيديوهات تُقبل كروابط URL فقط، ولا يوجد عمود *_video_base64.
  • يجب أن تكون الفيديوهات بصيغة mp4 أو webm أو mov، وألا يتجاوز حجم كل فيديو 10 MB. تُرفض الملفات الأكبر أو التي ليست فيديوهات كأخطاء صفوف.
  • تُطبّق Didit مهلات الاتصال والقراءة، وحداً أقصى لحجم الملف، ولا تُعيد المحاولة إلى ما لا نهاية.
  • تُسجَّل إخفاقات تنزيل الوسائط كأخطاء صفوف حتى يستمر باقي الاستيراد.
  • إذا لم تكن لديك وسائط من المزوّد، فاترك هذه الأعمدة فارغة. ستستورد Didit القرار المنظم وحقول المستند على كل حال.
  • الصور والفيديوهات المستوردة أدلة للمراجعة التاريخية. لا تُعيد Didit تشغيل OCR أو تحليل الحيوية أو تحليل احتيال المستندات على الوسائط التاريخية المستوردة بشكل افتراضي.

متابعة التقدم

تتضمن الاستجابة الحقول status وimport_type وtotal_rows وprocessed_rows وcreated_count وupdated_count وskipped_count وfailed_count وcheckpoint_row.

تنزيل أخطاء الصفوف

يتضمن كل خطأ الحقول row_number وexternal_id وerror وraw_row، حتى تتمكن من إصلاح الصفوف الفاشلة فقط وإعادة المحاولة.

الحماية من إساءة الاستخدام

مهام الاستيراد التاريخية عبر POST /v3/session/imports/ معطّلة افتراضياً. تفعّل Didit هذه القدرة لكل مؤسسة بعد المراجعة، لأن هذه المهام قد تعالج ملايين الصفوف وتنزّل الوسائط. أما عمليات الاستيراد العادية لبيانات التشغيل في هذا الدليل، مثل إنشاء المستخدمين، وإنشاء الشركات، ورفع صور الوجه للملفات الشخصية، ورفع قوائم حظر الوجوه، أو إضافة إدخالات القوائم، فلا تتطلب تفعيلاً خاصاً للترحيل، بل تكفيها أذونات مفتاح API العادية، وتوفر المنتج، وحدود المعدل الخاصة بتلك الـ endpoints. تعمل مهام الاستيراد التاريخية أيضاً على عمليات عاملة معزولة مع حدود لحجم الملفات، وحدود لعدد الصفوف، وروابط وسائط HTTPS فقط، وحظر الروابط المؤدية إلى الشبكات الخاصة، وحد أقصى 4 مهام استيراد نشطة لكل تطبيق، وتسجيل أخطاء كل صف على حدة.

الحالات المعيارية

idempotency

تستخدم Didit الحقل external_id مفتاح idempotency للاستيراد في عمليات استيراد التحقق من المستخدمين وعمليات استيراد التحقق من الشركات (KYB)، ضمن نطاق كل تطبيق. أما استيراد المعاملات فيستخدم transaction_id ضمن كل تطبيق. عند إعادة محاولة الملف نفسه، يتم تخطي الصفوف التي استُوردت سابقاً وإنشاء الصفوف التي لم تُعالج بعد.

استيراد المستخدمين وصور الوجه للملفات الشخصية وقوائم الحظر

استخدم هذه المسارات عندما لا تعيد إنشاء جلسة تحقق مكتملة:

استيراد الملفات الشخصية للمستخدمين

أنشئ المستخدمين باستخدام POST /v3/users/create/ أو استيراد CSV في Business Console من Import and Export Users. يؤدي هذا إلى إنشاء ملف VendorUser الشخصي أو تحديثه فقط. ولا يُنشئ جلسة تحقق، أو قرار KYC، أو تقرير مستند، أو تحذيراً، أو سجل webhook. استخدم هذا المسار عندما تريد أن يعرف Didit بوجود العميل قبل عمليات التحقق المستقبلية، أو عندما تحتاج إلى تعبئة حقول شبيهة بحقول CRM مثل display_name والوسوم والبيانات الوصفية بأثر رجعي.

رفع صور الوجه الموثوقة للملف الشخصي

بعد وجود مستخدم، ارفع صورة وجه موثوقة للملف الشخصي باستخدام POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. يُرفق هذا الإجراء الدليل البيومتري بالملف الشخصي للمستخدم ويفهرسه لاكتشاف التكرار والبحث بالوجه. لا يُدرج هذا الإجراء الوجه في قائمة الحظر. وهو مفيد عندما تملك صورة شخصية موثوقة من مزوّد KYC سابق وتريد أن تُقارَن الفحوصات المستقبلية في Didit بها.

استيراد قوائم الحظر والسماح للوجوه

لحظر وجه أو السماح به مباشرة، استخدم POST /v3/lists/{list_uuid}/entries/face-upload/ مع قائمة مخصّصة للوجوه. يستخرج Didit تضمين الوجه البيومتري ويخزّن إدخالاً في القائمة. استخدم هذا المسار لصور المحتالين المعروفين، أو الوجوه المدرجة في قائمة السماح الموثوقة، أو ترحيل قوائم الاحتيال من مزوّد آخر. إذا كان الوجه مأخوذاً من جلسة Didit موجودة، ففضّل POST /v3/lists/{list_uuid}/entries/ مع reference_session_id؛ إذ يستخرج Didit الوجه الصحيح من الجلسة ويربط الإدخال بمصدره.

استيراد قوائم المستخدمين أو الشركات أو المستندات أو المحافظ أو البريد الإلكتروني أو الهاتف أو IP أو الجهاز

استخدم POST /v3/lists/{list_uuid}/entries/ لقيم القوائم غير المتعلقة بالوجوه. هذا هو المسار الصحيح لقوائم الحظر والسماح الواردة من المزوّدين، وقوائم الاسترداد المالي (ردّ المبالغ)، وعناوين المحافظ، وعناوين IP المعروفة بالمخاطر، وبصمات الأجهزة، وأرقام المستندات، وعناوين البريد الإلكتروني، وأرقام الهواتف، والمستخدمين، والشركات.

الخطوات التالية

استيراد المستخدمين

تحميل الملفات الشخصية للمستخدمين وإرفاق صور الوجه الموثوقة بها.

استيراد الشركات

تحميل الملفات الشخصية للشركات قبل تشغيل KYB.

رفع صورة الوجه للملف الشخصي

إرفاق صور وجه موثوقة بالمستخدمين المستوردين.

رفع وجه إلى قائمة

إضافة وجوه إلى قوائم الحظر أو السماح.

إنشاء إدخال في قائمة

استيراد أرقام الهواتف أو عناوين البريد الإلكتروني أو المحافظ أو المستندات أو عناوين IP أو الأجهزة أو المستخدمين أو الشركات إلى القوائم.

حدود المعدل

تصميم حلقات ترحيل آمنة وإعادة المحاولات.

التفويضات

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.

الجسم

import_type
enum<string>
افتراضي:user_verification

ما سيتم استيراده: جلسات التحقق من المستخدمين التاريخية، أو جلسات التحقق من الشركات التاريخية، أو قواعد الحالة المخصصة لسير العمل، أو سجلات مراقبة المعاملات التاريخية.

الخيارات المتاحة:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

معرّف UUID لسير العمل الذي يجب إرفاق الجلسات المستوردة أو قواعد الحالة به. مطلوب لـ user_verification وbusiness_verification وstatus_rules. لا تُدرجه للمعاملات.

source_format
enum<string>

اختياري. يُستنتج من امتداد الملف المرفوع عند حذفه.

الخيارات المتاحة:
csv,
ndjson
file
file

ملف CSV أو NDJSON قياسي. استخدم NDJSON لعمليات الاستيراد الكبيرة. الحد الأقصى لحجم الرفع 25 ميغابايت (استخدم source_file_url للملفات الأكبر). يتعارض مع source_file_url.

source_file_url
string<uri>

بديل لتحميل الملفات. يجب أن يكون رابط HTTPS يوجه إلى عنوان عام (يتم رفض الشبكات الخاصة أو شبكات الاسترجاع). لا يمكن استخدامه مع file.

source
enum<string>

provider يجعل هذا نقلاً من مزود آخر للتحقق من الهوية. احذفه عند استيراد ملف.

الخيارات المتاحة:
file,
provider
provider
enum<string>

مصدر الترحيل، من GET /v3/session/imports/providers/. مطلوب عندما يكون source هو provider.

الخيارات المتاحة:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

المفتاح المخصص للقراءة فقط الخاص بالمزود، بأسماء الحقول التي تسردها credential_fields. مشفر في وضع السكون، ولا يُعاد أبداً، ويتم محوه عند انتهاء الاستيراد. أرسله كسلسلة JSON نصية في multipart.

options
object
status_mapping
object

تعديلات على تعيين الحالة الافتراضي للمزود: من حالة المصدر إلى حالة Didit. يتم تخطي الحالتين Not Finished وAbandoned وحسابهما، ولا يتم استيرادهما أبداً.

dry_run
boolean
افتراضي:false

حساب ما ستستورده عملية الترحيل (حسب الحالة، موجود بالفعل في Didit، نفس الشخص، غير مكتمل) وعدم كتابة أي شيء. تنتهي المهمة بالحالة READY؛ ابدأها باستخدام POST /v3/session/imports/{importId}/start/.

face_templates
boolean
افتراضي:false

إنشاء قوالب بيومترية للوجوه من صور السيلفي المستوردة والبحث عنها ومقارنتها بوجوه التطبيق وقائمة الحظر. يتم وضع علامة على التطابقات للمراجعة فقط. يتطلب lawful_basis_confirmed.

lawful_basis_confirmed
boolean
افتراضي:false

يؤكد أن لديك أساساً قانونياً لمشاركة صور السيلفي هذه مع Didit كمعالج.

الاستجابة

تم قبول مهمة الاستيراد. قم بالاستقصاء الدوري لـ uuid المُعاد حتى تصبح status هي COMPLETED أو FAILED.

uuid
string<uuid>
مطلوب

معرّف مهمة الاستيراد. استخدم هذه القيمة لمتابعة التقدم بشكل دوري وجلب أخطاء الصفوف.

status
enum<string>
مطلوب
الخيارات المتاحة:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
مطلوب
الخيارات المتاحة:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
مطلوب
الخيارات المتاحة:
csv,
ndjson
source_filename
string
مطلوب
total_rows
integer<int64>
مطلوب
processed_rows
integer<int64>
مطلوب
created_count
integer<int64>
مطلوب
updated_count
integer<int64>
مطلوب
skipped_count
integer<int64>
مطلوب
failed_count
integer<int64>
مطلوب
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

حالة المهمة كما تعرضها لوحة التحكم؛ تشير errors إلى مهمة مكتملة تحتوي على صفوف مرفوضة.

الخيارات المتاحة:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
الخيارات المتاحة:
file,
api,
provider
provider
string

مصدر الترحيل؛ فارغ لعمليات الاستيراد عبر الملفات أو API.

provider_options
object
credential_hint
string

الأحرف الأولى من المفتاح الذي يحتفظ به الترحيل. لا يتم إرجاع المفتاح نفسه أبداً.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

عندما تُستأنف تلقائياً مهمة أوقفها حد المعدل لدى المزود مؤقتاً.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

ما وجده التشغيل التجريبي: total، وby_status، وalready_in_didit، وsame_person، وnot_finished، وfailed، وunmapped_statuses.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
آخر تعديل في ٧ نوفمبر ٢٠٢٦