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

# فحص eID

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

يثبت فحص eID أن العميل الذي ليس أمامكم هو الشخص صاحب هويته. يتلقى العميل بريدًا إلكترونيًا يحتوي على رمز PIN ورابط، ثم يمسح هوية ضوئيًا ويلتقط صورة ذاتية في تطبيق مزوّد eID. تغطي ذلك ثلاث نقاط نهاية. النطاق (scope) للثلاث جميعًا: `kyc:eid`.

في هذا الإصدار لا يقبل المحرّك إلا العملاء الكنديين في eID. لذلك تستخدم الأمثلة في هذه الصفحة البلد `CA`، خلافًا لبقية الأدلة التي تستخدم `MA`.

| نقطة النهاية | الوظيفة |
| - | - |
| `POST /v1/kyc/eid` | يبدأ الفحص. يراسل المزوّد العميل فورًا. يعيد HTTP 201 و`key`. |
| `GET /v1/kyc/eid/{key}` | حالة الفحص، وما أثبته، وفحوصه. |
| `GET /v1/kyc/eid/{key}/report` | تقرير المزوّد بصيغة PDF عن الفحص. |

## قبل أن تبدؤوا

| الشرط | إن لم يتحقق |
| - | - |
| العميل كندي: `country` هو `CA` أو `CAN`. | 422 `identity verification is available for Canadian clients only` |
| لمساحة عملكم حساب خاص لدى مزوّد eID. تتولى Sahl إعداده. | 404 `identity verification is not set up for this tenant` |
| للمفتاح النطاق `kyc:eid` ومساحة العمل مفعّلة لواجهة الشركاء. | 403 `insufficient_scope` (المفتاح) أو `kyc_scope_not_allowed` (مساحة العمل). للحصول على وصول الشركاء، استخدموا [نموذج الاتصال](https://sahlfinancial.com/contact?type=demo). |

<Warning>
  لا يغيّر `environment` المزوّد. الطلب المرسل مع `environment: "sandbox"` يراسل العميل فعلًا ويستدعي المزوّد فعلًا. لا يختار `environment` إلا ملف الحالة الذي يُحفظ فيه الطلب. استخدموا عنوان بريد إلكتروني تتحكمون فيه عند الاختبار.
</Warning>

## بدء فحص

```json theme={null}
{
  "reference": "client-0001",
  "first_name": "Test",
  "last_name": "Client",
  "email": "test.client@example.com",
  "country": "CA",
  "language": "en",
  "documents": 1,
  "environment": "sandbox"
}
```

| الحقل | النوع | القيمة الافتراضية | القاعدة |
| - | - | - | - |
| `reference` | سلسلة نصية | مطلوب | من 1 إلى 64 حرفًا من `A-Z a-z 0-9 _ . : -`. معرّفكم للعميل. |
| `first_name` | سلسلة نصية | مطلوب | من 1 إلى 100 حرف. |
| `last_name` | سلسلة نصية | مطلوب | من 1 إلى 100 حرف. |
| `email` | سلسلة نصية | مطلوب | بريد إلكتروني صالح. يُرسل إليه PIN والرابط. |
| `country` | سلسلة نصية | مطلوب | حرفان أو 3 أحرف. يُقبل `CA` أو `CAN` فقط. |
| `language` | سلسلة نصية | `en` | `en` أو `fr`. |
| `documents` | عدد صحيح | `1` | `1` أو `2`: عدد وثائق الهوية التي يجب على العميل مسحها ضوئيًا. |
| `environment` | سلسلة نصية | `sandbox` | `sandbox` أو `production`. يختار ملف الحالة. |

الإجابة:

```json theme={null}
{ "key": 123456, "reference": "client-0001" }
```

`key` هو المعرّف الذي تستعلمون به. يُرسل PIN إلى العميل فقط ولا يُعاد إليكم أبدًا.

يُحفظ الطلب بوضع `pending` في ملف الحالة الخاص بـ (مساحة العمل، `environment`، `reference`). والطلب الجديد لنفس المرجع والبيئة يستبدل السجل، لأنكم بدأتم التحقق من العميل من جديد. ويخزّن المزوّد الطلب تحت معرّف عميل مكوّن من مساحة عملكم ومرجعكم، وهذا ما يمنع مساحة عمل أخرى من قراءته.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.sahlfinancial.com/api/v1/kyc/eid \
    -H "Authorization: Bearer $SAHL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference":"client-0001","first_name":"Test","last_name":"Client","email":"test.client@example.com","country":"CA","language":"en","documents":1,"environment":"sandbox"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/eid", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SAHL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reference: "client-0001",
      first_name: "Test",
      last_name: "Client",
      email: "test.client@example.com",
      country: "CA",
      language: "en",
      documents: 1,
      environment: "sandbox",
    }),
  });
  if (res.status !== 201) throw new Error(`${res.status} ${await res.text()}`);
  const { key } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://app.sahlfinancial.com/api/v1/kyc/eid",
      headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
      json={
          "reference": "client-0001",
          "first_name": "Test",
          "last_name": "Client",
          "email": "test.client@example.com",
          "country": "CA",
          "language": "en",
          "documents": 1,
          "environment": "sandbox",
      },
      timeout=60,
  )
  assert res.status_code == 201, res.text
  key = res.json()["key"]
  ```
</CodeGroup>

## الحالات

لا توجد دالة رد (callback) من المزوّد. أنتم تستعلمون عبر `GET /v1/kyc/eid/{key}`. وتستنتج Sahl الحالة من هذا الاستعلام.

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: POST /v1/kyc/eid (client emailed)
    pending --> complete: client scanned a document
    pending --> archived: request archived, never completed
    complete --> passed: no critical check failed
    complete --> failed: a critical check failed
    passed --> [*]
    failed --> [*]
    archived --> [*]
```

