التحقق من ملف عميل

يُرجع POST /v1/kyc/verify الحكم على ملف العميل والمستندات المرتبطة به. النطاق: kyc:verify. لا يقرأ الملفات ولا يستهلك أي قراءة مستند. يقبل POST /v1/kyc/assess الجسم نفسه، ويُجري الحكم نفسه، ويضيف تقييمًا للمخاطر.

الطلب

جسم JSON. جميع الحقول اختيارية، لكن الجسم الفارغ لا يتحقق من شيء.

الحقل	النوع	الافتراضي	المعنى
`reference`	string	none	معرّفك للعميل، من 1 إلى 64 حرفًا من `A-Z a-z 0-9 _ . : -`. عند وجوده يُحفظ الحكم في الحالة ويحتوي الرد على `case_id`. القيمة غير الصالحة تعطي 422.
`environment`	string	`sandbox`	`sandbox` أو `production`.
`subject`	string	none	اسم العميل أو اسمه القانوني، حتى 255 حرفًا.
`values`	object	`{}`	ملف العميل: مفاتيح الحقول وقيمها. انظر values.
`documents`	array	`[]`	عناصر `documents[]` التي أرجعها `/extract`، دون تعديل.
`kind`	string	none	`individual` أو `corporation` أو `partnership` أو `charitable_org` أو `trust` أو `estate`. المرادفات: `entity` و`business` و`corporate` و`kyb` (corporation)، و`societe` (partnership)، و`charity` (charitable_org)، و`fiducie` (trust)، و`succession` (estate). أي قيمة أخرى تُعامل على أنها `individual`.
`entity`	boolean	`false`	مؤشر تقريبي يُستخدم عندما تكون قيمة `kind` فارغة. القيمة true تعني شركة (corporation).
`require_documents`	boolean	`true`	طلب وثيقة الهوية. انظر السياسة والمفاتيح.
`screen`	boolean	`true`	فحص كل الأطراف في الملف. انظر الفحص.
`canadian_screening`	boolean or null	null	فحص كندي إضافي لعميل كندي. القيمة null تترك القرار لسياسة مساحة العمل.
`extra_checks`	array	`[]`	فحوص أجريتَها بنفسك وتُضاف إلى الحكم. انظر فحوصك الخاصة.
`purpose`	string	`onboarding`	`onboarding` أو `periodic_review`.

`values`

values كائن حر. يقرأ المحرك المفاتيح أدناه ويتجاهل الباقي. أرسل قيمًا نصية. التواريخ بصيغة YYYY-MM-DD. يعدّ فحص الاكتمال هذه المفاتيح موجودة عندما لا تكون فارغة.

النوع	بيانات مطلوبة
`individual` (26 مفتاحًا، إضافة إلى مجموعتين بديلتين)	`first_name`, `last_name`, `date_of_birth`, `citizenship`, `id_type`, `id_number`, `id_expiry`, `street1`, `city`, `province`, `postal_code`, `country`, `phone`, `email`, `occupation`, `employer_name`, `annual_income`, `net_liquid_assets`, `total_net_worth`, `source_of_funds`, `objective`, `horizon`, `investment_knowledge`, `investment_experience`, `account_type`, `third_party`. المجموعتان البديلتان: `sin` أو `ssn`؛ وأي مفتاح من `pep_foreign`, `pep_domestic`, `pep_hio`, `pep`.
`corporation`, `partnership`, `charitable_org`, `estate` (21 مفتاحًا)	`legal_name`, `business_number`, `incorporation_date`, `entity_address`, `entity_city`, `entity_province`, `entity_postal`, `industry`, `source_of_wealth`, `expected_activity`, `rp_first_name`, `rp_last_name`, `rp_id_type`, `rp_id_number`, `director_names`, `beneficial_owners`, `ownership_control_structure`, `bo_accuracy_measure`, `account_type`, `objective`, `horizon`
`trust` (17 مفتاحًا)	`legal_name`, `entity_address`, `entity_city`, `entity_province`, `entity_postal`, `source_of_wealth`, `expected_activity`, `rp_first_name`, `rp_last_name`, `rp_id_type`, `rp_id_number`, `beneficiaries`, `ownership_control_structure`, `bo_accuracy_measure`, `account_type`, `objective`, `horizon`

