> ## 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.

# حالات التحقق: دورة حياة الجلسة والرموز

> شرح حالات جلسات Didit: مقبولة، مرفوضة، قيد المراجعة، منتهية الصلاحية، مُعاد إرسالها، متروكة، وKYC منتهي. تعامل مع القرارات وإعادة المحاولة وwebhook.

تمرّ كل جلسة تحقق بسلسلة من الحالات. فهم هذه الحالات يساعدك على متابعة تقدم المستخدم، وأتمتة قرارات الامتثال، وتحسين معدل التحويل.

هذا التعداد هو المصدر الوحيد المعتمد للقيم النصية التي تُرجعها `GET /v3/session/<id>/decision/` وكل webhook من Didit.

***

## جميع قيم الحالة

> [!NOTE]
>
> كل حالة هي **سلسلة نصية مطابقة تماماً** تُرجعها واجهة API الخاصة بـ Didit وwebhooks. استخدم دائماً المطابقة الصارمة للسلاسل النصية في كودك (مثلاً `=== "In Review"`)، فهذه القيم حساسة لحالة الأحرف وتتضمن مسافات. كما أن القيمة `Kyc Expired` تستخدم حرف `K` كبيراً واحداً فقط، وليس `KYC`.

| الحالة | القيمة النصية | الوصف |
| - | - | - |
| Not Started | `"Not Started"` | تم إنشاء الجلسة، لكن المستخدم لم يفتح الرابط بعد |
| In Progress | `"In Progress"` | المستخدم يُكمل عملية التحقق حالياً |
| Approved | `"Approved"` | نجحت جميع الفحوصات، وتم التحقق من الهوية |
| Declined | `"Declined"` | فشل فحص واحد أو أكثر |
| In Review | `"In Review"` | تم وضع علامة عليها لمراجعة امتثال يدوية |
| Awaiting User | `"Awaiting User"` | في انتظار أن يُكمل طرف واحد أو أكثر عملية التحقق الخاصة به (KYB) |
| Resubmitted | `"Resubmitted"` | طُلب من المستخدم إعادة تنفيذ خطوات محددة |
| Expired | `"Expired"` | انتهت مهلة الجلسة قبل أن يفتح المستخدم الرابط |
| Abandoned | `"Abandoned"` | بدأ المستخدم العملية لكنه لم يُنهها في الوقت المحدد |
| KYC Expired | `"Kyc Expired"` | جلسة مقبولة سابقًا، وتجاوز المستند الذي جرى التحقق منه تاريخ انتهائه |

***

## حالات الجلسة

> [accordion] لم تبدأ - "Not Started"
>
> **القيمة في API:** `"Not Started"`
>
> تم إنشاء الجلسة عبر API، لكن المستخدم **لم يفتح رابط التحقق بعد**.
>
> * **ما الذي يجب فعله:** انتظر حتى يبدأ المستخدم، أو أرسل تذكيرًا إذا مرّ وقت طويل.
> * **ينتقل إلى:** `"In Progress"`، `"Expired"`

> [accordion] قيد التقدم - "In Progress"
>
> **القيمة في API:** `"In Progress"`
>
> فتح المستخدم الرابط، وهو **ينفّذ خطوات التحقق حاليًا** (التقاط المستند، وكشف الحيوية، وغير ذلك).
>
> * **ما الذي يجب فعله:** لا يلزم أي إجراء، فالمستخدم يتابع سير التحقق.
> * **ينتقل إلى:** `"Approved"`، `"Declined"`، `"In Review"`، `"Abandoned"`

> [accordion] مقبولة - "Approved"
>
> **القيمة في API:** `"Approved"`
>
> نجحت **جميع** فحوصات التحقق. تم التحقق من هوية المستخدم.
>
> * **ما الذي يجب فعله:** امنح المستخدم الوصول، وحدّث ملفه الشخصي، واحفظ بيانات القرار.
> * **يتضمن الـ webhook:** كائن `decision` كاملًا مع نتائج جميع الميزات.
> * **ينتقل إلى:** `"Kyc Expired"` (عند تجاوز تاريخ انتهاء صلاحية المستند الذي جرى التحقق منه، وهذا هو السلوك الافتراضي ما لم تكن **Expiration mode** مضبوطة على **Allow expired** لذلك البلد ونوع المستند). ويمكن للمراجع أو لـ endpoint تحديث الحالة أيضًا أن يعيّنها إلى `"Declined"` أو `"Resubmitted"`.

