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

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

> POST /v1/kyc/verify: الطلب، وطبقات الفحص الثلاث، وكل معرّف فحص، وكيفية قراءة passed وflags.

يُرجع `POST /v1/kyc/verify` الحكم على ملف العميل والمستندات المرتبطة به. النطاق: `kyc:verify`. لا يقرأ الملفات ولا يستهلك أي قراءة مستند. يقبل `POST /v1/kyc/assess` الجسم نفسه، ويُجري الحكم نفسه، ويضيف [تقييمًا للمخاطر](/ar/guides/risk-assessment).

## الطلب

جسم 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](#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` | فحوص الإقرارات و[المخاطر](/ar/guides/risk-assessment) |
| `verified_in_person` | سياسة تشترط eID للعملاء الذين لم تتم مقابلتهم حضوريًا |
| `objective`, `horizon`, `investment_knowledge`, `investment_experience`, `uses_leverage`, `industry`, `high_risk_jurisdiction`, `citizenships` | [تقييم المخاطر](/ar/guides/risk-assessment) |

## الرد

```json theme={null}
{
  "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` | علامة امتثال. يمكن للملف أن يتابع. | أحِله إلى شخص. يُحتسب بنقطة واحدة في [تقييم المخاطر](/ar/guides/risk-assessment). |
| `info` | يُحفظ لأغراض مسار التدقيق. تكون `passed` عادةً `true`. | لا شيء. |

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

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

```mermaid theme={null}
flowchart TD
    D[documents[] entries] --> L1[Layer 1: per document]
    L1 --> L2[Layer 2: across documents and values]
    V[values] --> L2
    L2 --> L3[Layer 3: screening, determinations, completeness]
    P[Workspace policy] --> L3
    X[extra_checks] --> L3
    L3 --> R[passed, checks, flags, completeness]
```

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

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

## الفحوص

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

### لكل مستند

| المعرّف | الخطورة | ينجح عندما | عند الفشل |
| - | - | - | - |
| `doctype:*` | critical | يكون `doc_type` الذي حدده القارئ من الأنواع التي تقبلها الخطوة. لا يعمل إلا إذا كانت الخطوة أو التلميح يقيّد النوع. | يحدد التفصيل ماهية المستند وما تقبله الخطوة. اطلب المستند الصحيح. |
| `legible:*` | critical إذا كانت كل الحقول المتوقعة مفقودة، وإلا warning | قُرئت الحقول الأساسية للنوع ([القائمة](/ar/guides/document-types)). | يسرد التفصيل `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 | صيغ الأرقام بحسب البلد. انظر [فحوص الصيغة](/ar/guides/document-types). | غالبًا خطأ في القراءة. |

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

| المعرّف | الخطورة | ينجح عندما | عند الفشل |
| - | - | - | - |
| `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](/ar/guides/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` | سياسة محفوظة لم تعد صالحة. جرى الاستدعاء وفق القالب الجاهز أو الإعداد الافتراضي بدلًا منها. |

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

```json theme={null}
"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 | التشديد فقط. انظر [تقييم المخاطر](/ar/guides/risk-assessment). |
| `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` دمج فحص أجريتَه بنفسك، كعميل مكرر أو قائمة حظر في قاعدة بياناتك، في الحكم ليتمكن من حجبه.

```json theme={null}
"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](/ar/guides/webhooks) الحدث `kyc.case_verified` بعد إتمام الحفظ.

## أمثلة

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      }]
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

### ملف محجوب

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

```json theme={null}
{
  "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" }
  ]
}
```


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