بُنيت قائمة المطلوبات من محرك صُمّم أصلًا لملفات أمريكا الشمالية. فهو يطلب province وpostal_code وsin أو ssn، لذلك لا يمكن لفرد مغربي أن يبلغ أكثر من 27 من 28 (96 بالمئة)، ويبقى sin/ssn في missing. لا يُعلَّم الملف إذا بلغت النسبة 80 بالمئة أو أكثر. تستخدم الطلبات النموذجية هنا البلد MA وid_type بقيمة National ID ورقم بطاقة وطنية مثل BK123456؛ ويقبل province وpostal_code أي نص لعنوان مغربي، ولا يُتحقق من صيغة الرمز البريدي الكندي إلا عندما يكون country هو CA. مفاتيح أخرى تستخدمها الفحوص:

المفاتيح	تُستخدم في
`sin`, `ssn`, `email`, `postal_code`, `province`, `date_of_birth`	فحوص `format:` و`age:`
`id_expiry`	`expiry:recorded:id_expiry` و`expiry_soon:recorded:id_expiry`
`bank_number`, `bank_transit`, `bank_routing`, `bank_account`	فحوص `bank:` و`format:bank_`
`other_names`	أسماء إضافية للفحص (الأسماء السابقة وأسماء العائلة قبل الزواج)
`country`, `entity_country`, `incorporation_jurisdiction`	قواعد البلد، والبحث في السجل، وأهلية eID
`ice`, `if_number`, `registration_number`, `tax_id`, `iban`	فحوص صيغة بيانات الكيان
`pep`, `pep_foreign`, `pep_domestic`, `pep_hio`, `third_party`	فحوص الإقرارات والمخاطر
`verified_in_person`	سياسة تشترط eID للعملاء الذين لم تتم مقابلتهم حضوريًا
`objective`, `horizon`, `investment_knowledge`, `investment_experience`, `uses_leverage`, `industry`, `high_risk_jurisdiction`, `citizenships`	تقييم المخاطر

الرد

{
  "passed": true,
  "checks": [
    { "id": "format:cin:national_id", "label": "national_id — CIN number is well-formed", "severity": "warning", "passed": true, "detail": "" },
    { "id": "screening", "label": "Sanctions screening — no matches; PEP not list-screened", "severity": "info", "passed": true, "detail": "screened against 23000 sanctions entries. The bundle carries no PEP list, so politically-exposed status rests on the client's declaration, not on a list check." },
    { "id": "completeness", "label": "KYC/KYB data completeness (61%)", "severity": "warning", "passed": false, "detail": "missing 11 required data point(s): street1, city, province, postal_code, phone, email, source_of_funds, account_type" }
  ],
  "critical_failures": [],
  "flags": [
    { "id": "completeness", "label": "KYC/KYB data completeness (61%)", "severity": "warning", "passed": false, "detail": "missing 11 required data point(s): street1, city, province, postal_code, phone, email, source_of_funds, account_type" }
  ],
  "completeness": {
    "required": 28,
    "present": 17,
    "missing": ["street1", "city", "province", "postal_code", "phone", "email", "source_of_funds", "account_type", "third_party", "sin/ssn", "pep_foreign/pep_domestic/pep_hio/pep"],
    "percent": 61
  },
  "policy": { "id": null, "version": 0, "source": "legacy", "regime": "none", "regulator": null, "purpose": "onboarding", "overrides_refused": [] },
  "registry": null,
  "case_id": "00000000-0000-4000-8000-000000000001"
}

قائمة checks أعلاه مختصرة إلى ثلاثة عناصر؛ والرد الكامل فيه أكثر. المثال هو المخرج الفعلي للمحرك لبيانات وهمية (بطاقة وطنية مغربية وكشف راتب باسم Test Client).