> [accordion] مرفوضة - "Declined"
>
> **القيمة في API:** `"Declined"`
>
> **فشل** فحص واحد أو أكثر من فحوصات التحقق. لم يجتز المستخدم التحقق.
>
> * **ما الذي يجب فعله:** أبلغ المستخدم. واطلب إعادة التقديم اختياريًا إذا كانت المشكلة قابلة للإصلاح.
> * **يتضمن الـ webhook:** كائن `decision` كاملًا مع التحذيرات التي تشرح سبب الفشل.
> * **ينتقل إلى:** `"Resubmitted"` (إذا طلب ذلك المراجع). ويمكن للمراجع أو لـ endpoint تحديث الحالة أيضًا أن يعيّنها إلى `"Approved"`.

> [accordion] قيد المراجعة - "In Review"
>
> **القيمة في API:** `"In Review"`
>
> رصدت الفحوصات الآلية **تحذيرات تحتاج إلى مراجعة بشرية**. يجب أن يتخذ مراجع الامتثال القرار النهائي.
>
> * **ما الذي يجب فعله:** ينبغي للمراجع فتح الجلسة في Console، ثم اعتمادها أو رفضها أو طلب إعادة التقديم.
> * **يتضمن الـ webhook:** كائن `decision` كاملًا مع التحذيرات.
> * **ينتقل إلى:** `"Approved"`، `"Declined"`، `"Resubmitted"`

> [accordion] بانتظار المستخدم - "Awaiting User"
>
> **القيمة في API:** `"Awaiting User"`
>
> تُستخدم في **جلسات KYB (التحقق من الشركات)** عندما ترسل خطوة الأشخاص الرئيسيين قائمة الأطراف، فتُنشئ جلسات KYC أو KYB فرعية. تنتظر الجلسة الأم حتى **يُكمل جميع الأطراف المطلوبون عملية التحقق الفردية**.
>
> * **ما الذي يجب فعله:** راقب حالات جلسات KYC الفرعية. وبمجرد أن تصل جلسات جميع الأطراف المطلوبة إلى حالة نهائية (مقبولة أو مرفوضة أو منتهية الصلاحية)، تُعيد الجلسة الأم تحديد حالتها النهائية تلقائيًا.
> * **يتضمن الـ webhook:** القائمة الحالية للأطراف وحالات جلساتهم الفرعية.
> * **ينتقل إلى:** `"Approved"`، `"Declined"`، `"In Review"` (عندما تصبح جميع الجلسات الفرعية نهائية)
> * **ينتقل من:** `"In Progress"` (بعد إرسال خطوة الأشخاص الرئيسيين)
> * **ملاحظة:** إذا أُعيد تقديم جلسة KYC فرعية، تعود الجلسة الأم إلى `"Awaiting User"` إلى أن تكتمل الجلسة المعاد تقديمها. ويتقدّم فحص السجل KYB (KYB Registry Check) الذي حالته `"Declined"` على `"Awaiting User"`.

> [accordion] أُعيد التقديم - "Resubmitted"
>
> **القيمة في API:** `"Resubmitted"`
>
> طلب المراجِع من المستخدم **إعادة تنفيذ خطوات تحقق محددة** (مثلًا إعادة التقاط صورة مستند غير واضحة).
>
> * **ما الذي يجب فعله:** انتظر حتى يُكمل المستخدم الخطوات المطلوب إعادتها. سيعيد النظام التقييم تلقائيًا.
> * **يتضمن الـ webhook:** كائن `resubmit_info` يحتوي على قائمة الميزات المطلوب إعادة تنفيذها وأسبابها.
> * **ينتقل إلى:** `"Approved"`، `"Declined"`، `"In Review"`، أو `"Abandoned"` عندما تنتهي نافذة الجلسة قبل أن يعيد الشخص تنفيذ الخطوات.

