> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة إدارة التحقق API v3: سير العمل والفوترة

> اضبط سير العمل والاستبيانات والمستخدمين والفوترة وقوائم الحظر في Didit عبر مفتاح API. جاهزة للوكلاء وMCP، وتسعير حسب الاستخدام بلا عقود.

## المصادقة

تستخدم جميع نقاط نهاية واجهة الإدارة البرمجية مفتاح API الخاص بتطبيقك. لا حاجة إلى معرّفات UUID للمؤسسة أو التطبيق في عناوين URL، إذ يُحدَّد التطبيق من مفتاحك.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...
```

ليس لديك مفتاح API بعد؟ [سجّل برمجياً باستدعاءين من API](https://docs.didit.me/ar/integration/programmatic-registration.md).

***

## سير العمل

يحدد سير العمل خطوات التحقق التي يمر بها مستخدموك (مسح الهوية، وكشف الحيوية، ومطابقة الوجه، وفحص AML، وغيرها). كل سير عمل إعداد قابل لإعادة الاستخدام تربطه بالجلسات.

**GET /v3/workflows/** `GET`

اعرض جميع سير العمل في تطبيقك. يعيد ميزات كل سير عمل وعتباته وما إذا كان هو الافتراضي.

**POST /v3/workflows/** `POST`

أنشئ سير عمل جديداً. حدّد ميزات التحقق المراد تفعيلها، واضبط العتبات، وأعدّ أنواع المستندات المقبولة، وغير ذلك.

**GET /v3/workflows/\{uuid}/** `GET`

احصل على التفاصيل الكاملة لسير عمل محدد، بما في ذلك إعدادات جميع الميزات والعتبات.

**PATCH /v3/workflows/\{uuid}/** `PATCH`

حدّث إعدادات سير العمل. يمكنك تعديل أي إعداد ميزة أو أي عتبة أو المستندات المقبولة.

**DELETE /v3/workflows/\{uuid}/** `DELETE`

احذف سير عمل. لا تتأثر الجلسات التي تستخدم سير العمل هذا بالحذف.

> [!WARNING]
>
> نوصي بشدة باستخدام **وحدة تحكم الأعمال** لإنشاء سير العمل وإعداده. يوفر منشئ سير العمل المرئي القوالب، والإعداد بالسحب والإفلات لميزات التحقق، وإعدادات المستندات، وضبط العتبات، والمعاينة، كل ذلك دون كتابة أي شيفرة. استخدم واجهة البرمجة للأتمتة أو لإدارة سير العمل برمجياً فقط.

### مثال سريع: إنشاء سير عمل

يحدد `workflow_type` مجموعة الميزات الأساسية. ثم تُفعَّل الميزات الفردية أو تُعطَّل بواسطة الأعلام `is_*_enabled`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'
```

قيم `workflow_type` المتاحة: `kyc`، `kyb`، `adaptive_age_verification`، `biometric_authentication`، `address_verification`، `questionnaire_verification`، `email_verification`، `phone_verification`.

في سير عمل `kyc`، يُضمَّن التحقق من الهوية تلقائياً، ولا تحتاج إلى علم منفصل له. استخدم أعلام `is_*_enabled` لإضافة الميزات الاختيارية أو إزالتها، مثل مطابقة الوجه، وكشف الحيوية، وAML، وNFC، والهاتف، والبريد الإلكتروني، وإثبات العنوان، وتحليل الجهاز وعنوان IP، وغيرها.