المفتاح	المعنى
`passed`	تكون `true` عندما لا يفشل أي فحص بخطورة `critical`. التحذيرات لا تغيّرها أبدًا.
`checks`	كل فحص جرى، سواء نجح أم لا.
`critical_failures`	الفحوص التي قيمتها `passed: false` وخطورتها `critical`. هذه تحجب الملف.
`flags`	كل ما يحتاج إلى شخص: الفحوص الحرجة الفاشلة والتحذيرات الفاشلة. فحوص `info` لا تكون علامات أبدًا.
`completeness`	بيانات `required` المطلوبة، وعدد الموجود منها `present`، والمفاتيح الناقصة `missing`، والنسبة `percent`.
`policy`	سياسة مساحة العمل التي جرى الحكم وفقها. انظر السياسة.
`registry`	ما تُدرجه Corporations Canada لشركة فيدرالية (CBCA)، بعد التوحيد. تكون null في كل حالة أخرى.
`case_id`	يظهر فقط مع `reference`.

لكل فحص خمسة مفاتيح.

المفتاح	المعنى
`id`	معرّف ثابت. اعتمد عليه في المطابقة. بعض المعرّفات تنتهي بتسمية مستند (`expiry:national_id`) أو باسم طرف موحَّد.
`label`	جملة موجهة للقارئ البشري.
`severity`	`critical` أو `warning` أو `info`.
`passed`	`true` أو `false`.
`detail`	السبب عند الفشل. فارغ عند النجاح.

لا تطابق على label: فقد يتغير. طابق على id، وعامل الجزء الذي يلي أول نقطتين رأسيتين على أنه متغير.

كيف تقرأ الحكم

الخطورة	معنى `passed: false`	الإجراء المقترح
`critical`	يحجب. تصبح `passed` مساوية `false` للملف كله.	توقف. عالج السبب أو أحِل الملف إلى مراجع.
`warning`	علامة امتثال. يمكن للملف أن يتابع.	أحِله إلى شخص. يُحتسب بنقطة واحدة في تقييم المخاطر.
`info`	يُحفظ لأغراض مسار التدقيق. تكون `passed` عادةً `true`.	لا شيء.

ينجح الملف عندما لا يفشل أي فحص حرج. الملف الذي فيه 30 تحذيرًا ينجح مع ذلك، لذا انظر إلى flags وكذلك إلى passed.

الطبقات الثلاث

لكل مستند: الفحوص نفسها التي أرجعها /extract لكل ملف (النوع، والقابلية للقراءة، والانتهاء، والبلوغ، وMRZ، والحداثة، والمصدر، والنموذج التجريبي).
بين المستندات والملف الشخصي: اتفاق الاسم وتاريخ الميلاد والعنوان بين المستندات ومع values؛ وصيغ الأرقام؛ والبيانات المصرفية؛ ووجود وثيقة الهوية المطلوبة بين المرفوعات.
على مستوى الملف: فحص العقوبات والأشخاص السياسيين المعرّضين (PEP)، والمستفيد الفعلي للكيانات، وفحوص السجل، وإقرارات السياسة، ثم الاكتمال.

التحقق حتمي: المدخل نفسه يعطي الحكم نفسه، باستثناء الفحص (الذي يعتمد على القائمة المحمّلة) والتاريخ الذي يأتي من ساعة الخادم.

الفحوص

تُسرد المعرّفات مع استبدال الجزء الذي يلي أول نقطتين رأسيتين بـ *. “المستند” يعني تسمية الخطوة أو التلميح doc_type (مثل passport، أو Government photo ID عند إرسال step_key).

لكل مستند