> [accordion] منتهية الصلاحية - "Expired"
>
> **القيمة في API:** `"Expired"`
>
> انتهت مهلة الجلسة **قبل أن يفتح المستخدم رابط التحقق**.
>
> * **ما الذي يجب فعله:** أنشئ جلسة جديدة، وأرسل للمستخدم رابطًا جديدًا.
> * **حالة نهائية**: لا توجد انتقالات أخرى.

> [accordion] متروكة - "Abandoned"
>
> **القيمة في API:** `"Abandoned"`
>
> بدأ المستخدم التحقق **لكنه لم يُنهِه** ضمن المهلة المسموح بها.
>
> * **ما الذي يجب فعله:** أرسل تذكيرًا، أو أنشئ جلسة جديدة.
> * **لا توجد انتقالات تلقائية.** يمكن للمراجع، أو لـ `PATCH /v3/session/{sessionId}/update-status/`، أن يعيّنها إلى `"Approved"` أو `"Declined"` أو `"Resubmitted"`.

> [accordion] KYC منتهي الصلاحية - "Kyc Expired"
>
> **القيمة في API:** `"Kyc Expired"`
>
> انتهى **تاريخ صلاحية** المستند الذي جرى التحقق منه خلال الجلسة. المُشغِّل هو هذا التاريخ، وليس مدة تُقاس من تاريخ الموافقة، ولا يُرسل أي تنبيه مسبق.
>
> * **ما الذي يجب فعله:** اطلب من المستخدم إعادة التحقق عبر جلسة جديدة. يُبلّغ حدث `status.updated` بالانتقال، وتتضمن نتيجة التحقق من الهوية التحذير `DOCUMENT_EXPIRED`.
> * **يتحكم فيه:** **Expiration mode** لذلك البلد ونوع المستند في *ID verification → Additional settings by country & document type*. **Reject expired** (الافتراضي) يراقب المستند، أما **Allow expired** فيعني أن الجلسة لا تنتقل إلى هذه الحالة أبدًا.
> * **لا توجد انتقالات تلقائية.** يمكن للمراجع، أو لـ `PATCH /v3/session/{sessionId}/update-status/`، أن يعيّنها إلى `"Approved"` أو `"Declined"` أو `"Resubmitted"`.

***

## انتقالات الحالة

| من | إلى | المُشغِّل |
| - | - | - |
| `"Not Started"` | `"In Progress"` | يفتح المستخدم رابط التحقق |
| `"Not Started"` | `"Expired"` | تنتهي مهلة صلاحية الجلسة قبل أن يفتح المستخدم الرابط |
| `"In Progress"` | `"Approved"` | تنجح جميع الفحوصات الآلية |
| `"In Progress"` | `"Declined"` | يفشل فحص واحد أو أكثر |
| `"In Progress"` | `"In Review"` | تُظهر الفحوصات تحذيرات تتطلب مراجعة بشرية |
| `"In Progress"` | `"Awaiting User"` | إرسال خطوة الأشخاص الرئيسيين في KYB؛ ينتظر الأصل أطراف KYC الفرعية |
| `"In Progress"` | `"Abandoned"` | لا ينهي المستخدم العملية خلال المدة المحددة |
| `"Awaiting User"` | `"Approved"` | يكمل جميع أطراف KYB المطلوبين وتنجح الفحوصات المجمّعة |
| `"Awaiting User"` | `"Declined"` | يُرفض أحد الأطراف المطلوبة أو يفشل فحص سجل الشركات الخاص بـ KYB |
| `"Awaiting User"` | `"In Review"` | تتطلب نتيجة KYB المجمّعة مراجعة يدوية |
| `"In Review"` | `"Approved"` | يوافق المراجع يدوياً |
| `"In Review"` | `"Declined"` | يرفض المراجع يدوياً |
| `"In Review"` | `"Resubmitted"` | يطلب المراجع إعادة تنفيذ خطوات محددة |
| `"Declined"` | `"Resubmitted"` | يطلب المراجع إعادة تنفيذ خطوات محددة |
| `"Approved"` | `"Resubmitted"` | يطلب المراجع إعادة تنفيذ خطوات محددة |
| `"Approved"` | `"Declined"` | يضبط المراجع أو API القرار المعاكس |
| `"Declined"` | `"Approved"` | يضبط المراجع أو API القرار المعاكس |
| `"Abandoned"`, `"Kyc Expired"` | `"Approved"`, `"Declined"`, `"Resubmitted"` | يتخذ المراجع أو API قراراً بشأن جلسة انتهت دون قرار |
| `"Resubmitted"` | `"Abandoned"` | تنتهي نافذة الجلسة قبل أن يعيد الشخص تنفيذ الخطوات |
| `"Resubmitted"` | `"Approved"` | تنجح جميع الفحوصات في الخطوات المُعاد تقديمها |
| `"Resubmitted"` | `"Declined"` | تفشل الخطوات المُعاد تقديمها |
| `"Resubmitted"` | `"In Review"` | تُظهر الخطوات المُعاد تقديمها تحذيرات جديدة |
| `"Resubmitted"` (فرع KYB) | `"Awaiting User"` (أصل KYB) | يعود الأصل إلى حالة الانتظار حتى يكتمل الفرع |
| `"Approved"` | `"Kyc Expired"` | يمر تاريخ انتهاء صلاحية المستند الموثّق (وضع الانتهاء هو **Reject expired**) |