ثم استخدم سير العمل عند إنشاء الجلسات:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'
```

***

## الاستبيانات

نماذج مخصصة يمكنك إضافتها إلى سير عمل التحقق لجمع معلومات إضافية من المستخدمين.

**GET /v3/questionnaires/** `GET`

اعرض جميع الاستبيانات.

**POST /v3/questionnaires/** `POST`

أنشئ استبياناً جديداً بأسئلة مخصصة ومنطق تفرّع وترجمات.

**GET /v3/questionnaires/\{uuid}/** `GET`

احصل على تفاصيل الاستبيان، بما في ذلك جميع الأسئلة وبنية النموذج.

**PATCH /v3/questionnaires/\{uuid}/** `PATCH`

حدّث الاستبيان.

**DELETE /v3/questionnaires/\{uuid}/** `DELETE`

احذف الاستبيان.

***

## المستخدمون

أدِر الأفراد الذين تم التحقق منهم (المستخدمين) في تطبيقك. يُعرَّف كل مستخدم بسلسلة `vendor_data` تزوّدنا بها عند إنشاء الجلسات.

**GET /v3/users/** `GET`

اعرض جميع المستخدمين في تطبيقك، بما في ذلك حالة التحقق وسجل الجلسات.

**GET /v3/users/\{vendor\_data}/** `GET`

احصل على تفاصيل المستخدم باستخدام معرّف vendor\_data الخاص بك.

**PATCH /v3/users/\{vendor\_data}/** `PATCH`

حدّث البيانات الوصفية للمستخدم.

**POST /v3/users/delete/** `POST`

احذف المستخدمين دفعة واحدة. نص الطلب: `{"vendor_data_list": ["user-1", "user-2"]}` أو `{"delete_all": true}`. كما يمسح جميع القوالب البيومترية المحفوظة لهؤلاء المستخدمين.

***

## القوالب البيومترية

قوالب بيومترية للوجه خالية من الصور، يحتفظ بها التطبيق الذي فعّل خيار الاحتفاظ بها بعد حذف الجلسات. راجع [القوالب البيومترية](https://docs.didit.me/ar/management-api/biometric-templates/overview.md).

**GET /v3/biometric-templates/** `GET`

قائمة مُقسّمة إلى صفحات مع عوامل تصفية (`vendor_data`، `vendor_user_uuid`، `status`، `source_type`، `retained_from`، `retained_to`، `ordering`).

**GET /v3/biometric-templates/count/** `GET`

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

**GET /v3/biometric-templates/\{template\_uuid}/** `GET`

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

**DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE`

امسح قالباً واحداً نهائياً. يُرجع `{"uuid": "...", "outcome": "purged" | "already_purged"}`.