المعرّف	الخطورة	ينجح عندما	عند الفشل
`doctype:*`	critical	يكون `doc_type` الذي حدده القارئ من الأنواع التي تقبلها الخطوة. لا يعمل إلا إذا كانت الخطوة أو التلميح يقيّد النوع.	يحدد التفصيل ماهية المستند وما تقبله الخطوة. اطلب المستند الصحيح.
`legible:*`	critical إذا كانت كل الحقول المتوقعة مفقودة، وإلا warning	قُرئت الحقول الأساسية للنوع (القائمة).	يسرد التفصيل `could not read: ...`. اطلب مسحًا أوضح.
`expiry:*`	critical	يكون `id_expiry` اليوم أو بعده.	`expired YYYY-MM-DD`. اطلب هوية سارية.
`expiry_soon:*`	warning	لا تنتهي الهوية خلال 90 يومًا (السياسة `id_expiry_days`).	يفشل فقط عندما تنتهي خلال هذه المدة. ليس حجبًا.
`adult:*`	critical	يبلغ صاحب وثيقة الهوية 18 سنة أو أكثر.	`holder is N`.
`mrz:*`	critical	أرقام التحقق في MRZ صحيحة (ICAO 9303، جواز السفر سطران من 44، بطاقة الهوية 3 أسطر من 30).	احتمال تلاعب أو قراءة سيئة.
`mrz:unreadable:*`	warning	يُضاف فقط عند قراءة MRZ جواز سفر تعذّر تحليله.	لم يُتحقق من الأرقام.
`mrz:dob:`, `mrz:docnum:`	warning	يطابق تاريخ الميلاد ورقم المستند في MRZ الحقول المطبوعة.	يقول MRZ شيئًا وتقول البطاقة شيئًا آخر.
`recency:*`	critical في خطوة إثبات العنوان أو لمستند `utility_bill` أو `proof_of_address`، وإلا warning	الأقدم بين التاريخ المطبوع وتاريخ الملف ضمن 90 يومًا (السياسة `document_recency_days`).	`effective date X is N days old`. فقط لـ `utility_bill` و`proof_of_address` و`bank_statement`.
`recency:future:*`	critical	التاريخ المطبوع ليس في المستقبل.
`authenticity:*`	warning	تاريخ الملف ليس أقدم من التاريخ المطبوع بأكثر من 14 يومًا (السياسة `backdate_days`).	احتمال تعديل أو تأريخ رجعي.
`provenance:editor:*`	warning	لا يذكر الملف برنامج تحرير صور أو PDF (Photoshop وGIMP وCanva وSejda وSmallpdf وما شابهها) على أنه البرنامج المنتج له.	ليس دليلًا على احتيال. قد يطمس الناس بيانات حساسة في ملفاتهم. أحِله إلى مراجع.
`provenance:revisions:`, `provenance:modified:`, `provenance:future:*`	warning	صدر مرة واحدة، ولم يُعدَّل بعد إنشائه، وتواريخ الملف معقولة.	كما سبق.
`provenance:reprint:*`	info	تُسجَّل الطباعة من متصفح أو هاتف وتنجح.
`authenticity:specimen:*`	critical	المستند ليس نموذجًا تجريبيًا (specimen) أو عينة أو قالبًا. يُفعَّل بكلمات مثل SPECIMEN أو SAMPLE، أو اسم حامل وهمي (`John Doe`, `Customer`, `Specimen Test Card`)، أو عنوان قالب (`123 Any St`)، أو رقم نموذجي (`P123456AA`، أو سلسلة من رقم واحد، أو `123456789`).	استخدم مستندًا حقيقيًا.
`format:cin:`, `format:licence:`, `consistency:licence:`, `format:iban:`, `format:national_id`	warning	صيغ الأرقام بحسب البلد. انظر فحوص الصيغة.	غالبًا خطأ في القراءة.

بين المستندات والملف الشخصي

