فحص 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` (مساحة العمل). للحصول على وصول الشركاء، استخدموا نموذج الاتصال.

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

بدء فحص

{
  "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`. يختار ملف الحالة.

الإجابة:

{ "key": 123456, "reference": "client-0001" }

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

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"}'

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();

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"]

الحالات

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

الحالة	`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 بالحدث kyc.eid_completed. أما الاستعلامات اللاحقة فتبقى صامتة.

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

{
  "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". وهو مخصص لملف العميل.

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	انظر الأخطاء	مشكلات في المفتاح.
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`	المزوّد متوقف أو رفض. أعيدوا المحاولة لاحقًا.

البدء

المستندات (OCR)

التحقق والهوية الإلكترونية (eID)

تقييم المخاطر وتسجيل الجدارة

البناء

المرجع

قبل أن تبدؤوا

بدء فحص

الحالات

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

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

الفحوص

التقرير

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

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

الأخطاء

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

​بدء فحص

​الحالات

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

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

​الفحوص

​التقرير

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

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

​الأخطاء

قبل أن تبدؤوا

بدء فحص

الحالات

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

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

الفحوص

التقرير

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

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

الأخطاء