**POST /v3/biometric-templates/delete/** `POST`

مسح جماعي. نص الطلب: `{"template_uuids": [...]}` أو `{"delete_all": true}` مع عوامل تصفية اختيارية.

***

## عمليات الجلسات

**POST /v3/sessions/delete/** `POST`

احذف الجلسات دفعة واحدة. يتطلب `delete:sessions`. نص الطلب: `{"session_numbers": ["1", "2", "3"]}` أو `{"delete_all": true}` (قيّد `delete_all` بعوامل تصفية قائمة الجلسات التي تسبقها `filter_`، مثل `filter_status`)، إضافةً إلى الحقول الاختيارية `retain_face_embeddings` و`face_retention_days` و`face_retention_deadline` و`deletion_instruction` و`instruction_id`. تُرجع ما يصل إلى 20 جلسة مطابقة مع الاستجابة `200` ومع `face_retention_outcome` لكل جلسة. أما إذا زاد العدد على ذلك، فتُرجع الاستجابة `202` مع مهمة حذف.

**GET /v3/sessions/delete/\{job\_id}/** `GET`

تقدّم عملية حذف الجلسات الجماعية التي أعادت `202` وأعداد نتائجها.

**GET /v3/sessions/\{uuid}/reviews/** `GET`

اعرض المراجعات وسجل النشاط للجلسة.

**POST /v3/sessions/\{uuid}/reviews/** `POST`

أضف ملاحظة مراجعة أو تغيير حالة إلى الجلسة.

***

## الفوترة

**GET /v3/billing/balance/** `GET`

الحصول على رصيد الاعتمادات الحالي وإعدادات إعادة التعبئة التلقائية.

```json theme={null}
{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}
```

**POST /v3/billing/top-up/** `POST`

إنشاء جلسة دفع في Stripe لشحن الرصيد. تتراوح كل عملية شحن بين \$50 و\$20,000، وتُضاف بقيمتها الاسمية.

```json theme={null}
{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}
```

***

## القوائم (قوائم الحظر وقوائم السماح والقوائم المخصصة)

إدارة القوائم المصنّفة حسب النوع لحظر العناصر والسماح بها وإنشاء شروط مخصصة لسير العمل. راجع [وثائق واجهة برمجة تطبيقات القوائم الكاملة](https://docs.didit.me/ar/management-api/lists/overview.md).

**GET /v3/lists/** `GET`

عرض جميع القوائم الخاصة بالتطبيق (قوائم الحظر، وقوائم السماح، والقوائم المخصصة).

**POST /v3/lists/\{list\_uuid}/entries/** `POST`

إضافة عنصر إلى قائمة. يدعم `reference_session_id` لاستخراج البيانات تلقائياً من جلسة، و`reference_object_uuid` لتتبع الارتباط بالمعاملات أو المستخدمين أو الشركات.

**DELETE /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE`

إزالة عنصر من قائمة.

**POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST`

رفع صورة وجه إلى قائمة حظر الوجوه (بصيغة base64).

***

## إعدادات webhook

**GET /v3/webhook/** `GET`

الحصول على الإعدادات الحالية لـ webhook، بما في ذلك عنوان URL والإصدار والمفتاح السري للتحقق من توقيعات webhook، وسياسة الاحتفاظ بالبيانات وسياسة الاحتفاظ بالقوالب البيومترية الخاصة بالتطبيق.
تتضمن الاستجابة أيضاً `allowed_domains`، وهو موصوف ضمن `PATCH /v3/webhook/` أدناه.

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}
```

**PATCH /v3/webhook/** `PATCH`

تحديث عنوان URL الخاص بـ webhook أو الإصدار، أو تدوير المفتاح السري. اضبط `rotate_secret_key: true` لإنشاء سر جديد لـ webhook (يُبطل القديم فوراً). كما يضبط سياسة الاحتفاظ الخاصة بالتطبيق: `data_retention_months`، و`face_retention_policy` (القيمة الافتراضية `delete_with_session`، أو `retain_until_user_deleted`) مع `face_retention_days` إلزامي بقيمة نهائية محددة (من 1 إلى 3650) عند تفعيل الاحتفاظ. راجع [الاحتفاظ بالقوالب البيومترية](https://docs.didit.me/ar/console/data-retention.md#الاحتفاظ-بالقالب-البيومتري). كما يسجّل `allowed_return_hosts`: ما يصل إلى 20 اسم مضيف مجرّداً (على سبيل المثال `app.example.com`، دون مخطط أو منفذ أو مسار أو حرف بدل)، يجوز لعملية تحقق عبر [واجهة برمجة تطبيقات محفظة الهوية الرقمية](https://docs.didit.me/ar/standalone-apis/digital-id-wallets.md#سجّل-وجهة-العودة-الخاصة-بك) إعادة الشخص إليها عبر HTTPS. تحلّ القائمة الجديدة محل القائمة المسجلة، ويبقى نطاق العلامة البيضاء الخاص بتطبيقك مسموحاً به دائماً.

كما يضبط `allowed_domains`: ما يصل إلى 50 أصل ويب (على سبيل المثال `https://app.example.com`) يجوز تضمين تدفق التحقق المستضاف فيها، ويجوز لها إعادة المستخدم إليها باستخدام `callback` الخاص بالجلسة.
يتكون كل إدخال من مخطط ومضيف ومنفذ اختياري، دون مسار أو استعلام أو حرف بدل.
استخدم `https`؛ ولا يُقبل `http` إلا لـ `localhost` و`127.0.0.1` و`::1`.
تخزّن Didit كل أصل بحروف صغيرة ودون المنفذ الافتراضي، وتعيد القائمة في `allowed_domains`.
يؤدي الإدخال غير الصالح إلى خطأ 400 عند ضبط `allowed_domains`.
تحلّ القائمة الجديدة محل القائمة المسجلة، وتزيل القائمة الفارغة القيد.
طالما القائمة غير فارغة، ترفض [`POST /v3/session/`](https://docs.didit.me/ar/sessions-api/create-session) قيمة `callback` للويب الواقعة خارجها بالخطأ 400، ولا تعيد صفحة التحقق المستضافة توجيه المستخدم إلى callback مخزّن أو افتراضي لسير العمل خارجها.
لا تتأثر مخططات الروابط المخصصة (روابط التطبيقات العميقة) ولا استدعاءات API من الخادم إلى الخادم.

إذا أرسلت `endpoints`، فسيتم حذف كل وجهة webhook لا تتضمنها القائمة بشكل دائم، مع سر التوقيع الخاص بها وسجل التسليم كاملاً، تماماً كما في [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/ar/management-api/webhook/delete-destination).
لا يمكن التراجع عن ذلك.
لإدارة الوجهات واحدة تلو الأخرى، استخدم [endpoints الخاصة بوجهات webhook](https://docs.didit.me/ar/management-api/webhook/list-destinations.md) بدلاً من ذلك.

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}
```

***

## ملخص endpoint الكامل لواجهة API

| Endpoint | الطريقة | الوصف |
| - | - | - |
| `/v3/session/` | POST | إنشاء جلسة تحقق |
| `/v3/sessions/` | GET | عرض جميع الجلسات |
| `/v3/session/{id}/decision/` | GET | الحصول على نتيجة التحقق للجلسة |
| `/v3/session/{id}/update-status/` | PATCH | قبول الجلسة أو رفضها |
| `/v3/session/{id}/delete/` | DELETE | حذف جلسة واحدة |
| `/v3/sessions/delete/` | POST | حذف الجلسات دفعة واحدة |
| `/v3/sessions/delete/{job_id}/` | GET | حالة مهمة حذف الجلسات بالجملة |
| `/v3/sessions/{id}/reviews/` | GET, POST | نشاط الجلسة ومراجعاتها |
| `/v3/workflows/` | GET, POST | عرض سير العمل وإنشاؤه |
| `/v3/workflows/{id}/` | GET, PATCH, DELETE | تفاصيل سير العمل وتحديثه وحذفه |
| `/v3/questionnaires/` | GET, POST | عرض الاستبيانات وإنشاؤها |
| `/v3/questionnaires/{id}/` | GET, PATCH, DELETE | تفاصيل الاستبيان |
| `/v3/users/` | GET | عرض المستخدمين المتحقق منهم |
| `/v3/users/{vendor_data}/` | GET, PATCH | تفاصيل المستخدم وتحديثه |
| `/v3/users/delete/` | POST | حذف المستخدمين دفعة واحدة (ويمسح أيضاً قوالبهم البيومترية المحتفظ بها نهائياً) |
| `/v3/biometric-templates/` | GET | عرض القوالب البيومترية المحتفظ بها |
| `/v3/biometric-templates/count/` | GET | عدّ القوالب البيومترية المحتفظ بها |
| `/v3/biometric-templates/{id}/` | GET, DELETE | تفاصيل القالب / إزالته نهائياً |
| `/v3/biometric-templates/delete/` | POST | إزالة القوالب بالجملة نهائياً |
| `/v3/lists/` | GET, POST | عرض جميع القوائم / إنشاء قائمة |
| `/v3/lists/{id}/` | GET, PATCH, DELETE | تفاصيل القائمة / تحديثها / حذفها |
| `/v3/lists/{id}/entries/` | GET, POST | عرض عناصر القائمة / إضافة عنصر |
| `/v3/lists/{id}/entries/{eid}/` | DELETE | إزالة عنصر |
| `/v3/lists/{id}/entries/face-upload/` | POST | رفع وجه إلى قائمة الحظر |
| `/v3/webhook/` | GET, PATCH | إعدادات webhook (عنوان URL والسر والإصدار)، وسياسة الاحتفاظ، وأسماء مضيفات العودة للمحفظة |
| `/v3/billing/balance/` | GET | الاستعلام عن رصيد الاعتمادات |
| `/v3/billing/top-up/` | POST | شحن الرصيد |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.