المعرّف	الخطورة	ينجح عندما	عند الفشل
`required:photo_id`	critical	توجد بين المستندات هوية حكومية مصوّرة مقروءة (جواز سفر، أو بطاقة وطنية، أو رخصة سياقة، أو بطاقة PR، أو تصريح إقامة). فقط عندما تكون `require_documents` مساوية true.	`no readable government photo ID among the uploads`.
`required:incorporation`, `required:partnership_agreement`, `required:trust_deed`, `required:estate_authority`	critical	يوجد المستند الذي يُنشئ كيانًا من ذلك النوع.	يسمّي التفصيل ما هو مفقود.
`consistency:name`, `consistency:name_unreadable`	critical	كل إثبات عنوان أو كشف حساب مصرفي أو وثيقة كيان يخص مقدّم الطلب أو الكيان. أسماء الحاملين غير المقروءة تحجب أيضًا.	فاتورة تخص طرفًا ثالثًا.
`consistency:poa_name_id`, `consistency:profile_name_id`, `consistency:id_name`	critical	إثبات العنوان باسم صاحب الهوية، والاسم في `values` هو الشخص المذكور في الهوية، وهويتان تخصان الشخص نفسه.
`consistency:dob`	critical	يتفق تاريخ الميلاد بين المستندات.
`consistency:address`, `consistency:profile_address_docs`, `consistency:postal_province`	warning	يتفق العنوان بين المستندات ومع `values`؛ ويطابق الرمز البريدي المقاطعة.
`expiry:recorded:id_expiry`	critical	قيمة `id_expiry` في `values` لم تنتهِ.
`expiry_soon:recorded:id_expiry`	warning	لا تنتهي خلال 90 يومًا.
`format:sin`	critical	يجتاز `sin` فحص Luhn.
`format:sin_series`, `format:sin_temporary`	warning	لا يبدأ SIN بـ 0 أو 8، ويُعلَّم الرقم الذي يبدأ بـ 9 على أنه من سلسلة المقيمين المؤقتين.
`format:ssn`, `format:email`, `format:postal`	warning	SSN وبريد إلكتروني ورمز بريدي كندي صالحة البنية.
`age:majority`	warning	يُعلَّم من عمره 18 سنة في مقاطعة سن الرشد فيها 19.
`bank:split`	warning	البيانات المصرفية في الحقول الصحيحة (رقم توجيه من 9 أرقام ليس في `bank_number`).
`format:bank_institution`, `format:bank_transit`, `format:bank_routing`	warning	مؤسسة من 3 أرقام، وtransit من 5 أرقام، ومجموع تحقق ABA لرقم توجيه من 9 أرقام.
`consistency:bank_account`	warning	رقم حساب واحد عبر الكشوف.

على مستوى الملف

المعرّف	الخطورة	ينجح عندما	عند الفشل
`screening`	info أو critical	انظر الفحص.
`screening:sanctions:*`	critical	لا يوجد للطرف تطابق في العقوبات.	`matches sanctions entry 'X' (source, N%) ... blocked pending manual review`.
`screening:pep:*`	warning	لا يوجد للطرف تطابق مع PEP.	العناية الواجبة المعززة.
`screening:review:*`	warning	لا سجل سلبي أو تنظيمي (أمر تأديبي، أو أمر بوقف التداول، أو أخبار سلبية).	راجع قبل الموافقة.
`screening:canchek`, `screening:canchek_skipped`, `screening:canchek_unavailable`	info / info / warning	جرى الفحص الكندي / كان مطلوبًا لكن مساحة العمل بلا حساب / لم تُجب الخدمة.	فُحص مقابل الحزمة فقط. افحص مجددًا قبل الموافقة.
`completeness`	warning	يوجد 80% على الأقل من البيانات المطلوبة.	يسرد التفصيل أول 8 مفاتيح ناقصة.
`bo:none_recorded`, `bo:names_only`, `bo:addresses`, `bo:senior_officer`, `bo:unconfirmed_risk`	warning	سُجّل المستفيد الفعلي أشخاصًا مع عناوينهم، وسُمّي أعلى مسؤول إداري، وتأكدت الملكية. للكيانات فقط.
`discrepancy:*`	warning أو info	الشركات الفيدرالية: يتفق المستفيدون الفعليون مع Corporations Canada، وأُبلغ عن أي تباين.
`registry:found`, `registry:active`, `registry:directors`	warning, critical, info أو warning	الشركة الفيدرالية موجودة، وفاعلة، ويتفق مديروها مع السجل. فقط لشركات CBCA عندما تفعّل السياسة البحث.
`registry:`, `registry:manual:`	warning	الولايات القضائية الأخرى: يسمّي السجل الذي على المراجع الرجوع إليه.
`format:ice`, `format:if_number`, `format:rc`, `required:ma_identifiers`, `format:business_number`, `format:ein`, `format:registration_number`, `format:tax_id`, `required:*_identifiers`	warning	معرّفات الشركة سليمة الصيغة ومسجَّلة.
`determination:pep_hio`, `determination:third_party`	warning	تطلب السياسة أن يسجّل الملف هذه الإجابات وهي موجودة.
`policy:eid_non_face_to_face`	critical	انظر eID.
`document:*`	warning أو critical	تفرض السياسة خانات المستندات والخانة موجودة.
`policy:periodic_review`, `policy:periodic_review_unanchored`, `policy:override_refused:*`, `policy:met_in_person_declared`	info / warning / info / info	انظر السياسة والمفاتيح.
`partner:*`	بحسب ما أرسلت	فحوصك الخاصة، انظر أدناه.