| الحالة | `complete` | `passed` | ما تفعلونه |
| - | - | - | - |
| `pending` | false | false | واصلوا الاستعلام. يقول الفحص `eid:completed`: `the client has not completed the verification yet`. |
| `passed` | true | true | استخدموها. نزّلوا التقرير. |
| `failed` | true | false | انظروا أي فحص `eid:` فشل. ابدؤوا طلبًا جديدًا لإعادة المحاولة. |
| `archived` | false | false | أُرشف الطلب دون فحص مكتمل. يقول `eid:completed`: `the request was archived without a completed verification`. ابدؤوا طلبًا جديدًا. |

`pending` و`passed` و`failed` و`archived` هي أيضًا الحالة التي تسجّلها Sahl في ملف الحالة. وحدها `passed` تستوفي متطلب eID في السياسة.

## الاستعلام الدوري

لـ `GET /v1/kyc/eid/{key}` معامل استعلام اختياري واحد، `environment` (الافتراضي `sandbox`). ولا يفيد إلا في تحديد موضع طلب بدأ قبل أن تحتفظ Sahl بسجل eID. أما الطلب المقدَّم عبر `POST /v1/kyc/eid` فيحتفظ ببيئته.

لا تحدد Sahl فاصلًا للاستعلام. السقف الوحيد هو 100 طلب في الدقيقة لكل IP. جدول معقول: كل 30 ثانية في أول 10 دقائق، ثم كل 5 دقائق. على العميل أن يفتح البريد، لذلك من الطبيعي أن يستغرق الأمر من دقائق إلى ساعات.

الفحص المنتهي (complete أو archived) هو اللحظة التي تسجّل فيها Sahl النتيجة في ملف الحالة، وأول استعلام يراه يرسل [webhook](/ar/guides/webhooks) بالحدث `kyc.eid_completed`. أما الاستعلامات اللاحقة فتبقى صامتة.

### الإجابة عند الاكتمال

```json theme={null}
{
  "key": 123456,
  "complete": true,
  "passed": true,
  "identity": {
    "documentType": "PASSPORT",
    "documentNumber": "P1234567",
    "expiryDate": "2030-05-01",
    "birthDate": "1988-04-12",
    "firstName": "Test",
    "lastName": "Client"
  },
  "checks": [
    { "id": "eid:liveness", "label": "Selfie passed the liveness check", "severity": "critical", "passed": true, "detail": "" },
    { "id": "eid:face_match", "label": "Face on the ID matches the selfie (score 3 or more)", "severity": "critical", "passed": true, "detail": "score 4 of 4, confidence 97%" },
    { "id": "eid:name_match", "label": "Name on the ID matches the name on the request", "severity": "critical", "passed": true, "detail": "" }
  ],
  "completed_date": "2026-10-07T12:00:00Z"
}
```

القيم وهمية، ومنتَجة بالدالة نفسها التي تستخدمها الواجهة.

| المفتاح | المعنى |
| - | - |
| `key` | معرّف الطلب. |
| `complete` | true بمجرد أن يمسح العميل مستندًا ضوئيًا. |
| `passed` | true عندما يكون `complete` ولم يفشل أي فحص بدرجة `critical`. |
| `identity` | ما أثبته الفحص. المفاتيح الممكنة: `documentType` و`documentNumber` و`expiryDate` و`birthDate` و`firstName` و`lastName` و`address`. لا تظهر إلا القيم التي يحتفظ بها المزوّد. فارغ إلى أن يكتمل الفحص. |
| `checks` | فحوص eID، بنفس شكل فحوص التحقق. |
| `completed_date` | وقت الاكتمال كما يبلّغه المزوّد، أو null. |

