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

استخدم endpoint مخصصًا للمحفظة للتحقق من شخص من داخل تطبيقك.
لا تحتاج إلى إنشاء سير العمل أو نشره، ولا إلى توفير `workflow_id`.
يبدأ الخادم الخلفي لديك التحقق ويسترجع نتيجة التحقق، بينما تُرشد واجهتك الشخص خلال المصادقة المطلوبة من المحفظة.

> [!NOTE]
>
> يتطلب تكامل API مع ذلك أن يصادق الشخص ويوافق على مشاركة هويته.
> لا يمكنك التحقق من شخص عبر إرسال معرّفه الشخصي دون هذا التفاعل.

## كيف يعمل التحقق

1. يتحقق الخادم الخلفي لديك من [كتالوج المحافظ](https://docs.didit.me/ar/standalone-apis/digital-id-wallet-catalog.md)، ثم يستدعي endpoint بدء المحفظة المتاحة باستخدام مفتاح API الخاص بتطبيقك.
2. يُرجع Didit مرجع التحقق والإجراء الذي يجب على الشخص تنفيذه.
3. يفتح تطبيقك صفحة المصادقة أو يعرض تعليمات الموافقة الخاصة بالمحفظة.
4. يصادق الشخص باستخدام محفظته.
5. يسترجع خادمك الخلفي النتيجة المؤكدة ويتعامل مع إشعارات الإكمال.

مصادقة المحفظة غير متزامنة.
يعني نجاح طلب البدء أن المصادقة قد بدأت، ولا يعني أن الهوية قد تم التحقق منها.
تحقق دائمًا من النتيجة النهائية قبل اعتبار الشخص موثّقًا.

## التكامل من جهة الخادم

استخدم [إدراج محافظ الهوية الرقمية](https://docs.didit.me/ar/standalone-apis/digital-id-wallet-catalog.md) للحصول على endpoints الحالية والحقول المطلوبة والتوفر لتطبيقك.

احتفظ بالمفتاح `x-api-key` على خادمك الخلفي.
لا تضعه في حزمة المتصفح أو في تطبيق الجوال.
استخدم `Idempotency-Key` مميزًا لكل محاولة تحقق جديدة، وأعد استخدام المفتاح نفسه عند إعادة محاولة طلب البدء نفسه.
تغيير الطلب مع إعادة استخدام المفتاح يُعد تعارضًا، وليس محاولة تحقق جديدة.

لكل محفظة عنوان URL خاص ببدء التحقق، مثل `/v3/id-verification/wallets/ftn/` لشبكة Finnish Trust Network.
يحدّد `request_id` عملية التحقق المستقلة للعمليات اللاحقة.
استخدم `vendor_data` لمرجعك الخاص، بحد أقصى 2,000 بايت UTF-8، واستخدم `metadata` لكائن JSON اختياري.
يتم إرجاع الحقلين مع النتيجة وwebhook الإكمال.

| العملية | endpoint |
| - | - |
| قراءة الحالة والنتيجة | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| استطلاع موافقة الهاتف | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| إرسال استجابة محفظة Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| إلغاء التحقق المعلّق | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

تستخدم هذه العمليات مفتاح API للتطبيق الذي بدأ التحقق.
يعتمد توفر الاستطلاع والمصادقة على المحفظة المختارة.

يؤدي الإلغاء إلى رفض التحقق المعلّق دون احتساب رسوم عليه، ويُرجع التحقق المكتمل دون تغيير.
بالنسبة إلى Smart-ID وMobile-ID، إذا وصل طلب إلغاء أثناء قيام استطلاع بفحص الموافقة، ينتظر الإلغاء بضع ثوانٍ حتى ينتهي ذلك الاستطلاع.
ثم يرفض التحقق، أو يُرجعه بالحالة `verified` إذا كان الشخص قد وافق مسبقًا.
لا يمكن إلغاء التحقق الذي يُكمله الشخص في تلك اللحظة: تكون الاستجابة `409` مع `error: "verification_in_progress"` ومع رأس `Retry-After`.
أعد المحاولة بعد هذا العدد من الثواني لقراءة النتيجة المكتملة.

## سجّل وجهة العودة الخاصة بك

ترسل محافظ إعادة التوجيه الشخص إلى تطبيقك بعد المصادقة.
سجّل اسم المضيف الدقيق قبل بدء أي تحقق:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

ثم أرسل `return_url` عبر HTTPS، مثل `https://app.example.com/identity/complete`، في طلب البدء.
استخدم أسماء مضيفين مجردة في `allowed_return_hosts`، دون مخطط أو مسار أو حرف بدل.
سجّل كل نطاق فرعي تستخدمه على حدة، بحد أقصى 20 اسم مضيف.
يؤدي تحديث `allowed_return_hosts` إلى استبدال القائمة المسجّلة، لذا أدرج كل اسم مضيف تريد الاحتفاظ به.
يُرجع `GET /v3/webhook/` القائمة الحالية؛ راجع [إعدادات webhook](https://docs.didit.me/ar/sessions-api/management-api.md#إعدادات-webhook).
لا تحتاج إلى سير عمل أو نطاق بالعلامة البيضاء لتسجيل وجهة العودة.
الوجهة صفحة عودة في المتصفح، لذا اضبط webhook الإكمال بشكل منفصل لخادمك الخلفي.

## مثال: Finnish Trust Network

بعد تسجيل اسم المضيف الخاص بالعودة، ابدأ عملية تحقق باستخدام Finnish Trust Network:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

احفظ `request_id` المُعاد، وأرسل متصفح الشخص إلى `wallet_verification.next_action.url` عندما يكون `type` هو `redirect`.
بعد عودة الشخص، استرجع النتيجة من خادمك الخلفي:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

تحقق من `wallet_verification.outcome`:

| النتيجة | المعنى |
| - | - |
| `pending` | ما زالت المصادقة جارية. |
| `verified` | اكتملت المصادقة، وتم التحقق من الهوية المُعادة. |
| `cancelled` | ألغى الشخص أو تطبيقك المحاولة. |
| `timeout` | انتهت مهلة المصادقة. |
| `failed` | فشلت المصادقة أو التحقق من الهوية. |

لا تعتمد على الهوية إلا عندما تكون النتيجة `verified`، ويكون `simulated` بالقيمة `false` في فحص هوية حقيقي.
قد تتضمن الاستجابة المعلّقة إجراءً تاليًا، أما الاستجابات النهائية فلا تتضمن إجراءً تاليًا.

## تجارب المصادقة

**المحافظ القائمة على إعادة التوجيه** تُعيد عنوان URL للمصادقة.
افتح هذا العنوان في متصفح الشخص، ودعه يُكمل عملية المصادقة الخاصة بالمحفظة، ثم أعده إلى الوجهة المسجّلة لديك.
اقرأ النتيجة من الخادم الخلفي لديك بدلاً من الاعتماد على معامل في عنوان الإعادة بوصفه دليلاً على الهوية.

**Smart-ID وMobile-ID** تستخدمان مطالبة موافقة على هاتف الشخص.
تجمع واجهتك المعرّف الشخصي المطلوب؛ ويحتاج Mobile-ID أيضاً إلى رقم الهاتف المرتبط به.
اعرض رمز المقارنة، ووجّه الشخص إلى الموافقة فقط عندما يتطابق رمز المقارنة مع الرمز الظاهر على هاتفه.
يجب أن يُدخل رقم PIN الخاص به في مطالبة المحفظة أو الهاتف، وليس في نموذجك أو في أي طلب API.
استعلم من الخادم الخلفي لديك بالفاصل الزمني المُعاد في `poll_interval_seconds` للحصول على تحديثات بشأن المطالبة.
كما يتحقق Didit من موافقات الهاتف المعلّقة في الخلفية، لذا قد يصل الإكمال إلى webhook الخاص بك بعد أن يغلق الشخص صفحتك.

**Google Wallet** تستدعيها صفحة الويب أو تطبيق Android لديك مباشرةً عبر Digital Credentials API، دون إعادة توجيه؛ راجع [محافظ بيانات الاعتماد الرقمية (Google Wallet)](#محافظ-بيانات-الاعتماد-الرقمية-google-wallet).

تعتمد طريقة التفاعل المتاحة على المحفظة المختارة.
لا تفترض أن كل محفظة تدعم نموذجاً مضمّناً أو رمز QR أو المصادقة دون متصفح.

## محافظ بيانات الاعتماد الرقمية (Google Wallet)

تستدعي صفحة الويب أو تطبيق Android لديك Google Wallet مباشرةً، باستخدام W3C Digital Credentials API.
لا توجد إعادة توجيه، ولا صفحة مستضافة من Didit، ولا رمز QR من Didit.
يتوفر في الإنتاج وفي البيئة التجريبية.
لا تحتاج تطبيقات البيئة التجريبية إلى تسجيل؛ أما كل تطبيق في بيئة الإنتاج فيسجّل مرة واحدة من وحدة التحكم (خطوة التحقق من الهوية، صف Google Wallet، **التسجيل لدى Google**) قبل أن يتمكن من استخدام Google Wallet.
راجع [عرض محافظ الهوية الرقمية](https://docs.didit.me/ar/standalone-apis/digital-id-wallet-catalog.md) لمعرفة ما يمكن لتطبيقك البدء به الآن.

**1. ابدأ بالمصدر (origin) الخاص بك**

يستدعي الخادم الخلفي لديك `POST /v3/id-verification/wallets/google-wallet/` مع `country` الخاص بالشخص (`USA` أو `GBR` أو `BRA` أو `SGP` أو `TWN`) و`origin` الذي سيستدعي المحفظة.
الـ `origin` هو أصل HTTPS لصفحتك، مثل `https://app.example.com`، ويجب أن يكون مضيفه أحد [أسماء المضيف المسجّلة لإعادة التوجيه](#سجّل-وجهة-العودة-الخاصة-بك) لديك أو نطاقك ذا العلامة البيضاء.
أما في تطبيق Android فيكون `android:apk-key-hash:` متبوعاً بقيمة base64 لـ SHA-256 لشهادة توقيع تطبيقك، دون حشو.
ترفض المحفظة أي طلب يأتي من أصل آخر.
لا يوجد `return_url`.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. اطلب من المحفظة ضمن تفاعل المستخدم**

يحتوي الرد على `wallet_verification.interaction = "digital_credentials"` و`next_action.type = "request_digital_credential"`.
مرّر `next_action.digital_credentials.request` إلى المتصفح أو إلى Android Credential Manager، من نقرة أو لمسة على `origin` الذي بدأت به.
على سطح المكتب، يعرض المتصفح رمز QR الخاص به عندما تكون المحفظة على جهاز آخر.

**3. أرسل ما أعادته المحفظة**

أرسل `{protocol, data}` المُعادة إلى الخادم الخلفي لديك، ومنه إلى `POST /v3/id-verification/wallets/verifications/{request_id}/response/` بالصيغة `{"response": {...}}`.
يمكن إرسال الطلب مرة واحدة فقط؛ فالإرسال الثاني يُعيد التحقق الذي اتُّخذ قراره بالفعل.

**4. اقرأ النتيجة**

استجابة الإرسال هي التحقق الذي اتُّخذ قراره.
ويمكنك أيضاً قراءته عبر `GET /v3/id-verification/wallets/verifications/{request_id}/` أو استلامه في webhook الإكمال.

في المتصفح، اطلب من المحفظة من معالج النقر:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

اعرض هذه الطريقة فقط حيث يدعمها المتصفح، مثلاً عندما تكون `"DigitalCredential" in window` صحيحة.
يجب أن يعمل `navigator.credentials.get` ضمن تفاعل المستخدم، لذا استدعِه من معالج النقر لا بعد خطوة غير متزامنة.

على Android، استخدم Jetpack Credential Manager (`androidx.credentials` بالإصدار 1.5.0 أو أحدث) مع الطلب نفسه:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

الأخطاء التي يجب معالجتها:

| الخطأ | المكان | المعنى |
| - | - | - |
| `origin_invalid` | البداية، `400` | `origin` ليس أصل HTTPS ولا أصل تطبيق Android. |
| `origin_not_allowed` | البداية، `400` | اسم المضيف الخاص بالـ origin غير مسجّل لتطبيقك. سجّله في `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | الإرسال، `409` | هذا التحقق لا يقبل ردّ محفظة. |

بيانات الاعتماد التي تفشل في التحقق تُعد تحققاً اتُّخذ قراره بنتيجة `failed`، لا استجابة خطأ.
لا تغادر المحفظة إلا الحقول التي يطلبها التحقق، وتحتوي النتيجة على سمات الهوية التي أعادتها المحفظة.
لا تُعيد بطاقة هوية Google Wallet ولا رخصة القيادة المحمولة الصادرة عن إحدى الولايات الأمريكية صورة شخصية.

في تطبيق البيئة التجريبية تُحاكى العملية بالخطوات نفسها وتُعيد `simulated: true`.
يحسم أي رد مُرسَل التحقق وفق `sandbox_scenario`، لذا يمكنك بناء رحلة المتصفح أو التطبيق كاملةً دون بيانات اعتماد حقيقية.

## webhooks الخاصة بالإكمال

اضبط وجهة webhook للتطبيق لحدث `status.updated` باتباع [دليل تكامل webhook](https://docs.didit.me/ar/integration/webhooks.md).
استخدم `webhook_version: "v3"` لبنية القرار الموصوفة هنا.
تحقّق من توقيع webhook على الخادم الخلفي لديك قبل معالجته.
يطابق `session_id` في webhook القيمة `request_id` التي تُعيدها واجهة API الخاصة بالمحفظة.
تظهر هوية المستخدم المكتملة عبر المحفظة في مصفوفة `decision.id_verifications` الخاصة بالـ webhook مع `verification_method: "wallet"`.
ويمكنك أيضاً استخدام المعرّف لاسترجاع نتيجة واجهة API المخصصة للمحفظة.

عالج إشعارات الموافقة والرفض، بما في ذلك إشعارات التحققات الملغاة والمنتهية الصلاحية.
اجعل معالج webhook لديك قابلاً للتنفيذ المتكرر بأمان لأن عمليات التسليم الفاشلة تُعاد محاولتها.
عودة المتصفح ليست webhook إكمال، ومعاملات الاستعلام فيها ليست دليلاً على الهوية.

## الهوية المُعادة

استخدم حقول الهوية الموحّدة للأسماء وتواريخ الميلاد عندما تُعاد هذه الحقول.
تصف السمات الخاصة بالمحفظة معلومات الهوية التي تشاركها المحفظة المختارة.
تختلف السمات المتاحة بحسب المحفظة والدولة.
لا تعني الهوية الموثّقة أن الصورة الشخصية أو العنوان أو أي سمة أخرى مطلوبة متاحة.

## الاختبار في البيئة التجريبية

يحاكي التطبيق الذي يعمل في وضع البيئة التجريبية في Didit التحقق عبر المحفظة دون الاتصال بمزوّد المحفظة، ودون خصم الرصيد.
تُحدِّد الاستجابة هذه الطلبات بالقيمة `wallet_verification.simulated: true`.
الموافقة المُحاكاة بيانات نموذجية، وليست هوية حقيقية موثّقة.

بالنسبة إلى محفظة تعتمد على إعادة التوجيه، اتبع الرابط المُعاد لاختبار رد الاستدعاء والعودة إلى تطبيقك.
أما Smart-ID أو Mobile-ID، فاستخدم endpoint المخصّص للاستطلاع لإكمال الموافقة المحاكاة؛ لا يُرسل أي إشعار إلى الهاتف.
لاختبار التعامل مع الإخفاق، اضبط `sandbox_scenario` على `wallet_cancelled` أو `wallet_timeout` أو `wallet_provider_error` عند بدء الطلب.
ترفض التطبيقات الإنتاجية `sandbox_scenario`.

تختلف محاكاة البيئة التجريبية في Didit عن الاختبار في البيئة التجريبية الخاصة بالمزوّد.
ولا يثبت نجاح المحاكاة وصولاً إلى المزوّد في بيئة الإنتاج ولا توافراً إنتاجياً.

### البيئة التجريبية لمزوّد ConnectID

تستخدم البيئة التجريبية لمزوّد ConnectID بنوكاً تجريبية، وهي منفصلة عن محاكاة البيئة التجريبية في Didit.
عند إعداد الوصول إلى البيئة التجريبية للمزوّد في تكاملك، مرّر `authorisation_server_id` الخاص بالبنك المختار إلى [endpoint بدء ConnectID](https://docs.didit.me/ar/api-reference/digital-id-wallets/connectid.md).
استخدم المعرّف الذي يعيده محدِّد البنوك في ConnectID؛ ولا ترسل رابط بنك أو مُصدِراً عشوائياً.
إذا أغفلت الحقل، يُختار بنك الاختبار الافتراضي.
هذا الحقل خاص بـ ConnectID، ولا يغيّر سمات الهوية المطلوبة.

تطلب الحزمة الأولية الاسم الأول واسم العائلة وتاريخ الميلاد.
اتبع `next_action` المُعاد للمصادقة، ثم استرجع نتيجة التحقق أو استطلعها.
لا تؤكد نجاح التحقق إلا نتيجة مكتملة بحالة مقبولة؛ أما العودة إلى تطبيقك فلا تؤكد ذلك.
تظل حالة ConnectID **قريبًا** في بيئة الإنتاج إلى أن يكتمل التسجيل والاعتماد.

## التوافر والأسعار

تغطية endpoint وتفعيل المحفظة في الإنتاج أمران منفصلان.
قد تملك محفظة صفحة مرجع API وتظل غير متاحة للمصادقة في بيئة الإنتاج.
تحقّق من الدول التي تغطيها المحفظة وحالتها في بيئة الإنتاج قبل تنفيذ مسار في بيئة الإنتاج.

للاطلاع على الأسعار المنشورة والتوافر، راجع [أسعار المحفظة الرقمية للهوية](https://docs.didit.me/ar/getting-started/pricing.md#تسعير-محفظة-الهوية-الرقمية).
يُحتسب التحقق عبر المحفظة بشكل منفصل عن التقاط المستندات.

## اختيار التكامل

استخدم واجهات البرمجة هذه عندما تريد التحكم في الواجهة المحيطة ومنطق التطبيق.
واستخدم [Sessions API](https://docs.didit.me/ar/sessions-api/create-session.md) عندما تريد مسار التحقق المستضاف من Didit وقواعد سير العمل والخطوات البديلة المُعدّة.
ويظل النهجان يتطلبان عملية المصادقة والموافقة الخاصة بالمحفظة.


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