الفحص

يُفحص كل طرف في الملف افتراضيًا (screen: true).

الملف	الأطراف المفحوصة
فرد	الحامل (الاسم الأول والأوسط والأخير) وكل اسم في `other_names`.
كيان	`legal_name`، والمسؤول الموقِّع (`rp_*`)، وكل اسم في `director_names` و`beneficial_owners`، و`other_names`. تُزال التكرارات.

التطابق مع العقوبات حرج ويحجب. التطابق مع PEP تحذير. النتيجة النظيفة تنتج فحص screening واحدًا يذكر ما فُحص الطرف مقابله:

فحص `screening`	الخطورة	المعنى
`Sanctions screening — no matches; PEP not list-screened`	info، ناجح	فُحص مقابل حزمة العقوبات (OFAC والقائمة الموحدة للأمم المتحدة وOSFI). لا تحتوي هذه الحزمة على قائمة PEP، لذا يستند وضع PEP إلى إقرار العميل.
`Sanctions/PEP screening — no matches`	info، ناجح	فُحص مقابل مصدر يتضمن جداول PEP (الفحص الكندي).
`Sanctions/PEP screening — sample list only`	warning	لدى البيئة قائمة عيّنة من 30 اسمًا فقط. وهي ليست فحصًا مطابقًا للمتطلبات. لا ينبغي أن تراها في الإنتاج.
`Sanctions/PEP screening — NOT PERFORMED`	critical	لم تُحمَّل أي قائمة.
`Sanctions/PEP screening — coverage unknown`	critical	تعذّر تحديد القائمة المستخدمة. عامل الطرف على أنه غير مفحوص.

عندما تكون canadian_screening مساوية true (أو تطلبها السياسة) ويكون العميل كنديًا (country هو CA أو CAN أو Canada)، تُفحص الأطراف التي لم تجد الحزمة عنها شيئًا كذلك مقابل جداول AML وPEP الكندية لدى مزود eID، متى كان لمساحة العمل حساب. ويذكر فحص screening:canchek عدد الأطراف المفحوصة.

السياسة والمفاتيح

يجري كل استدعاء وفق سياسة KYC الخاصة بمساحة عملك لنوع العميل (kyc للشخص، وkyb لأي كيان) وللبيئة. ويحدد policy في الرد أيّ سياسة طُبّقت.

`policy.source`	المعنى
`tenant`	سياسة محفوظة في الوحدة (الإعدادات، سياسة KYC)، بالإصدار `version`.
`preset`	لا سياسة محفوظة. القالب الجاهز للنظام التنظيمي لمساحة عملك (FINTRAC لكندا، وBSA/CIP للولايات المتحدة، والقانون 43-05 للمغرب).
`legacy`	لا سياسة محفوظة ولا نظام تنظيمي: الإعداد الافتراضي الخفيف. لا شيء مقفل.
`fallback`	سياسة محفوظة لم تعد صالحة. جرى الاستدعاء وفق القالب الجاهز أو الإعداد الافتراضي بدلًا منها.

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

