تقييم المخاطر

يأخذ POST /v1/kyc/assess الطلب نفسه الخاص بـ /verify، ويجري التحقق نفسه، ثم يبني فوقه تقييماً. النطاق: kyc:verify. وهو ليس تصنيفاً ائتمانياً. يعيد أربع قراءات للمستشار: تحمّل المخاطر، والقدرة المالية، ومخاطر الامتثال، والملاءمة. كل رقم في هذه الصفحة تحسبه دالة حتمية (deterministic) من values والحكم. المُدخل نفسه يعطي المُخرج نفسه.

الاستجابة

{
  "verification": { "passed": true, "checks": [], "critical_failures": [], "flags": [], "completeness": {}, "policy": {} },
  "assessment": {
    "risk_profile": { "score": 58, "band": "Balanced", "missing": [] },
    "capacity": { "score": 20, "band": "Low", "missing": [] },
    "compliance_risk": { "level": "Low", "score": 1, "factors": ["Flag: KYC/KYB data completeness (61%) (missing 11 required data point(s): ...)"] },
    "suitability": "Suitable",
    "risk_level": "Balanced",
    "verification": { "passed": true }
  },
  "registry": null,
  "case_id": "00000000-0000-4000-8000-000000000001"
}

اختُصر verification هنا؛ وهو الحكم الكامل لـ /verify. ويكرر التقييم الحكم أيضاً تحت assessment.verification. والمثال هو المُخرج الحقيقي للمحرّك على بيانات وهمية (راجع الجولة المتكاملة).

المفتاح	المعنى
`verification`	حكم `/verify`، مع `policy`.
`assessment.risk_profile`	تحمّل العميل للمخاطر، من 0 إلى 100، وشريحته.
`assessment.capacity`	القدرة المالية للعميل، من 0 إلى 100، وشريحتها.
`assessment.compliance_risk`	تصنيف مكافحة غسل الأموال والعناية الواجبة: `level`، و`score` بالنقاط، و`factors` بالكلمات.
`assessment.suitability`	جملة واحدة من قائمة ثابتة.
`assessment.risk_level`	شريحة `risk_profile`. وهي ليست مستوى الامتثال.
`registry`, `case_id`	كما في `/verify`.

تحمّل المخاطر

يتطلب الإجابات الأربع كلها في values. وإذا كانت إحداها فارغة تكون score وband بقيمة null وتسرد missing المفاتيح الغائبة. لا تُحسب درجة جزئية ولا تُفترض قيمة افتراضية.

المُدخل	القيم المقبولة ونقاطها
`objective` (غير حساس لحالة الأحرف)	`capital preservation` 5، `income` 25، `balanced` 50، `growth` 78، `aggressive growth` 95
`horizon`	`< 3 years` 12، `3-5 years` 38، `5-10 years` 68، `> 10 years` 92
`investment_knowledge`	`None` 10، `Limited` 40، `Good` 70، `Excellent` 92
`investment_experience`	`None` 15، `< 5 years` 50، `> 5 years` 85

الإجابة الموجودة لكنها غير مدرجة في الجدول تنال درجة افتراضية: الهدف 50، والأفق 50، والمعرفة 40، والخبرة 40. استخدم النصوص الحرفية أعلاه.

score = objective x 0.35 + horizon x 0.25 + knowledge x 0.20 + experience x 0.20

إذا كانت uses_leverage بقيمة true (منطقية) أو "true" أو "Yes"، تُضاف 8 نقاط. وتُقرَّب النتيجة وتُحصر بين 0 و100.

الدرجة	الشريحة
أقل من 20	Conservative
من 20 إلى 39	Moderate
من 40 إلى 59	Balanced
من 60 إلى 79	Growth
80 فما فوق	Aggressive

مثال: balanced (50)، و5-10 years (68)، وGood (70)، وأقل من 5 سنوات (50) تعطي 50 x 0.35 + 68 x 0.25 + 70 x 0.20 + 50 x 0.20 = 58.5، تُقرَّب إلى 58، Balanced.

القدرة

تتطلب واحداً على الأقل من annual_income وnet_liquid_assets وtotal_net_worth. وبدون أي منها تكون score وband بقيمة null. ومع واحد أو اثنين تُحسب الدرجة وتسرد missing البقية. ويُعدّ المبلغ الغائب بقيمة 0، فيقع في الشريحة الدنيا (درجة فرعية 12 أو 15)، ولذلك فإن الإجابة الغائبة تخفض الدرجة. وتُحلَّل القيم من نصوص مثل 84000 أو 150,000 أو $1.2M أو 84k.

