عمليات المستخدمين: إنشاء مستخدمي البائع وإدارتهم

تتم إدارة كيان المستخدم الأساسي عبر endpoints عامة تحت /v3/users/. أما مرفقات الملف الشخصي، مثل رفع الوجه المستورد، فتستخدم مسار المؤسسة/التطبيق مع didit_internal_id. تقدم لك هذه الصفحة شرحاً مفاهيمياً، راجع مرجع API للاطلاع على المخططات الكاملة للطلبات والاستجابات.

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

GET /v3/users/ يُرجع قائمة مقسّمة إلى صفحات بالمستخدمين في تطبيقك. يدعم عوامل تصفية حسب الحالة والبحث ونطاق التاريخ وغيرها.

curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"

حالات الاستخدام:

مزامنة مجموعة فرعية من المستخدمين مع مستودع البيانات لديك يومياً.
العثور على المستخدمين المُعلَّمين لقائمة انتظار المحللين.
البحث عن المستخدمين بالاسم المعروض.

الحصول على مستخدم

GET /v3/users/{vendor_data}/ استرجع مستخدماً واحداً عبر vendor_data. يُرجع نموذج البيانات كاملاً مع العدادات المجمّعة.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

قيمة vendor_data في عنوان URL حساسة لحالة الأحرف. مرّر دائماً القيمة الدقيقة التي استخدمتها عند إنشاء الجلسة.

إنشاء مستخدم

POST /v3/users/create/ أنشئ كيان مستخدم قبل بدء أي جلسة. مفيد في:

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

curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'

إذا كان هناك مستخدم بقيمة vendor_data هذه موجوداً بالفعل، يُرجع الطلب خطأ تعارض، فاستخدم PATCH للتحديث بدلاً من ذلك. يمكنك أيضاً إرسال بيانات الاتصال: first_name وlast_name (يُدمجان في full_name عندما لا ترسل قيمة له)، وemail، وphone_number، وcountry. تخزّن Didit الحقلين email وphone_number في metadata.contact، والحقل country في metadata.address. لدعوة الشخص إلى التحقق في الطلب نفسه، أضف send_verification_link: true مع email وworkflow_id. تنشئ Didit جلسة تحقق للشخص على سير العمل هذا وترسل إليه الرابط عبر البريد الإلكتروني. يتضمن الحقل verification_link في الاستجابة القيم session_id وsession_number وstatus وurl وworkflow_id وemail الخاصة بالجلسة، ويكون null عندما لا تطلب رابطاً. راجع إنشاء مستخدم للاطلاع على عمليات التحقق والأخطاء.

رفع وجه مستورد

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ أرفق صورة وجه موثوقة بملف مستخدم موجود. هذه هي الخطوة اللاحقة المناسبة عندما تستورد مستخدمين من مزوّد آخر وتريد أن تحمل Didit أدلة وجوههم قبل أول جلسة في Didit.

# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

راجع رفع وجه المستخدم للاطلاع على حقول الطلب والحدود endpoint الخاصة بالعرض والحذف، والفرق بينه وبين قائمة الحظر.

تحديث مستخدم

PATCH /v3/users/{vendor_data}/ حدّث حقول الملف الشخصي القابلة للتعديل. معظم الحقول المشتقة من الجلسات المُتحقَّق منها للقراءة فقط، ومحاولة تغييرها عبر PATCH إما أن تُتجاهل أو تُوسَم في سجل التدقيق. الحقول القابلة للتعديل: display_name وmetadata وtags. للقراءة فقط بعد التحقق: full_name وdate_of_birth وportrait_image وجميع العدادات المجمّعة وخريطة features.

curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

يُرسِل حدث webhook user.data.updated يتضمن المصفوفة changed_fields.

تغيير الحالة

PATCH /v3/users/{vendor_data}/update-status/ انقل المستخدم بين ACTIVE وFLAGGED وBLOCKED. تنتقل تغييرات الحالة إلى الجلسات والمعاملات المستقبلية.

curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'

من → إلى	المحفّز الشائع
`ACTIVE` → `FLAGGED`	قاعدة معاملات، مراجعة المحلل، تطابق AML مستمر
`ACTIVE` → `BLOCKED`	احتيال مؤكد، إدخال يدوي في قائمة الحظر، تطابق مع قائمة الحظر
`FLAGGED` → `ACTIVE`	أنهى المحلل المراجعة
`BLOCKED` → `ACTIVE`	رفع الحظر يدوياً من قبل محلل

يُرسِل حدث webhook user.status.updated.

حذف المستخدمين (دفعات)

POST /v3/users/delete/ احذف مستخدماً واحداً أو أكثر. تُحذف سجلات المستخدمين نهائياً، مع جميع القوالب البيومترية المحفوظة لهم بعد حذف الجلسة. لا يشمل هذا endpoint جلسات التحقق الخاصة بهم، إذ تبقى هذه الجلسات مع مسح ارتباطها بالمستخدم؛ احذفها باستخدام حذف الجلسة أو حذف الجلسات بالدفعات. المعاملات غير مشمولة أيضاً، فاحذفها من Console.

curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'

حدّد المستخدمين عبر vendor_data_list أو didit_internal_id_list أو عبر الاثنين معاً؛ أو مرّر delete_all: true لحذف كل المستخدمين في التطبيق. تُرفض معاملات الدفعات filter_* الخاصة بـ Console هنا بخطأ 400 بدلاً من تجاهلها، حتى لا تتحول نية محددة أبداً إلى حذف شامل. يُرجع عدداً، {"deleted": <int>}، وليس نتيجة لكل عنصر. تُتجاهل المعرّفات التي لم تطابق أي شيء دون إشعار، لذا أرسل قائمة خالية من التكرار إذا أردت مقارنة deleted بعدد المعرّفات التي أرسلتها.

نموذج الأذونات

تنتمي مفاتيح API إلى تطبيق واحد. يمكن للمفتاح السري الأساسي ومفاتيح الوصول الكامل استدعاء كل endpoint من /v3/users/* في ذلك التطبيق، بما في ذلك delete. يحتاج مفتاح API محدود النطاق إلى صلاحية الأشخاص (users): القراءة لنقاط endpoint من نوع GET، والكتابة للإنشاء والتحديث وتغيير الحالة والحذف. يتطلب إنشاء مستخدم باستخدام send_verification_link: true أيضاً صلاحية الكتابة في الجلسات، لأنه ينشئ جلسة ويرسل رابطها بالبريد الإلكتروني. يُرجع المفتاح الذي يفتقر إلى الصلاحية المطلوبة الرمز 403. لا يمكن لمفتاح مقيّد ببعض سير العمل أو بالجلسات المقبولة الوصول إلى endpoints /v3/users/* إطلاقاً. الأدوار مفهوم خاص بـ Console: مورد الإذن users ومطالباته تحدد ما يمكن لعضو الفريق فعله في Console، ولا تُقيَّم في طلبات مفاتيح API. راجع الأدوار والأذونات للاطلاع على هذه المصفوفة. لمنع خدمة ما من حذف المستخدمين، امنحها مفتاحاً بصلاحية الأشخاص للقراءة فقط، أو بدون أي صلاحية للأشخاص.

حدود المعدل وidempotency

تخضع كل endpoint من /v3/users/* لـحدود المعدل القياسية.
لا تتسم create بخاصية idempotency، فإعادة المحاولة بالقيمة vendor_data نفسها تُرجع خطأ تعارض. أزِل التكرار من جهتك، أو نفّذ GET دائماً أولاً.
تتسم delete بخاصية idempotency، فحذف مستخدم محذوف مسبقاً لا يُحدث أي تغيير.

أحداث webhook التي تُطلقها هذه العمليات

العملية	Webhook
`create`	لا يوجد webhook لعملية الإنشاء نفسها، ويصل أول حدث `user.data.updated` عندما تملأ جلسة أو عملية تحديث الحقول الشخصية للمرة الأولى
`update`	`user.data.updated` (مع `changed_fields`)
`update-status`	`user.status.updated`
`delete`	لا يوجد. سجّل عملية الحذف في نظامك إن احتجت إلى الاستجابة لها

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

نموذج البيانات

المرجع الكامل للحقول.

واجهة API للقائمة

مخطط GET /v3/users/.

واجهة API للإنشاء

مخطط POST /v3/users/create/.

رفع الوجه

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

نظرة عامة

الأسعار

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

المراجعة والعمليات

الكيانات (المستخدمون والشركات)

الإعدادات والتخصيص

الأمان والامتثال

Didit Academy

الموارد

عمليات المستخدمين: إنشاء مستخدمي البائع وإدارتهم

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

الحصول على مستخدم

إنشاء مستخدم

رفع وجه مستورد

تحديث مستخدم

تغيير الحالة

حذف المستخدمين (دفعات)

نموذج الأذونات

حدود المعدل وidempotency

أحداث webhook التي تُطلقها هذه العمليات

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

نموذج البيانات

واجهة API للقائمة

واجهة API للإنشاء

رفع الوجه

​عرض المستخدمين

​الحصول على مستخدم

​إنشاء مستخدم

​رفع وجه مستورد

​تحديث مستخدم

​تغيير الحالة

​حذف المستخدمين (دفعات)

​نموذج الأذونات

​حدود المعدل وidempotency

​أحداث webhook التي تُطلقها هذه العمليات

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

نموذج البيانات

واجهة API للقائمة

واجهة API للإنشاء

رفع الوجه

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

الحصول على مستخدم

إنشاء مستخدم

رفع وجه مستورد

تحديث مستخدم

تغيير الحالة

حذف المستخدمين (دفعات)

نموذج الأذونات

حدود المعدل وidempotency

أحداث webhook التي تُطلقها هذه العمليات

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