### مخطط دورة الحياة

```mermaid theme={null}
flowchart LR
    NS["Not Started"] --> IP["In Progress"]
    NS --> EX["Expired"]
    IP --> AP["Approved"]
    IP --> DC["Declined"]
    IP --> IR["In Review"]
    IP --> AU["Awaiting User<br/>(KYB only)"]
    IP --> AB["Abandoned"]
    AU --> AP
    AU --> DC
    AU --> IR
    IR --> AP
    IR --> DC
    IR --> RS["Resubmitted"]
    DC --> RS
    AP --> RS
    AP <--> DC
    AB --> AP
    AB --> DC
    AB --> RS
    KE --> AP
    KE --> DC
    KE --> RS
    RS --> AB
    RS --> AP
    RS --> DC
    RS --> IR
    AP --> KE["Kyc Expired"]
```

***

## الحالات النهائية وغير النهائية

| الفئة | الحالات | المعنى |
| - | - | - |
| **ذات قرار** | `"Approved"`, `"Declined"`, `"Kyc Expired"` | أنتجت الفحوصات قراراً، ولا يغيّره النظام من تلقاء نفسه، إلا عندما تنتقل الحالة من `"Approved"` إلى `"Kyc Expired"` بعد تجاوز تاريخ انتهاء المستند الموثّق. ما زال بإمكان المراجع أو endpoint تحديث الحالة تغيير القرار. |
| **غير نهائية** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | ما زالت نشطة، تنتظر إجراء المستخدم أو الجلسات الفرعية أو المعالجة. |
| **قابلة للتنفيذ** | `"In Review"` | تتطلب تدخلاً يدوياً من فريقك. |
| **غير نشط** | `"Expired"`, `"Abandoned"` | انتهت دون قرار تحقق. لا تتغير الحالة `"Expired"` أبداً، ويمكن للمراجع أن يتخذ قراراً بشأن جلسة `"Abandoned"`. |

***

## التعامل مع الحالات في الكود

استخدم webhooks أو [واجهة برمجة استرجاع الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session.md) للاستجابة لتغييرات الحالة.

> [!WARNING]
>
> الحالات **سلاسل نصية دقيقة تتضمن مسافات، وتفرّق بين الأحرف الكبيرة والصغيرة**. على سبيل المثال، `"In Review"` (وليس `"in_review"` أو `"IN_REVIEW"`). استخدم دائماً المقارنة الصارمة (`===`) عند المطابقة.

```javascript theme={null}
// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}
```

***

## إعادة التقديم

تتيح حالة **مُعاد التقديم** لفريق الامتثال لديك منح المستخدمين فرصة ثانية دون إنشاء جلسة جديدة.

**1. يبدأ المراجع إعادة التقديم**

من Console، افتح جلسة `In Review` أو `Declined` وانقر على **طلب إعادة التقديم**. حدّد الخطوات التي تحتاج إلى إعادة التنفيذ.