"policy": {
  "source": "preset",
  "regime": "fintrac",
  "purpose": "onboarding",
  "overrides_refused": [
    { "field": "screen", "requested": false, "enforced": true, "locked_item": "sanctions_screening" }
  ]
}

(للتوضيح: شكل overrides_refused حقيقي، أما القيم فمثال.) كما يضيف الرفض فحص info هو policy:override_refused:screen.

المفتاح	يُحترم عندما
`require_documents: false`	لا تقفل السياسة `id_verification`، أو تكون `purpose` هي `periodic_review`.
`screen: false`	لا تقفل السياسة `sanctions_screening`.
`canadian_screening: false`	لا تقفل السياسة الفحص الكندي.

ما يمكن للسياسة تغييره:

الإعداد	الافتراضي	الأثر
`thresholds.document_recency_days`	90	نافذة إثبات العنوان (من 1 إلى 365).
`thresholds.backdate_days`	14	الفارق بين تاريخ الملف والتاريخ المطبوع الذي يُعلَّم.
`thresholds.id_expiry_days`	90	نافذة `expiry_soon` (من 0 إلى 365).
`risk_bands.low_max_points`, `medium_max_points`	1 و3	التشديد فقط. انظر تقييم المخاطر.
`beneficial_ownership_threshold_pct`	25	نسبة الملكية التي يجب تسمية صاحبها. حتى 25.
`enabled_checks`	كل العائلات	العائلات التي تظهر في الحكم. فحوصك `extra_checks` ونتائج eID لا تُصفّى أبدًا.
`document_slot_enforcement`	`off`	القيمة `warning` أو `critical` تضيف فحوص `document:*` للخانات المطلوبة.
`eid_required_non_face_to_face`	false	الشخص الذي لم تتم مقابلته حضوريًا يجب أن يجتاز فحص eID.

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

المراجعة الدورية

purpose: "periodic_review" مخصّصة لعميل جرى تسجيله مسبقًا. فهي لا تعيد التحقق من الهوية (PCMLTFR s.155(1)): لا تُطبَّق وثائق الهوية ومتطلب eID وفحوص الخانات. ويبقى الفحص والإقرارات وكل قفل آخر ساريًا.

مع وجود تسجيل ناجح لدى Sahl للعميل نفسه بالـ reference والـ environment نفسيهما، تضيف المراجعة فحص info هو policy:periodic_review.
وبدون ذلك، أو بدون reference، تُقبل المراجعة لكنها تضيف تحذيرًا هو policy:periodic_review_unanchored: جرى تجاوز الهوية بناءً على قولك وحده.

فحوصك الخاصة

يتيح extra_checks دمج فحص أجريتَه بنفسك، كعميل مكرر أو قائمة حظر في قاعدة بياناتك، في الحكم ليتمكن من حجبه.

"extra_checks": [
  { "id": "internal:duplicate_client", "label": "No duplicate client in our database", "severity": "critical", "passed": false, "detail": "matches client 8812" }
]

يحتاج كل فحص إلى id وlabel وseverity (critical أو warning أو info) وpassed؛ أما detail فاختياري. المعرّف الذي يبدأ بـ eid: أو policy: مقصور على Sahl: يعود بصيغة partner:eid:... أو partner:policy:...، ويظهر ويمكنه الحجب، لكنه لا يحقق أبدًا متطلب eID في السياسة.

سجل Corporations Canada

بالنسبة إلى corporation يقول المستشار إنها مؤسَّسة فيدراليًا (CBCA)، وعندما تفعّل السياسة ذلك (مفعّل افتراضيًا)، تبحث Sahl عن الشركة. ويحتوي registry حينئذ على السجل بعد توحيده، فتستطيع تعبئة بياناتك منه، وتقارنه فحوص registry: ببياناتك. وفي كل حالة أخرى يكون registry مساويًا null.

الحفظ