الدخل السنوي	الدرجة الفرعية	الأصول السائلة الصافية	الدرجة الفرعية	صافي الثروة الإجمالي	الدرجة الفرعية
أقل من 50,000	15	أقل من 50,000	12	أقل من 100,000	15
أقل من 100,000	35	أقل من 250,000	35	أقل من 500,000	38
أقل من 250,000	55	أقل من 1,000,000	60	أقل من 2,000,000	62
أقل من 1,000,000	80	أقل من 5,000,000	82	أقل من 10,000,000	85
1,000,000 فما فوق	95	5,000,000 فما فوق	96	10,000,000 فما فوق	97

score = income x 0.30 + liquid x 0.35 + net worth x 0.35

الدرجة	الشريحة
أقل من 30	Low
من 30 إلى 54	Moderate
من 55 إلى 79	High
80 فما فوق	Very High

مثال: دخل 84,000 (35)، وأصول سائلة 20,000 (12)، وصافي ثروة 60,000 (15) تعطي 10.5 + 4.2 + 5.25 = 19.95، تُقرَّب إلى 20، Low. وتُقرأ المبالغ في العيّنة بالدرهم المغربي (MAD). ويقرأ المحرّك المبالغ أرقاماً مجردة مقابل شرائح ثابتة لا ترتبط بعملة معينة، ولذلك تنال 84,000 الدرجة نفسها بأي عملة. لا يحوّل API العملات. فالشرائح بالوحدة التي ترسلها.

مخاطر الامتثال

تُجمع النقاط من الملف الشخصي والحكم.

العامل	النقاط
شخص مكشوف سياسياً (PEP): أي من `pep` أو `pep_foreign` أو `pep_domestic` أو `pep_hio` يساوي `yes` (بأي حالة أحرف)، أو تطابق PEP من الفحص (screening)	2 (مرة واحدة، ولو وُجد الأمران)
الجغرافيا: أسوأ فئة بين `citizenships` (أو `citizenship`) و`country` و`entity_country` (وتعود إلى `country` عند غيابها)	محظورة 6، مرتفعة 3، مرتفعة نسبياً 1، عادية 0
`high_risk_jurisdiction` يساوي `yes`	1
`industry` هو `Virtual assets / Crypto` أو `Money services business` أو `Gaming` أو `Cannabis`	2
`third_party` يساوي `yes`	1
كل فحص حرج فاشل في الحكم	3، ويُفرض المستوى High
كل فحص تحذيري فاشل في الحكم	1

المستوى	القاعدة
High	فشل فحص حرج، أو نقاط تزيد على 3
Medium	2 أو 3 نقاط
Low	0 أو نقطة واحدة

يمكن لسياسة مساحة العمل أن تخفض سقف Low (الافتراضي 1) وسقف Medium (الافتراضي 3)، ولا يمكنها رفعهما أبداً. وتسرد factors كل مساهمة بالكلمات، مثل Flag: <label> (<detail>) أو Verification failed: <label> (<detail>). لا تضيف فحوص المعلومات (info) شيئاً. ولاحظ أن التحذير يُحتسب حتى لو كان مما لا يستطيع العميل إصلاحه، مثل completeness دون 80 بالمئة: فالملف الهزيل يناله نقطة واحدة.

فئات الجغرافيا

مستمدة من القوائم العامة لمجموعة العمل المالي (FATF) حتى 19 يونيو 2026 (FATF_LISTS_AS_OF). والمجموعة لقطة ثابتة في الشيفرة وتُحدَّث بعد كل اجتماع عام لـ FATF. الرموز بصيغة ISO alpha-2. وتُفهم بعض رموز alpha-3 والأسماء (IRN وiran وusa وcanada). وما سوى ذلك يُعدّ عادياً.

الفئة	النقاط	الرموز
محظورة	6	`IR`, `KP`, `MM`, `SY`, `CU`
مرتفعة	3	`AO`, `BO`, `BA`, `BG`, `CM`, `CI`, `CD`, `HT`, `IQ`, `KE`, `KW`, `LA`, `LB`, `MC`, `NP`, `PG`, `SS`, `VE`, `VN`, `VG`, `YE`
مرتفعة نسبياً	1	`PA`, `SC`, `KY`, `BZ`
عادية	0	كل رمز آخر

بلد محظور وحده ينال 6 نقاط، وهو مستوى High. لا تُدخِل هذا الجدول في شيفرة تطبيقك ثابتاً: فهو يتغير مع كل إصدار من FATF.

الملاءمة

تسري أول قاعدة تنطبق.