### الفحوص

| المعرّف | الدرجة | ينجح عندما |
| - | - | - |
| `eid:completed` | critical | موجود فقط إلى أن يكمل العميل الفحص. فاشل دائمًا. |
| `eid:liveness` | critical | اجتازت الصورة الذاتية فحص الحيوية (liveness). |
| `eid:face_match` | critical | تبلغ درجة مطابقة الوجه 3 أو أكثر (تُظهر التفاصيل `score N of 4` ونسبة الثقة). |
| `eid:name_match` | critical | يطابق الاسم على الهوية الاسم في طلبكم. ولذلك يجب أن يكون الاسم الأول واسم العائلة اللذان ترسلونهما دقيقين. |
| `eid:message:N` | critical أو warning | أعاد المزوّد رسالة. فاشل دائمًا. انظر أدناه. |

رسائل المزوّد ودرجتها:

| الرسالة | الدرجة |
| - | - |
| `The machine readable values of one or more fields do not match.` | critical |
| `Document is past expiry date.` | critical |
| `Name entered on request does not match name on document.` | critical |
| `Low face match score.` | critical |
| `No machine readable data found on document.` | warning |
| أي رسالة أخرى | warning |

## التقرير

يعيد `GET /v1/kyc/eid/{key}/report` تقرير المزوّد بالنوع `application/pdf` مع `Content-Disposition: attachment; filename="eid-<key>.pdf"`. وهو مخصص لملف العميل.

```bash theme={null}
curl -o eid-123456.pdf https://app.sahlfinancial.com/api/v1/kyc/eid/123456/report \
  -H "Authorization: Bearer $SAHL_API_KEY"
```

## احتفظوا بالنتيجة

اجلبوا النتيجة وملف PDF خلال نحو سبعة أيام من الفحص. بعد ذلك يحذف المزوّد البيانات الشخصية. تسجّل Sahl النتيجة (الحالة ووقت الاكتمال) في ملف الحالة لديكم عندما يرى أول استعلام الحالة النهائية، لكن كتلة `identity` وملف PDF يأتيان من المزوّد، فخزّنوا ما تحتاجونه.

## استيفاء متطلب eID في السياسة

يمكن لسياسة مساحة العمل أن تشترط فحص eID عن بُعد لشخص لم يُقابَل وجهًا لوجه (`eid_required_non_face_to_face`). عندئذ يضيف `/verify` و`/assess` فحصًا من درجة critical هو `policy:eid_non_face_to_face`:

| الحالة | الفحص |
| - | - |
| قُدّم طلب بهذا `reference` و`environment` عبر `POST /v1/kyc/eid` وحالته المسجلة `passed` | ينجح: `eID request N passed` |
| لا يوجد طلب مسجل | يفشل: `the client was not met in person and no eID request made through Sahl (POST /v1/kyc/eid) is on file for this reference and environment` |
| الطلب معلّق | يفشل: `eID request N has not been seen completed; poll GET /v1/kyc/eid/{key} once the client has finished` |
| فشل الطلب أو أُرشف | يفشل: `eID request N ended failed` (أو `archived`) |
| `values.verified_in_person` يساوي true | لا يُطبَّق. يسجّل فحص info باسم `policy:met_in_person_declared` أنه إقراركم وأن Sahl لم تتحقق منه. |
| `purpose` هو `periodic_review` | لا يُطبَّق |

لا يستوفي المتطلب إلا سجل Sahl نفسها. الفحص الذي ترسلونه في `extra_checks` بمعرّف يبدأ بـ `eid:` يُعاد تسميته `partner:eid:...` ولا يُحتسب أبدًا. استخدموا `reference` و`environment` نفسيهما لطلب eID ولاستدعاء `/verify`. واستعلموا عن الفحص حتى يكتمل قبل أن تستدعوا `/verify`، لأن النتيجة تُسجَّل عبر الاستعلام.

## الأخطاء

| الحالة | الجسم | السبب |
| - | - | - |
| 401, 403 | انظر [الأخطاء](/ar/errors) | مشكلات في المفتاح. |
| 404 | `identity verification is not set up for this tenant` | لا يوجد حساب مزوّد لمساحة العمل. |
| 404 | `Not Found` | `key` غير معروف، أو مفتاح بدأته مساحة عمل أخرى. |
| 422 | `identity verification is available for Canadian clients only` | `country` ليس `CA` ولا `CAN`. |
| 422 | قائمة `detail` | حقل لا يطابق المخطط، مثلًا `documents` ليس 1 ولا 2. |
| 502 | `the identity verification service did not answer` | المزوّد متوقف أو رفض. أعيدوا المحاولة لاحقًا. |


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