مع reference يُحفظ الحكم في الحالة الخاصة بـ (مساحة العمل، البيئة، reference). وتُربط به المستندات التي جاء document_id الخاص بها من /extract. ولا يُلغي حكم جديد أبدًا حالة وضعها شخص (approved أو refused). ويُطلق webhook الحدث kyc.case_verified بعد إتمام الحفظ.

أمثلة

curl -X POST https://app.sahlfinancial.com/api/v1/kyc/verify \
  -H "Authorization: Bearer $SAHL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "client-0001",
    "environment": "sandbox",
    "subject": "Test Client",
    "kind": "individual",
    "values": {
      "first_name": "Test", "last_name": "Client", "date_of_birth": "1988-04-12",
      "citizenship": "MA", "country": "MA",
      "id_type": "National ID", "id_number": "BK123456", "id_expiry": "2030-05-01"
    },
    "documents": [{
      "filename": "cin-test.jpg", "doc_type": "national_id", "step_hint": "national_id",
      "step_key": null, "mapped": 9, "notes": [],
      "fields": {
        "first_name": "Test", "last_name": "Client", "date_of_birth": "1988-04-12",
        "id_type": "National ID", "id_number": "BK123456", "id_expiry": "2030-05-01",
        "citizenship": "MA", "id_country": "MA", "document_holder_name": "Test Client"
      }
    }]
  }'

const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAHL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: "client-0001",
    environment: "sandbox",
    subject: "Test Client",
    kind: "individual",
    values: { first_name: "Test", last_name: "Client", date_of_birth: "1988-04-12" },
    documents: extracted.documents, // from /extract, unchanged
  }),
});
const verdict = await res.json();
if (!verdict.passed) {
  for (const c of verdict.critical_failures) console.log(c.id, c.detail);
}

import os, requests

res = requests.post(
    "https://app.sahlfinancial.com/api/v1/kyc/verify",
    headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
    json={
        "reference": "client-0001",
        "environment": "sandbox",
        "subject": "Test Client",
        "kind": "individual",
        "values": {"first_name": "Test", "last_name": "Client", "date_of_birth": "1988-04-12"},
        "documents": extracted["documents"],  # from /extract, unchanged
    },
    timeout=60,
)
res.raise_for_status()
verdict = res.json()
for c in verdict["critical_failures"]:
    print(c["id"], c["detail"])

ملف محجوب

بطاقة وطنية منتهية الصلاحية تعطي passed: false وإخفاقين حرجين، أحدهما من المستند والآخر من الملف الشخصي:

{
  "passed": false,
  "critical_failures": [
    { "id": "expiry:national_id", "label": "national_id — not expired", "severity": "critical", "passed": false, "detail": "expired 2024-01-01" },
    { "id": "expiry:recorded:id_expiry", "label": "The identity document on file is not expired", "severity": "critical", "passed": false, "detail": "expired 2024-01-01" }
  ]
}

البدء

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

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

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

البناء

المرجع

التحقق من ملف عميل

الطلب

`values`

الرد

كيف تقرأ الحكم

الطبقات الثلاث

الفحوص

لكل مستند

بين المستندات والملف الشخصي

على مستوى الملف

الفحص

السياسة والمفاتيح

المراجعة الدورية

فحوصك الخاصة

سجل Corporations Canada

الحفظ

أمثلة

ملف محجوب

​الطلب

​values

​الرد

​كيف تقرأ الحكم

​الطبقات الثلاث

​الفحوص

​لكل مستند

​بين المستندات والملف الشخصي

​على مستوى الملف

​الفحص

​السياسة والمفاتيح

​المراجعة الدورية

​فحوصك الخاصة

​سجل Corporations Canada

​الحفظ

​أمثلة

​ملف محجوب

الطلب

`values`

الرد

كيف تقرأ الحكم

الطبقات الثلاث

الفحوص

لكل مستند

بين المستندات والملف الشخصي

على مستوى الملف

الفحص

السياسة والمفاتيح

المراجعة الدورية

فحوصك الخاصة

سجل Corporations Canada

الحفظ

أمثلة

ملف محجوب