**2. أرشفة البيانات السابقة**

يعيد النظام ضبط الميزات المحددة ويضع علامة `previous_attempt` على البيانات السابقة، مع الحفاظ على سجل التدقيق الكامل.

**3. إشعار المستخدم**

إذا كان البريد الإلكتروني متاحاً، يتلقى المستخدم رسالة بريد إلكتروني مترجمة إلى لغته تحتوي على رابط مباشر للمتابعة.

**4. يعيد المستخدم تنفيذ خطوات محددة**

يكرر المستخدم الخطوات المُعلَّمة فقط، وليس التحقق بأكمله.

**5. يعيد النظام التقييم**

عند الاكتمال، تنتقل الجلسة تلقائياً إلى `"Approved"` أو `"Declined"` أو `"In Review"`.

### حمولة webhook الخاصة بإعادة التقديم

```json theme={null}
{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "DOCUMENT_EXPIRED",
      "feature_liveness": "LOW_LIVENESS_SCORE"
    }
  }
}
```

تربط `reasons` كل `node_id` أُعيد تقديمه بكود التحذير الخاص بالسجل الأكثر صلة بتلك الخطوة (وهي الأكواد نفسها التي يعرضها [القرار](https://docs.didit.me/ar/reference/data-models.md))، فيمكنك ربطه بنسختك الخاصة. وهو أيضاً الكود الذي تُحوّله شاشة إعادة التقديم في التدفق المستضاف ورسالة إعادة التقديم إلى نص محلي للمستخدم، باستثناء التحذيرات التي قد تكشف إشارة فحص أو احتيال (التكرار وAML وقائمة الحظر والفحوصات عبر المؤسسات وسلامة الموقع وما شابهها). في هذه الحالات يرى الشخص سبباً عاماً، أما `resubmit_info.reasons` في webhook فيتضمن دائماً الكود الحقيقي. لا يظهر أي إدخال للخطوة التي لم يُسجَّل لها أي تحذير.

### أي الميزات يمكن إعادة تقديمها؟

أي ميزة بحالة غير مقبولة: **مرفوضة**، **قيد المراجعة**، **غير مكتملة**، **لم تبدأ**، أو **منتهية الصلاحية**.

> [!TIP]
>
> يمكنك طلب إعادة التقديم عدة مرات في الجلسة نفسها. تؤرشف كل دورة بيانات المحاولة السابقة، مما يمنحك رؤية كاملة لسجل التحقق لدى المستخدم.

***

## أفضل الممارسات

> [card] مراقبة حالة قيد المراجعة
>
> اضبط التنبيهات (عبر البريد الإلكتروني أو Slack) في Didit Console لتتلقى إشعارًا عندما تحتاج الجلسات إلى مراجعة يدوية.

> [card] تفضيل إعادة التقديم
>
> إذا كانت المشكلة قابلة للإصلاح (صورة غير واضحة، أو الجانب الخاطئ من المستند)، فاطلب إعادة التقديم بدلًا من الرفض. يؤدي ذلك إلى تحسين معدل التحويل.

> [card] تتبّع حالات التسرّب
>
> قد تشير معدلات الحالات المتروكة أو منتهية الصلاحية المرتفعة إلى احتكاك في تجربة المستخدم. فكّر في تعديل TTL الخاص بالجلسة أو تحسين إرشادات المستخدم.

> [card] معالجات Idempotent
>
> قد تُعاد محاولة إرسال webhook. استخدم `session_id` كمفتاح فريد لتضمن معالجة كل تغيير في الحالة مرة واحدة فقط.

> [!WARNING]
>
> تحقّق دائمًا من توقيعات webhook قبل معالجة payload. يوفّر Didit ثلاث طرق: `X-Signature` و`X-Signature-V2` (موصى به)، و`X-Signature-Simple` المُهمَل، الذي يصادق على المغلّف فقط ولا يصادق على محتوى `decision` أبدًا. راجع [Webhooks](https://docs.didit.me/ar/integration/webhooks.md#التحقق-من-التوقيع) للتفاصيل.


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