الترتيب	القاعدة	`suitability`
1	`verification.passed` تساوي false	`Blocked — document verification failed`
2	درجة تحمّل المخاطر 75 فأكثر ودرجة القدرة أقل من 40	`Review — objective exceeds capacity`
3	مستوى الامتثال High	`Enhanced due diligence required`
4	حُجبت درجة تحمّل المخاطر	`Incomplete — suitability answers missing`
5	حُجبت درجة القدرة	`Incomplete — financial capacity answers missing`
6	خلاف ذلك	`Suitable`

Suitable قراءة للمستشار وليست حكماً تنظيمياً بالملاءمة. فالمؤسسة هي التي تتخذ ذلك الحكم.

أمثلة تطبيقية

ملف كامل ونظيف يعطي:

{
  "risk_profile": {
    "score": 58,
    "band": "Balanced",
    "missing": []
  },
  "capacity": {
    "score": 20,
    "band": "Low",
    "missing": []
  },
  "compliance_risk": {
    "level": "Low",
    "score": 1,
    "factors": [
      "Flag: KYC/KYB data completeness (61%) (missing 11 required data point(s): street1, city, province, postal_code, phone, email, source_of_funds, account_type)"
    ]
  },
  "suitability": "Suitable",
  "risk_level": "Balanced"
}

الملف نفسه مع بطاقة هوية وطنية منتهية الصلاحية (تضيف الإخفاقات الحرجة 3 نقاط لكل منها وتفرض High):

{
  "level": "High",
  "score": 7,
  "factors": [
    "Verification failed: national_id — not expired (expired 2024-01-01)",
    "Verification failed: The identity document on file is not expired (expired 2024-01-01)",
    "Flag: KYC/KYB data completeness (61%) (missing 11 required data point(s): street1, city, province, postal_code, phone, email, source_of_funds, account_type)"
  ]
}

قيمة suitability فيه هي Blocked — document verification failed، وتبقى risk_level تقرأ Balanced.

مثال على طلب

curl -X POST https://app.sahlfinancial.com/api/v1/kyc/assess \
  -H "Authorization: Bearer $SAHL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "client-0001",
    "environment": "sandbox",
    "subject": "Test Client",
    "kind": "individual",
    "require_documents": false,
    "values": {
      "first_name": "Test", "last_name": "Client", "country": "MA", "citizenship": "MA",
      "annual_income": "84000", "net_liquid_assets": "20000", "total_net_worth": "60000",
      "objective": "Balanced", "horizon": "5-10 years",
      "investment_knowledge": "Good", "investment_experience": "< 5 years"
    },
    "documents": []
  }'

const res = await fetch("https://app.sahlfinancial.com/api/v1/kyc/assess", {
  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",
    require_documents: false,
    values: {
      first_name: "Test", last_name: "Client", country: "MA", citizenship: "MA",
      annual_income: "84000", net_liquid_assets: "20000", total_net_worth: "60000",
      objective: "Balanced", horizon: "5-10 years",
      investment_knowledge: "Good", investment_experience: "< 5 years",
    },
    documents: [],
  }),
});
const { assessment } = await res.json();
console.log(assessment.risk_profile.band, assessment.capacity.band, assessment.compliance_risk.level, assessment.suitability);

import os, requests

res = requests.post(
    "https://app.sahlfinancial.com/api/v1/kyc/assess",
    headers={"Authorization": f"Bearer {os.environ['SAHL_API_KEY']}"},
    json={
        "reference": "client-0001",
        "environment": "sandbox",
        "subject": "Test Client",
        "kind": "individual",
        "require_documents": False,
        "values": {
            "first_name": "Test", "last_name": "Client", "country": "MA", "citizenship": "MA",
            "annual_income": "84000", "net_liquid_assets": "20000", "total_net_worth": "60000",
            "objective": "Balanced", "horizon": "5-10 years",
            "investment_knowledge": "Good", "investment_experience": "< 5 years",
        },
        "documents": [],
    },
    timeout=60,
)
res.raise_for_status()
a = res.json()["assessment"]
print(a["risk_profile"]["band"], a["capacity"]["band"], a["compliance_risk"]["level"], a["suitability"])

مع documents: [] وrequire_documents: false لا تترتب على المثال أعلاه فحوص وثائقية، ولذلك يعتمد خطر الامتثال على تحذير completeness وسطر الفحص (screening) في بيئتك. أما risk_profile وcapacity المتوقعتان فهما نفسهما أعلاه.

ملخص Webhook

يحمل الحدث kyc.case_assessed القيمتين risk_level وsuitability في ملخص verdict. وهناك تكون risk_level هي compliance_risk.level (Low أو Medium أو High)، لا شريحة تحمّل المخاطر. راجع Webhooks.

البدء

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

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