إعدادات ميزات سير العمل: مرجع API

استخدم حقول config التالية داخل كل عنصر من عناصر المصفوفة features في طلبات POST /v3/workflows/ وPATCH /v3/workflows/{settings_uuid}/.

{
  "workflow_label": "Standard KYC",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        }
      }
    }
  ]
}

تُنشئ واجهة برمجة تطبيقات سير العمل v3 سير عمل خطياً قائماً على العقد من المصفوفة المرتبة features. أرسل الميزات بترتيب التنفيذ الدقيق.

أي محرك يشغّل ميزة، سواء كان محرك Didit الخاص أو مزوداً خارجياً، ليس أحد حقول config أدناه. تتم إدارته من خلال Marketplace في الكونسول، الذي يضبط provider_key وfallback_to_native في كائن config الخاص بالميزة نيابةً عنك.

قواعد التحقق

تكون قيمة OCR الافتراضية شاملة لجميع الدول وأنواع المستندات المدعومة عندما يُحذف config.documents_allowed أو يكون null أو {}. إذا أرسلت كائن documents_allowed مخصصاً، فيجب أن يحتوي على دولة صالحة واحدة على الأقل ونوع مستند مفعّل واحد على الأقل. يمكن لإعداد كل مستند أن يضبط sides على 1 لالتقاط الوجه الأمامي فقط، أو على 2 لالتقاط الوجهين الأمامي والخلفي.
يتطلب QUESTIONNAIRE وجود config.questionnaire_uuid.
يتطلب KYB_DOCUMENTS وجود config.kyb_required_document_groups.
يرفض SIGNATURE القيمة signature_level: "qes" مع الخطأ qes_not_available إلى أن تصبح التواقيع المؤهلة متاحة، ويرفض خطوة جديدة بقيمة signature_level: "aes" مع الخطأ aes_not_available ما دام signature_availability.aes يساوي false في سير العمل. ويجب أن تكون مستنداته موجودة عند إنشاء الجلسة: فإذا كان signature_documents_source يساوي workflow، تحتاج الخطوة إلى مستندات مرفوعة في الكونسول، وتبقى الخطوة التي لا تحتوي على أي مستندات مسودةً، لكنها لا تستطيع أن تُفعَّل. أما مع session، فيجب أن يرسل كل طلب إنشاء الحقل sign.documents.
يجب أن يأتي FACE_MATCH بعد OCR في طلبات سير العمل البسيطة.
يتطلب NFC وDATABASE_VALIDATION وجود OCR عندما يظهران في سير العمل نفسه. ويحتاج AML إلى واحدة من OCR أو KYB_REGISTRY أو DOCUMENT_AI قبله. ومع وجود DOCUMENT_AI وحده قبله، يجب أن يكون full_name المراد فحصه قابلاً للتعبئة، إما من حقل Document AI سابق مُعرَّف بالمفتاح full_name، فيُربط تلقائياً، وإما من إدخال صريح في config.aml_field_sources (انظر AML).
تتطلب الميزات الفرعية لـ KYB مثل KYB_DOCUMENTS وKYB_KEY_PEOPLE وجود KYB_REGISTRY سابقاً في سير العمل.
سير العمل إما أن يكون سير عمل للأشخاص (KYC) أو سير عمل للشركات (KYB)، ولا يمكن أن يكون الاثنين معاً. يمكن لسير العمل الذي يستخدم أي ميزة KYB (KYB_REGISTRY أو KYB_DOCUMENTS أو KYB_KEY_PEOPLE) أن يجمعها فقط مع AML وDOCUMENT_AI وQUESTIONNAIRE وPHONE_VERIFICATION وEMAIL_VERIFICATION وIP_ANALYSIS وSIGNATURE. ولا يمكن أن يتضمن ميزات خاصة بالأشخاص مثل OCR وLIVENESS وFACE_MATCH وNFC وPROOF_OF_ADDRESS وDATABASE_VALIDATION أو AGE_ESTIMATION، ولا يمكن لسير عمل الأشخاص أن يتضمن ميزات KYB. وفي سير عمل الشركات، يقارن DOCUMENT_AI أي حقل مُعلَّم بـ is_full_name بالشركة المُتحقَّق منها بدلاً من مقارنته بشخص. للتحقق من الأشخاص الذين يقفون وراء شركة، أنشئ سير عمل KYC منفصلاً وأشر إليه من عقدة KYB_KEY_PEOPLE باستخدام kyb_ubo_verification_workflow أو kyb_officer_verification_workflow أو kyb_shareholder_verification_workflow.
تستخدم حقول الإجراء DECLINE أو REVIEW أو NO_ACTION ما لم يذكر الحقل أدناه أنه مقيّد.
حقول الدرجة والحد أرقام من 0 إلى 100 ما لم تُذكر نطاقات أضيق.

قواعد الحالة المشتركة

تدعم كل ميزة مصفوفة اختيارية باسم status_rules. استخدمها لتجاوز حالة الميزة عندما يتطابق شرط على حقل معيّن.

{
  "status_rules": [
    {
      "field": "kyc.issuing_state",
      "operator": "in",
      "value": ["VEN", "IRN"],
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.profession",
      "operator": "fuzzy_match",
      "value": "Soft. Engineer",
      "score": 80,
      "status": "Declined",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_to",
      "operator": "less_than",
      "value": "2030-01-01",
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_from",
      "operator": "less_than",
      "value": { "direction": "past", "amount": 3, "unit": "years" },
      "status": "Declined",
      "value_type": "relative_date"
    }
  ]
}

الحقل	النوع	الوصف
`field`	نص	مسار الحقل المراد فحصه، مثل `kyc.issuing_state` أو `kyc.document_type`.
`operator`	نص	إحدى القيم التالية: `equals`، `not_equals`، `greater_than`، `greater_than_or_equals`، `less_than`، `less_than_or_equals`، `contains`، `not_contains`، `in`، `not_in`، `is_empty`، `is_not_empty`، `regex`، أو `fuzzy_match`.
`value`	أي قيمة	قيمة المقارنة. احذفها أو أرسل `null` للعوامل التي لا تحتاج إلى قيمة.
`status`	نص	إحدى القيم التالية: `Approved`، أو `Declined`، أو `In Review`، أو `No Action`.
`value_type`	نص	اختياري. القيمة الافتراضية هي `literal`. استخدم `field` للمقارنة مع حقل آخر، أو `list` لتحويل معرّف UUID لقائمة Didit أثناء التشغيل، أو `relative_date` لمقارنة حقل تاريخ باليوم الحالي مضافًا إليه مدة أو مطروحًا منه مدة.
`score`	رقم	مطلوب مع `fuzzy_match`. الحد الأدنى لدرجة التشابه من `0` إلى `100`. تتطابق القاعدة عندما تكون درجة التشابه المحسوبة أكبر من هذه القيمة أو مساوية لها (`similarity >= score`). على سبيل المثال، يمكن أن تطابق `Software Engineer` القيمة `Soft. Engineer` عندما تكون درجة التشابه `80` على الأقل.

اقرأ المثال أعلاه على النحو التالي: kyc.extra_fields.profession يطابق بالتقريب Soft. Engineer بحد أدنى للدرجة 80 ← تعيين حالة الميزة إلى Declined. في ميزة التحقق من الهوية، استهدف قيم extra_fields المستخرجة مثل kyc.extra_fields.profession، أو تواريخ صلاحية فئة رخصة القيادة مثل kyc.extra_fields.dl_class_code_b_from وkyc.extra_fields.dl_class_code_b_to، أو رموز القيود أو المعلومات الخاصة بكل فئة مثل kyc.extra_fields.dl_class_code_b_notes (العمود 12 من رخص القيادة البريطانية). تأتي هذه القيم من كائن extra_fields في نتيجة OCR، وليست جزءًا من expected_details.

حقلا dl_class_code_*_from وdl_class_code_*_to يكونان دائمًا إما تاريخ ISO صالحًا أو غائبين من extra_fields. لا يُرجع Didit أبدًا نص OCR غير قابل للقراءة في حقل تاريخ. إذا تعذّر قراءة خلية جدول الفئات، يُحذف الحقل بدلًا من إرساله كنص خام. لذلك استخدم العامل is_empty لتوجيه تواريخ الفئات غير القابلة للقراءة، ولا تفترض أن الحقل موجود دائمًا.

بالنسبة إلى حقول التاريخ، استخدم value_type: "relative_date" مع كائن قيمة بالشكل { "direction": "past" | "future", "amount": number, "unit": "days" | "months" | "years" }. على سبيل المثال، يطابق operator: "less_than" مع { "direction": "past", "amount": 3, "unit": "years" } التواريخ الأقدم من ثلاث سنوات من اليوم.

المقارنة مع خطوة محددة

يمكن لسير عمل بياني أن يشغّل الميزة نفسها أكثر من مرة، مثلًا ثلاث خطوات من التحقق من الهوية. مع value_type: "field"، أضف @<node_id> إلى القيمة لقراءتها من خطوة معيّنة. يجب أن تكون العقدة المشار إليها خطوة ميزة تُنفَّذ دائمًا قبل خطوة القاعدة نفسها، في كل مسار يصل إليها، أو أن تكون خطوة القاعدة نفسها. القيمة التي لا تحتوي على اللاحقة تُقرأ من خطوة القاعدة نفسها.

{
  "status_rules": [
    {
      "field": "kyc.full_name",
      "operator": "fuzzy_match",
      "value": "kyc.full_name@ocr_1",
      "value_type": "field",
      "score": 80,
      "status": "Declined"
    }
  ]
}

اقرأ هذه القاعدة، المعيّنة على الخطوة الثالثة من التحقق من الهوية، على النحو التالي: kyc.full_name في هذه الخطوة يطابق بالتقريب الاسم الكامل الذي قرأته الخطوة ocr_1 بحد أدنى للدرجة 80 ← تعيين حالة الميزة إلى Declined. في الكونسول، تعرض أداة اختيار المتغيرات كل خطوة مؤهلة برقمها على لوحة التصميم، وتضيف اللاحقة نيابةً عنك.

OCR / التحقق من الهوية

قيمة الميزة: OCR.

حقل الإعداد	النوع	الوصف
`documents_allowed`	كائن	اختياري. احذفه، أو أرسل `null`، أو أرسل `{}` للسماح بكل الدول وأنواع المستندات المدعومة. أرسل رمز الدولة بتنسيق ISO3 مع إعداد نوع المستند فقط عندما تريد تقييد المستندات المسموح بها. يجب أن يكون مستند مخصص واحد على الأقل مفعّلًا بالقيمة `enabled: 1`. يمكن أن تتضمن إعدادات المستند `sides: 1` لالتقاط الوجه الأمامي فقط، أو `sides: 2` لالتقاط الوجهين. تشمل أنواع المستندات القيم `P` و`ID` و`DL` و`RP` و`HIC` و`TC` و`SSC`، وغيرها من القيم التي تدعمها الدولة.
`methods`	كائن	الطرق الثلاث للتحقق من الهوية التي يجوز لكل دولة استخدامها: التقاط المستند، والبحث غير القائم على المستندات لدى مصدر حكومي أو مصدر موثوق آخر، ومحافظ الهوية الرقمية. إذا حذفت المفتاح، أو الدولة، أو طريقة داخل الدولة، فإن تلك الدولة تقتصر على التقاط المستند فقط. يجب أن تكون كل طريقة ومحفظة متاحة للدولة في كتالوج القدرات، وإلا يُرفض الحفظ. راجع الطرق حسب الدولة أدناه.
`document_blur_fields_by_country`	كائن	رمز الدولة بتنسيق ISO3 إلى أسماء الحقول التي تُطمس على صور المستندات لإخفائها.
`image_capture_methods_allowed`	string[]	طرق الالتقاط المسموح بها. تشمل القيم `CAMERA_SCAN` و`UPLOAD`.
`duplicated_user_action`	إجراء	الإجراء الذي يُتخذ عند اكتشاف مستخدم مكرر.
`is_age_restrictions_enabled`	قيمة منطقية	يفعّل فحوصات الحد الأدنى والحد الأقصى للعمر.
`age_restrictions_by_country`	كائن	رمز الدولة بتنسيق ISO3 إلى إعداد عمر يتضمن `minimum_age`، و`maximum_age` اختياريًا، و`states` اختياريًا.
`minimum_age`	عدد صحيح	الحد الأدنى العام للعمر، من `1` إلى `120`.
`minimum_age_action`	إجراء	الإجراء الذي يُتخذ عندما يكون المستخدم أصغر من `minimum_age`.
`maximum_age`	عدد صحيح	الحد الأقصى العام للعمر، من `1` إلى `120`.
`maximum_age_action`	إجراء	الإجراء الذي يُتخذ عندما يكون المستخدم أكبر من `maximum_age`.
`expiration_date_not_detected_action`	إجراء	الإجراء الذي يُتخذ عندما يكون تاريخ انتهاء صلاحية المستند مفقودًا.
`invalid_code_action`	إجراء	الإجراء الذي يُتخذ عندما يكون الباركود أو الرمز القابل للقراءة آليًا غير صالح.
`invalid_mrz_action`	إجراء	الإجراء الذي يُتخذ عندما تكون منطقة القراءة الآلية MRZ غير صالحة.
`inconsistent_data_action`	إجراء	الإجراء الذي يُتخذ عندما تتعارض حقول المستند المستخرجة.
`invalid_validation_action`	إجراء	الإجراء الذي يُتخذ عندما يفشل التحقق من المستند.
`expected_details_mismatch_action`	إجراء	الإجراء الذي يُتخذ عندما لا تتطابق تفاصيل المستخدم المتوقعة مع المستند.
`image_too_blurry_action`	إجراء	الإجراء الخاص بصور المستندات الضبابية.
`image_too_dark_action`	إجراء	الإجراء الخاص بصور المستندات المعتمة.
`image_too_bright_action`	إجراء	الإجراء الخاص بصور المستندات مفرطة التعريض.
`unparsed_address_action`	إجراء	الإجراء الذي يُتخذ عندما يتعذر تحليل عنوان المستند.
`address_validation_enabled`	قيمة منطقية	يتحقق من العنوان الذي تقرؤه هذه الخطوة (المطبوع على وثيقة الهوية) مقابل البيانات المرجعية البريدية: يؤكد وجود العنوان ويوحّد صيغته، ولا يربطه أبدًا بشخص. تكون النتيجة كائن `address_validation` الخاص بالخطوة في القرار. تُحتسب تكلفته بمقدار $0.10 لكل عنوان يُتحقق منه؛ والتحقق الذي تعذّر تشغيله (`unavailable`) مجاني. مُعطّل افتراضيًا.
`address_not_verified_action`	إجراء	الإجراء الذي يُتخذ عندما لا يستطيع التحقق من العنوان تأكيد العنوان حتى مستوى المبنى (`ADDRESS_NOT_VERIFIED`: `partially_verified` أو `not_verified`). يُطبّق فقط عندما يكون `address_validation_enabled` مفعّلًا. القيمة الافتراضية هي `NO_ACTION`، وهي تسجّل التحذير فقط.
`document_or_personal_number_format_mismatch_action`	إجراء	الإجراء الذي يُتخذ عندما لا يتطابق تنسيق رقم المستند أو الرقم الشخصي مع النمط المتوقع.
`critical_field_occlusion_action`	إجراء	الإجراء الذي يُتخذ عندما يُبلغ فحص الحجب أن حقلًا مطبوعًا حرجًا، مثل رقم الهوية أو الاسم أو تاريخ الميلاد أو تاريخ الانتهاء، كان مغطى فعليًا على المستند الملتقط. يُعد تغطية رقم الهوية مؤشرًا على التلاعب وليس على جودة الالتقاط، لذلك تكون القيمة الافتراضية `REVIEW`. تُستبعد القيمة المقروءة للحقل المغطى من الاستخراج في كل الأحوال. ارفعها إلى `DECLINE` إذا كان يجب ألا يصل المستند المحجوب إلى المراجِع مطلقًا.
`document_without_portrait_action`	إجراء	الإجراء الذي يُتخذ عندما لا يحمل نوع المستند المعترف به صورة شخصية على أي وجه، وهذا ينطبق على بعض تصاريح الإقامة وبطاقات الصحة وشهادات التسجيل وغيرها من فئات المستندات التي لا تحمل صورة شخصية والمعروفة في الكتالوج. القيمة الافتراضية هي `REVIEW`. فكّر في `DECLINE` عندما تستند عملية التحقق من هوية سير العمل إلى مطابقة الوجه.
`is_document_selfie_portrait_match_enabled`	قيمة منطقية	يفعّل مقارنة الصورة الشخصية في المستند بصورة السيلفي.
`document_selfie_portrait_match_decline_threshold`	عدد صحيح	حد الرفض لمطابقة الصورة الشخصية في المستند مع صورة السيلفي.
`document_selfie_portrait_match_review_threshold`	عدد صحيح	حد المراجعة لمطابقة الصورة الشخصية في المستند مع صورة السيلفي.
`document_selfie_face_search_enabled`	قيمة منطقية	شغّل البحث بالوجه 1:N على صورة السيلفي المأخوذة أثناء التقاط المستند (يتطلب `is_document_selfie_portrait_match_enabled`): قارنها بقائمة الحظر للوجوه وبالمستخدمين الذين تم التحقق منهم سابقًا. تُقارن الصورة فقط، ولا يُخزَّن قالبها البيومتري أبدًا. مفعّل افتراضيًا. تؤدي القيمة `false` إلى تخطي البحث، فلا يبقى لإجراءات الوجه المكرر لصورة السيلفي الملتقطة أثناء التقاط المستند ما تتخذ بشأنه إجراءً. كما أن `face_search_enabled: false` في خطوة كشف الحيوية يتخطى البحث أيضًا، لأن هذا الإلغاء يشمل كل صورة سيلفي في الجلسة.
`document_selfie_duplicated_face_action`	إجراء	القرار عندما تطابق صورة السيلفي الملتقطة مع المستند، أو تحتمل أن تطابق، وجه مستخدم تم التحقق منه بالفعل في هذا التطبيق. القيمة الافتراضية هي `NO_ACTION`.
`document_selfie_duplicated_face_name_mismatch_action`	إجراء	القرار عندما تطابق صورة السيلفي الملتقطة مع المستند مستخدمًا تم التحقق منه سابقًا باسم مختلف. لا يمكن إلا أن يرفع مستوى `document_selfie_duplicated_face_action`. القيمة الافتراضية هي `REVIEW`.
`document_selfie_duplicated_face_document_mismatch_action`	إجراء	القرار عندما تطابق صورة السيلفي الملتقطة مع المستند مستخدمًا تم التحقق منه سابقًا بتاريخ ميلاد مختلف في وثيقة هويته. لا يُصنَّف الشخص نفسه على أنه حالة مطابقة إذا كان يحمل مستندًا مختلفًا أو مُجدَّدًا. لا يمكن إلا أن يرفع مستوى `document_selfie_duplicated_face_action`. القيمة الافتراضية هي `REVIEW`.
`id_verification_name_match_score_threshold`	عدد صحيح	حد تطابق الاسم عبر عدة عمليات التحقق من الهوية.
`id_verification_max_retry_attempts`	عدد صحيح	حد إعادة المحاولة للتحقق من الهوية، من `2` إلى `5`.
`id_document_quality_threshold`	عدد صحيح	الحد الأدنى لدرجة جودة الالتقاط (من `0` إلى `100`) الذي يجب أن تبلغه صورة المستند لقبولها. يُجرى فحص الجودة دائماً، وهذا الحد وحده قابل للضبط. القيمة الافتراضية `20`، وقد ضُبطت بحيث تُرفض اللقطات منخفضة الجودة والحالات الحدّية (الضبابية، والاهتزاز، والنص غير المقروء)، بينما تُقبل المستندات الواضحة. ارفع القيمة لاشتراطات التقاط أكثر صرامة. يعرض الكونسول هذه القيمة على شريط تمرير إدراكي، حيث تظهر القيمة الافتراضية `20` بنسبة متوازنة قدرها 50%.
`cross_org_fraud_document_action`	إجراء	الحكم عندما تُعلِّم مؤسسة أخرى في الشبكة هذا المستند على أنه احتيالي.
`document_audio_recording_enabled`	منطقي	تسجيل الميكروفون أثناء التقاط المستند، ليتمكن المراجِع من سماع الجلسة. مُعطّل افتراضياً.
`document_liveness_portrait_replace_decline_threshold`	عدد صحيح	درجة استبدال الصورة الشخصية (من `0` إلى `100`، وكلما ارتفعت الدرجة زادت احتمالية أن تكون أصلية) التي تُرفض الجلسة دونها. القيمة الافتراضية `35`. راجع حدود كشف حيوية المستند.
`document_liveness_portrait_replace_review_threshold`	عدد صحيح	درجة استبدال الصورة الشخصية التي تنتقل الجلسة دونها إلى قيد المراجعة، ما لم تكن مرفوضة بالفعل. عند `100` تُحال شبه كل الجلسات إلى المراجعة. القيمة الافتراضية `70`. راجع حدود كشف حيوية المستند.
`document_liveness_printed_copy_decline_threshold`	عدد صحيح	درجة النسخة المطبوعة (من `0` إلى `100`، وكلما ارتفعت الدرجة زادت احتمالية أن تكون أصلية) التي تُرفض الجلسة دونها. القيمة الافتراضية `35`. راجع حدود كشف حيوية المستند.
`document_liveness_printed_copy_review_threshold`	عدد صحيح	درجة النسخة المطبوعة التي تنتقل الجلسة دونها إلى قيد المراجعة، ما لم تكن مرفوضة بالفعل. عند `100` تُحال شبه كل الجلسات إلى المراجعة. القيمة الافتراضية `77`. راجع حدود كشف حيوية المستند.
`document_liveness_screen_replay_decline_threshold`	عدد صحيح	درجة التقاط الشاشة (من `0` إلى `100`، وكلما ارتفعت الدرجة زادت احتمالية أن تكون أصلية) التي تُرفض الجلسة دونها. القيمة الافتراضية `30`. راجع حدود كشف حيوية المستند.
`document_liveness_screen_replay_review_threshold`	عدد صحيح	درجة التقاط الشاشة التي تنتقل الجلسة دونها إلى قيد المراجعة، ما لم تكن مرفوضة بالفعل. عند `100` تُحال شبه كل الجلسات إلى المراجعة. القيمة الافتراضية `70`. راجع حدود كشف حيوية المستند.
`id_verification_injection_attack_action`	إجراء	الحكم عندما يكون المستند، أو صورة السيلفي المأخوذة للبحث بالهوية، قد حُقن بدلاً من أن يُلتقط بكاميرا الجهاز نفسه (`INJECTION_ATTACK_DETECTED`): كاميرا افتراضية برمجية، أو تغذية كاميرا تولّدها الصفحة أو أتمتة المتصفح، أو كاميرا مُعترضة، أو أداة قياس مرتبطة بالتطبيق. القيم: `DECLINE` و`REVIEW` و`NO_ACTION`. القيمة الافتراضية `DECLINE`. الإشارات التي يمكن أن ينتجها شخص حقيقي لا تُفعّله أبداً. أما في كشف الحيوية ومطابقة الوجه، فيتبع الخطر بدلاً من ذلك `frame_injection_action`.
`image_quality_too_low_action`	إجراء	الحكم عندما تكون جودة صورة المستند الإجمالية دون المعيار.
`is_image_capture_review_screen_enabled`	منطقي	عرض شاشة مراجعة للمستخدم بعد كل التقاط للمستند، تتيح له إعادة التقاط الصورة قبل إرسالها. مُعطّل افتراضياً.
`is_ocr_id_verification_data_review_enabled`	منطقي	السماح للمستخدم بمراجعة بيانات الهوية المستخرجة وتصحيحها قبل إكمال الخطوة. مُعطّل افتراضياً. يُحتسب التصحيح مقابل `ocr_id_verification_data_review_critical_fields`، ويُتخذ عند الاختلاف الإجراء الحرج أو الثانوي بحسب الحال. تعمل المراجعة حتى لو تضمّن سير العمل NFC، إذ تحل قراءة الشريحة اللاحقة محلها ببساطة.
`ocr_id_verification_data_review_critical_fields`	string[]	الحقول المستخرجة من بيانات الهوية التي تُعدّ حرجة عندما يعدّل المستخدم نتيجة OCR، فيؤدي عدم التطابق إلى اتخاذ الإجراء الحرج بدلاً من الإجراء الثانوي. الشكل: `["first_name" \| "last_name" \| "date_of_birth" \| ...]`.
`ocr_id_verification_data_review_critical_mismatch_action`	إجراء مقيّد	الحكم عندما يختلف تعديل المستخدم عن نتيجة OCR في حقل حرج.
`ocr_id_verification_data_review_minor_mismatch_action`	إجراء	الحكم عندما يختلف تعديل المستخدم عن نتيجة OCR في حقل غير حرج.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

يُضبط كشف حيوية المستند بالحدود الستة document_liveness_* أعلاه، لا بحقول إجراء لكل إشارة. الحقول portrait_replacement_action وprinted_copy_action وscreen_capture_action إعدادات على مستوى الحساب، ولا تُقبل في إعدادات ميزات سير العمل: تُزيل الواجهة البرمجية مفاتيح الإعدادات غير المعروفة عند الحفظ، لذا لا يكون لإرسالها أي أثر. لكل إشارة حد رفض وحد مراجعة على مقياس من 0-100، حيث تعني الدرجة الأعلى أن المستند أكثر احتمالاً أن يكون أصلياً.

مثال:

{
  "feature": "OCR",
  "config": {
    "documents_allowed": {
      "USA": {
        "DL": {
          "enabled": 1,
          "sides": 2
        }
      }
    },
    "duplicated_user_action": "REVIEW",
    "image_capture_methods_allowed": ["CAMERA_SCAN", "UPLOAD"]
  }
}

الطرق حسب الدولة

تُفهرس methods حسب رمز الدولة ISO 3166-1 alpha-3. تحمل كل دولة ما يصل إلى ثلاثة كائنات طرق، وأي طريقة تتركها دون تحديد تأخذ قيمتها الافتراضية.

{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "id_lookup": { "enabled": true, "on_no_match": "decline" }
      }
    }
  }
}

wallet.on_failure هو fallback_to_document أو decline أو retry. يُبقي retry (للمحفظة فقط، مع إيقاف التقاط المستند في الدولة) المستخدمَ الذي لم يُكمل تسجيل الدخول في خطوة المحفظة قادراً على المحاولة مرة أخرى. ولا تُرفض الجلسة بسبب ذلك، وتبقى مفتوحة حتى يُكمل المستخدم العملية أو تنتهي صلاحية الجلسة. تقبل مفاتيح id_lookup القيمتين fallback_to_document أو decline فقط. لإبقاء المستندات بعيدة عن الشاشة الأولى وعرضها فقط عندما لا تُفضي المحفظة أو عملية البحث إلى نتيجة، اضبط document.fallback_only. يستخدم المثال فنلندا، حيث تأتي Finnish Trust Network أولاً ويكون التقاط المستند هو البديل. تحتاج فنلندا أيضاً إلى تفعيل أنواع مستنداتها في documents_allowed (مثل جواز السفر وبطاقة الهوية)، حتى يكون لدى البديل مستندات يعرضها.

{
  "FIN": {
    "document": { "enabled": true, "fallback_only": true },
    "wallet": { "enabled": true, "providers": ["ftn"], "on_failure": "fallback_to_document" }
  }
}

عمليتا البحث المذكورتان أعلاه بحالة available في الكتالوج الحالي، لذا يُحفظ هذا الإعداد كما هو مكتوب. تم حذف كتلة المحفظة من هذا المثال عن قصد: لا تُحفظ المحفظة إلا في دولة يُعلّمها الكتالوج بحالة available، ويُرفض wallet.enabled: true في أي دولة أخرى فيُسقط معه الحفظ كاملاً، بما في ذلك إعدادات البحث. حيث يُعلّم الكتالوج المحفظة بحالة available، أضفها إلى تلك الدولة:

{
  "DNK": {
    "document": { "enabled": true },
    "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
  }
}

المفتاح	النوع	الافتراضي	الوصف
`<ISO3>.document.enabled`	boolean	`true`	هل يُقبل المستند المُلتقَط بالصورة في هذه الدولة. أما المستندات المقبولة فتبقى محددة في `documents_allowed`.
`<ISO3>.document.fallback_only`	boolean	`false`	إبقاء التقاط المستند مفعّلاً دون عرضه في الشاشة الأولى. يبدأ المستخدمون بتسجيل الدخول عبر المحفظة الرقمية للدولة أو بالاستعلام عن الهوية، ولا يُوجَّه إلى التقاط المستند إلا من فشل تسجيل دخوله عبر المحفظة أو أُلغي أو انتهت مهلته، أو لم يتطابق استعلامه (وفق مفاتيح `on_failure` و`on_partial_match` و`on_no_match` و`on_provider_error` المضبوطة على `fallback_to_document`). إذا وُجدت محفظة واحدة، يصل المستخدم إليها مباشرةً. وإن لم توجد، تُعرض المحفظة أو الاستعلام جنباً إلى جنب مع التقاط المستند. يُرفض بالرمز HTTP 400 ما لم تكن قيمة `document.enabled` هي `true` وتتضمن محفظة واحدة على الأقل أو استعلاماً واحداً على الأقل عن الهوية في الدولة يعود إلى التقاط المستند.
`<ISO3>.id_lookup.enabled`	boolean	`false`	عرض الاستعلام عن الهوية غير المعتمد على المستند، لدى الجهة الحكومية أو أي مصدر موثوق آخر في هذه الدولة. يُرفض إذا لم يُعلِّم الكتالوج مصدر الدولة بأنه `available`.
`<ISO3>.id_lookup.max_attempts`	integer	`1`	من `1` إلى `5`. عدد عمليات الاستعلام التي ردّ عليها السجل التي يحصل عليها المستخدم قبل تفعيل مفتاح الرجوع إلى المستند. الرقم الذي يفشل في فحص التنسيق على جانب العميل لا يصل إلى السجل، فلا يُحتسب ولا يُفوتَر.
`<ISO3>.id_lookup.skip_liveness_and_face_match`	boolean	`true`	بعد تطابق مع سجل يعيد صورة شخصية، يتخطى سير العمل خطوتي كشف الحيوية ومطابقة الوجه الخاصتين به، لأن الاستعلام قد أجرى بالفعل كشف الحيوية السلبي على الصورة الشخصية (السيلفي) وطابقها مع تلك الصورة. يُعاد ضبطه على `false` عند الحفظ لمصدر لا يعيد صورة شخصية، لأن المفتاح لن يكون له معنى حينها.
`<ISO3>.id_lookup.on_partial_match`	`fallback_to_document` \| `decline`	`fallback_to_document`	ما يحدث عندما يرد السجل لكن بعض الحقول لا تتطابق.
`<ISO3>.id_lookup.on_no_match`	`fallback_to_document` \| `decline`	`fallback_to_document`	ما يحدث عندما يرد السجل ولا يحتوي على أي سجل مطابق.
`<ISO3>.id_lookup.on_provider_error`	`fallback_to_document` \| `decline`	`fallback_to_document`	ما يحدث عندما لا يمكن الوصول إلى السجل. لا يُفوتَر هذا الاستعلام أبداً.
`<ISO3>.id_lookup.response_fields`	string[] \| null	`null`	مجموعة اختيارية من مفاتيح حقول الاستجابة الخاصة بالمصدر. تُرفض المفاتيح غير المعروفة، وتُضاف الحقول المطلوبة للمصدر دائماً مجدداً، لذا تكون القيمة المحفوظة اختياراً صالحاً دائماً. يطبّق التنفيذ الحالي في بيئة الاختبار هذا الاختيار على مخرجات المقارنة، والجنس عندما يكون اختيارياً، والصور الشخصية المحفوظة من السجل. تبقى حقول الهوية المطلوبة. انظر ملاحظة الإطلاق والاحتفاظ بالبيانات أدناه.
`<ISO3>.wallet.enabled`	boolean	`false`	عرض تسجيل الدخول عبر محفظة الهوية الرقمية في هذه الدولة.
`<ISO3>.wallet.providers`	string[]	`[]`	معرّفات المحافظ في الكتالوج التي تقبلها هذه الدولة، وهي قائمة قبول وليست ترتيباً. تُرتَّب القيم التي ترسلها وفق ترتيب الكتالوج. يلزم وجود محفظة واحدة على الأقل عندما تكون قيمة `enabled` هي `true`. تُرفض أي محفظة غير معروضة في الدولة، أو التي لا تزال قيد الإتاحة.
`<ISO3>.wallet.on_failure`	`fallback_to_document` \| `decline` \| `retry`	`fallback_to_document`	ما يحدث عندما يُلغى تسجيل الدخول أو تنتهي مهلته أو يفشل. تُبقي `retry` المستخدم في خطوة المحفظة ليحاول مجدداً (للمحفظة فقط)، ويُرفض استخدامها مع `document.fallback_only`.

التحقق الذي تطبّقه الواجهة البرمجية عند الحفظ:

يُرفض رمز الدولة غير المعروف، أو مفتاح غير معروف داخل دولة، أو مفتاح غير معروف داخل طريقة. لا يُتجاهل أي شيء بصمت.
تُرفض الدولة التي لا تكون فيها أي طريقة مفعّلة، لأن أحداً فيها لن يستطيع التحقق.
يمكن للمحفظة أو الاستعلام أن يعودا إلى التقاط المستند فقط عندما يكون التقاط المستند مفعّلاً في تلك الدولة. تؤدي fallback_to_document في دولة تكون فيها قيمة document.enabled هي false إلى الرفض وقت التشغيل، لأنه لا يوجد مسار للرجوع إليه.
يُرفض document.fallback_only: true بالرمز HTTP 400 ما لم تكن قيمة document.enabled هي true وتتضمن محفظة واحدة على الأقل أو استعلاماً واحداً على الأقل عن الهوية في تلك الدولة يعود إلى التقاط المستند.

يطبّق التنفيذ الحالي في بيئة الاختبار المفتاح id_lookup.response_fields على مخرجات المقارنة، والجنس عندما يكون اختيارياً، والصور الشخصية المحفوظة من السجل. وتبقى حقول الهوية المطلوبة جزءاً من سجل التحقق. هذا ليس ضماناً بأن كل حمولة وسيطة من المزوّد مستثناة من المعالجة. لم يُتحقق من الإطلاق الإنتاجي لهذا التغيير، فتأكد من السلوك في بيئتك المستهدفة قبل الاعتماد على اختيار الحقول لتلبية متطلبات الاحتفاظ بالبيانات.

اطّلع على كتالوج الإمكانات قبل كتابة methods، سواء عبر تبويب الدول في الكونسول أو باستخدام أداة MCP ‏didit_workflow_get_id_verification_methods_catalog. يرد السلوك والتغطية والفوترة في صفحة طرق التحقق من الهوية.

NFC / جواز السفر الإلكتروني

قيمة الميزة: NFC.

حقل الإعداد	النوع	الوصف
`allow_nfc_skip`	قيمة منطقية	يسمح للمستخدمين بتخطي NFC عندما يدعم مستندهم قراءة الشريحة.
`skip_nfc_action`	إجراء	الإجراء عندما يتخطى المستخدم قراءة NFC.
`unverified_chip_action`	إجراء	الإجراء عندما يفشل التحقق من الشريحة.
`trust_anchor_missing_action`	إجراء	الحكم عندما تكون تجزئات مجموعات بيانات الشريحة سليمة، لكن تعذّر التحقق من سلسلة الشهادات، لأن نقطة الثقة CSCA الخاصة بدولة الإصدار غير محمّلة.
`jpki_request_attributes`	قيمة منطقية	بطاقة My Number اليابانية (JPKI، لحزم SDK الأصلية فقط): اقرأ أيضًا شهادة التوقيع، وهي تتطلب رقم PIN الخاص بالتوقيع في البطاقة، وتتضمن اسم حامل البطاقة وتاريخ ميلاده وجنسه وعنوانه، وتُقارَن ببيانات التحقق من الهوية. القيمة الافتراضية `true`. القيمة `false` تقرأ شهادة مصادقة المستخدم فقط (رقم PIN مكوّن من 4 أرقام)، وهي تثبت البطاقة ورقم PIN، لكنها لا تتضمن أي بيانات عن حاملها.
`jpki_certificate_invalid_action`	إجراء	الحكم عندما لا ترتبط شهادة بطاقة My Number بسلسلة الثقة التابعة لهيئة التصديق الخاصة بـ JPKI، أو تكون خارج فترة صلاحيتها، أو لا تكون شهادة بطاقة من النوع المطلوب (`JPKI_CERTIFICATE_INVALID`). القيمة الافتراضية `DECLINE`.
`jpki_signature_invalid_action`	إجراء	الحكم عندما لا يتحقق توقيع بطاقة My Number على التحدي لمرة واحدة، فلا يثبت امتلاك البطاقة ومعرفة رقم PIN الخاص بها (`JPKI_SIGNATURE_INVALID`). القيمة الافتراضية `DECLINE`.
`jpki_certificate_revoked_action`	إجراء	الحكم عندما يُبلغ فحص الإلغاء بأن شهادة بطاقة My Number ملغاة (`JPKI_CERTIFICATE_REVOKED`). القيمة الافتراضية `DECLINE`.
`jpki_revocation_unchecked_action`	إجراء	الحكم عندما يُتحقق من بطاقة My Number، لكن لم تتوفر إجابة عن حالة الإلغاء، فلا يمكن استبعاد أن تكون البطاقة ملغاة (`JPKI_REVOCATION_UNCHECKED`). القيمة الافتراضية `REVIEW`.
`jpki_inconsistent_data_action`	إجراء	الحكم عندما يختلف الاسم أو تاريخ الميلاد أو الجنس أو العنوان في شهادة توقيع بطاقة My Number عن بيانات التحقق من الهوية للبطاقة نفسها (`JPKI_AND_OCR_DATA_NOT_SAME`). القيمة الافتراضية `REVIEW`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

كشف الحيوية

قيمة الميزة: LIVENESS.

حقل الإعداد	النوع	الوصف
`face_liveness_method`	نص	إحدى القيم `ACTIVE_3D` أو `FLASHING` أو `PASSIVE`.
`face_liveness_mode`	نص	تجاوز وضع كشف الحيوية.
`face_liveness_flash_mode`	نص	وضع الوميض للطريقتين `ACTIVE_3D` و`FLASHING`. تتحقق القيمة `"0"` (غير صارمة، وهي الافتراضية) من أن الألوان التي تومض على الشاشة تنعكس على وجه المستخدم، أما القيمة `"1"` (صارمة) فتشترط بالإضافة إلى ذلك أن تطابق الانعكاسات تسلسل الألوان الوامضة تمامًا. وهي أقوى في مواجهة هجمات إعادة التشغيل وحقن الفيديو، لكنها تؤدي إلى رفض خاطئ أكثر.
`face_liveness_score_decline_threshold`	عدد صحيح	حد الرفض.
`face_liveness_score_review_threshold`	عدد صحيح	حد المراجعة.
`face_liveness_possible_duplicated_face_action`	إجراء	الإجراء عندما يُحتمل أن يكون الوجه مكررًا.
`face_liveness_multiple_faces_action`	إجراء	الإجراء عند اكتشاف عدة وجوه.
`face_liveness_video_anomaly_action`	إجراء	الإجراء عندما تحتوي التسجيلات المخزنة على تسلسل متحرك متكرر. الافتراضي `NO_ACTION`، ويمكن لـ `REVIEW` و`DECLINE` تصعيد عملية تحقق تم البت فيها بشكل غير متزامن. الصور الثابتة المتفرقة أو المتكررة وحدها لا تُفعّل هذا الإجراء.
`face_liveness_attack_face_match_action`	إجراء	الإجراء عندما يطابق وجه كشف الحيوية وجهًا من جلسة سابقة لهذا التطبيق يخص مستخدمًا آخر، كان التقاطه قد صُنّف على أنه هجوم على كشف الحيوية بثقة عالية (التحذير `FACE_MATCHES_LIVENESS_ATTACK`). يقبل `NO_ACTION` أو `REVIEW`، و`DECLINE` مقبولة لكنها تُطبَّق كـ `REVIEW`، لأن المستخدم الحقيقي قد يُرفض مرة واحدة عن طريق الخطأ ثم ينجح لاحقًا. القيمة الافتراضية `NO_ACTION`.
`race_map_similarity_thresholds`	كائن	حدود التشابه لكل فئة ديموغرافية.
`face_privacy_mode_enabled`	قيمة منطقية	يفعّل وضع الخصوصية لأصول الوجه.
`face_quality_review_threshold`	عدد صحيح	حد المراجعة لجودة صورة الوجه.
`face_quality_decline_threshold`	عدد صحيح	حد الرفض لجودة صورة الوجه. يجب أن يكون أقل من حد المراجعة أو مساويًا له.
`face_luminance_min_threshold`	عدد صحيح	حد السطوع الأدنى. يجب أن يكون أقل من `face_luminance_max_threshold`.
`face_luminance_min_action`	إجراء	الإجراء عندما يكون السطوع منخفضًا جدًا.
`face_luminance_max_threshold`	عدد صحيح	حد السطوع الأقصى.
`face_luminance_max_action`	إجراء	الإجراء عندما يكون السطوع مرتفعًا جدًا.
`face_liveness_max_attempts`	عدد صحيح	إجمالي محاولات إرسال كشف الحيوية لكل جلسة، من `1` إلى `3`. القيمة الافتراضية `3` تعني محاولة أولية واحدة ومحاولتين إضافيتين. ضبط القيمة على `1` لا يُلغي إعادة المحاولة عند إخفاقات جودة الالتقاط: عندما تكون جميع التحذيرات في المحاولة بيئية (`LOW_FACE_LUMINANCE` و`HIGH_FACE_LUMINANCE` و`LOW_FACE_QUALITY` و`HIGH_FACE_OCCLUSION` و`NO_FACE_DETECTED`)، يحصل المستخدم دائمًا على محاولة ثانية مع ملاحظات قابلة للتنفيذ.
`cross_org_fraud_face_action`	إجراء	مهمل ولم يعد يُطبَّق. كان يعامل الوجه كما لو كان يحمل حكمًا بالاحتيال، وهو أمر لا يمكن أن تحمله الهوية البيومترية الثابتة. ما زال مقبولًا حتى تستمر عمليات سير العمل الحالية في اجتياز التحقق من صحتها. استخدم `cross_org_identity_claim_pattern_action`.
`cross_org_identity_claim_pattern_action`	إجراء	القرار عندما سجلت مؤسسات أخرى في الشبكة أحداث ادعاء هوية لهذا الشخص نفسه لم تتطابق فيها الهوية المدّعاة. المراجعة أو بدون إجراء فقط، وأي قرار رفض يُحدَّد هنا يُخفَّض إلى مراجعة. راجع الادعاءات بالهوية عبر المؤسسات.
`external_capture_device_action`	إجراء	القرار عند اكتشاف جهاز التقاط خارجي.
`face_audio_recording_enabled`	قيمة منطقية	تسجيل الميكروفون أثناء التقاط السيلفي، حتى يتمكن المراجِع من الاستماع إلى الجلسة. مُعطّل افتراضيًا.
`face_search_enabled`	قيمة منطقية	تشغيل البحث بالوجه 1:N التلقائي على صورة السيلفي: مطابقتها مع المستخدمين الذين جرى التحقق منهم سابقًا، وقائمة حظر الوجوه وقائمة السماح، وتخزين قالبها البيومتري للمطابقة لاحقًا. مفعّل افتراضيًا. القيمة `false` تتخطى البحث، ولا تحتفظ بقالب وجه لهذه الخطوة، وتترك إجراءات الوجه المكرر بلا أي شيء تعمل عليه.
`face_liveness_uncertain_retry_enabled`	قيمة منطقية	خاص بكشف الحيوية النشط في حزمة SDK الأصلية فقط. عند التفعيل، لا يُبَتّ أبدًا في أي التقاط تكون درجة كشف الحيوية فيه أكبر من `face_liveness_score_decline_threshold` وأقل من `face_liveness_score_review_threshold`، أيًا كان القرار الذي أرفقه المحرك به. يُبلَّغ الشخص بأن النتيجة كانت غير واضحة ويُطلب منه الالتقاط مجددًا، في كل مرة، خارج ميزانية `face_liveness_max_attempts` (التي ما زالت تنطبق على الالتقاطات التي لم يتمكن المحرك من تسجيل درجة لها). مُعطّل افتراضيًا، ومسار الويب يتجاهله.
`face_liveness_duplicated_face_name_mismatch_action`	إجراء	القرار عند العثور على وجه مكرر تحت اسم مختلف.
`face_liveness_duplicated_face_document_mismatch_action`	إجراء	القرار عند العثور على وجه مكرر، وكان تاريخ الميلاد في وثيقة هوية المستخدم المطابق يختلف. لا يُعلَّم الشخص نفسه على وثيقة مختلفة أو مجددة. القيمة الافتراضية `REVIEW`.
`frame_injection_action`	إجراء	القرار عند اكتشاف إطارات فيديو مُحقونة.
`screen_capture_action`	إجراء	القرار عندما تكون صورة السيلفي لصورة معروضة على شاشة.
`virtual_camera_action`	إجراء	القرار عند اكتشاف بث من كاميرا افتراضية.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

مطابقة الوجه

قيمة الميزة: FACE_MATCH.

حقل الإعداد	النوع	الوصف
`face_match_score_decline_threshold`	عدد صحيح	حد الرفض.
`face_match_score_review_threshold`	عدد صحيح	حد المراجعة.
`face_match_max_attempts`	عدد صحيح	إجمالي محاولات مطابقة الوجه لكل جلسة، من `1` إلى `3`. القيمة الافتراضية `3` تعني محاولة أولية واحدة ومحاولتي إعادة المحاولة.
`face_match_not_computed_action`	إجراء مقيّد	القرار عندما لا يمكن إنتاج درجة لمطابقة الوجه (صورة شخصية أو صورة سيلفي مفقودة).
`face_match_eyes_covered_action`	إجراء	القرار عندما تكون منطقة العينين مغطاة في صورة السيلفي. القيمة الافتراضية هي `NO_ACTION`، وتسجّل هذه القيمة الدليل دون تغيير نتيجة مطابقة الوجه. ما زالت هذه الإشارة قيد المعايرة، لذا تبقى في وضع الظل فقط إلى أن تُعلَن معايرة المنطقة: إذا عيّنت `REVIEW` أو `DECLINE` الآن، فسيسري ذلك من تلك النقطة فصاعداً.
`face_match_mouth_covered_action`	إجراء	القرار عندما تكون منطقة الفم مغطاة في صورة السيلفي. القيمة الافتراضية نفسها `NO_ACTION` والتحفّظ نفسه المتعلق بالمعايرة كما في `face_match_eyes_covered_action`.
`face_match_face_covered_action`	إجراء	القرار عندما يكون الوجه بأكمله مغطى في صورة السيلفي. القيمة الافتراضية نفسها `NO_ACTION` والتحفّظ نفسه المتعلق بالمعايرة كما في `face_match_eyes_covered_action`.
`status_rules`	مصفوفة	قواعد الحالة المخصصة الاختيارية.

تقدير العمر

قيمة الميزة: AGE_ESTIMATION.

حقل الإعداد	النوع	الوصف
`enable_id_verification_fallback`	منطقي	يُشغّل التحقق من الهوية عندما تقع نتيجة تقدير العمر ضمن نطاق الحالات الحدية.
`minimum_age_threshold`	عدد صحيح	الحد الأدنى للعمر المقبول، من `1` إلى `100`.
`borderline_minimum_age_threshold`	عدد صحيح	الحد الأدنى لنطاق الحالات الحدية، من `1` إلى `100`.
`borderline_maximum_age_threshold`	عدد صحيح	الحد الأعلى لنطاق الحالات الحدية، من `1` إلى `100`.
`face_liveness_method`	نص	إحدى القيم `ACTIVE_3D` أو `FLASHING` أو `PASSIVE`.
`face_liveness_flash_mode`	نص	وضع الوميض للطريقتين `ACTIVE_3D` و`FLASHING`. تتحقق القيمة `"0"` (غير صارمة، وهي الافتراضية) من أن الألوان المعروضة على الشاشة تنعكس على وجه المستخدم؛ أما القيمة `"1"` (صارمة) فتشترط إضافةً إلى ذلك أن تطابق الانعكاسات تسلسل الألوان المعروض بدقة.
`face_liveness_score_decline_threshold`	رقم	حد الرفض لفحص الحيوية المستخدم في تقدير العمر.
`face_liveness_score_review_threshold`	رقم	حد المراجعة لفحص الحيوية المستخدم في تقدير العمر.
`face_liveness_possible_duplicated_face_action`	إجراء	الإجراء عندما يُحتمل أن يكون الوجه مكرراً.
`face_liveness_multiple_faces_action`	إجراء	الإجراء عند اكتشاف أكثر من وجه.
`face_liveness_video_anomaly_action`	إجراء	الإجراء عندما تحتوي التسجيلة المحفوظة على تسلسل متحرك متكرر. القيمة الافتراضية `NO_ACTION`، ويمكن أن تؤدي `REVIEW` و`DECLINE` إلى تصعيد التحقق الذي اتُّخذ قرار بشأنه بشكل غير متزامن. الإطارات الثابتة المتفرقة أو المتكررة وحدها لا تُفعّل هذا الإجراء.
`face_liveness_attack_face_match_action`	إجراء	الإجراء عندما يطابق الوجه في فحص الحيوية وجهاً من جلسة سابقة في هذا التطبيق لمستخدم آخر كان التقاطه قد صُنّف هجوم حيوية بثقة عالية (التحذير `FACE_MATCHES_LIVENESS_ATTACK`). تقبل القيمتين `NO_ACTION` أو `REVIEW`؛ القيمة `DECLINE` مقبولة لكنها تُطبَّق كـ`REVIEW`، لأن المستخدم الحقيقي قد يُرفض مرة بالخطأ ثم ينجح لاحقاً. القيمة الافتراضية `NO_ACTION`.
`face_privacy_mode_enabled`	منطقي	يفعّل وضع الخصوصية لأصول الوجه.
`face_quality_review_threshold`	عدد صحيح	حد المراجعة لجودة الوجه.
`face_quality_decline_threshold`	عدد صحيح	حد الرفض لجودة الوجه.
`face_luminance_min_threshold`	عدد صحيح	حد الإضاءة الأدنى.
`face_luminance_min_action`	إجراء	الإجراء عندما تكون الإضاءة منخفضة جداً.
`face_luminance_max_threshold`	عدد صحيح	حد الإضاءة الأعلى.
`face_luminance_max_action`	إجراء	الإجراء عندما تكون الإضاءة مرتفعة جداً.
`face_liveness_max_attempts`	عدد صحيح	إجمالي محاولات إرسال فحص الحيوية لكل جلسة، من `1` إلى `3`. القيمة الافتراضية `3` تعني محاولة أولى ومحاولتين إضافيتين. ضبط القيمة على `1` لا يعطّل إعادة المحاولة عند فشل جودة الالتقاط: إذا كانت جميع التحذيرات في المحاولة بيئية (`LOW_FACE_LUMINANCE` و`HIGH_FACE_LUMINANCE` و`LOW_FACE_QUALITY` و`HIGH_FACE_OCCLUSION` و`NO_FACE_DETECTED`)، يحصل المستخدم دائماً على محاولة ثانية مع ملاحظات قابلة للتنفيذ.
`external_capture_device_action`	إجراء	القرار عند اكتشاف جهاز التقاط خارجي.
`face_audio_recording_enabled`	منطقي	تسجيل الميكروفون أثناء التقاط صورة السيلفي، ليتمكن المراجِع من الاستماع إلى الجلسة. مُعطّل افتراضياً.
`face_search_enabled`	منطقي	تشغيل البحث بالوجه 1:N التلقائي على صورة السيلفي: مطابقتها مع المستخدمين الذين تم التحقق منهم سابقاً، وقائمتي حظر الوجوه والسماح بها، وتخزين قالبها البيومتري للمطابقة لاحقاً. مُفعّل افتراضياً. القيمة `false` تتخطى البحث، ولا تحتفظ بقالب وجه لهذه الخطوة، وتترك إجراءات الوجه المكرر دون أي شيء تتصرف بناءً عليه.
`face_liveness_uncertain_retry_enabled`	منطقي	خاص بفحص الحيوية النشط عبر SDK الأصلي فقط. عند التفعيل، لا يُتخذ أي قرار بشأن أي التقاط تقع درجة الحيوية فيه بين القيمتين `face_liveness_score_decline_threshold` و`face_liveness_score_review_threshold` (دون أن تساويهما)، بغض النظر عن القرار الذي أرفقه المحرك به: يُبلَّغ الشخص بأن النتيجة كانت غير واضحة ويُطلب منه الالتقاط مجدداً، في كل مرة، خارج ميزانية `face_liveness_max_attempts` (التي تبقى سارية على الالتقاطات التي لم يتمكن المحرك من احتساب درجة لها). مُعطّل افتراضياً؛ مسار الويب يتجاهله.
`face_liveness_duplicated_face_name_mismatch_action`	إجراء	القرار عند العثور على وجه مكرر تحت اسم مختلف.
`face_liveness_duplicated_face_document_mismatch_action`	إجراء	القرار عند العثور على وجه مكرر وكان مستند الهوية للمستخدم المطابق يُظهر تاريخ ميلاد مختلفاً. لا يُوضَع على الشخص نفسه تنبيه عند ظهوره على مستند مختلف أو مُجدَّد. القيمة الافتراضية `REVIEW`.
`frame_injection_action`	إجراء	القرار عند اكتشاف حقن إطارات فيديو.
`screen_capture_action`	إجراء	القرار عندما تكون صورة السيلفي صورة لشاشة.
`virtual_camera_action`	إجراء	القرار عند اكتشاف بث من كاميرا افتراضية.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

التحقق من رقم الهاتف

قيمة الميزة: PHONE_VERIFICATION.

حقل الإعداد	النوع	الوصف
`code_size`	عدد صحيح	حجم رمز OTP، من `4` إلى `8`.
`phone_max_retries`	عدد صحيح	الحد الأقصى لمحاولات إعادة إرسال الرمز، من `1` إلى `5`.
`phone_max_check_attempts`	عدد صحيح	الحد الأقصى لمحاولات التحقق من رمز OTP، من `1` إلى `5`.
`phone_verification_countries`	كائن	رمز الدولة ISO2 مع إعدادات القناة. مثال: `{ "US": { "sms": { "enabled": true } } }`.
`disposable_number_action`	إجراء	الإجراء المتخذ مع أرقام الهاتف المؤقتة.
`voip_number_action`	إجراء	الإجراء المتخذ مع أرقام VoIP.
`duplicated_phone_number_action`	إجراء	الإجراء المتخذ مع أرقام الهاتف المكررة.
`high_risk_phone_action`	إجراء	الإجراء عندما يحظر مزوّد خدمة الإرسال إرسال رمز OTP. القيمتان المسموحتان فقط `DECLINE` أو `REVIEW`، والافتراضي `DECLINE`. يُطبَّق فقط عندما تحمل كل عمليات الحظر في الخطوة `risk_factors` بالقيمة `["device_attribute"]` تحديداً. أي عامل مخاطر آخر، أو أي مزيج يتضمنه، أو عدم وجود أي عوامل مخاطر، يؤدي إلى الرفض بغض النظر عن هذا الإعداد.
`phone_shared_device_mode`	قيمة منطقية	يسمح بوضع التحقق من الهاتف على الجهاز المشترك.
`phone_enrichment_enabled`	قيمة منطقية	يفعّل إثراء استخبارات الهاتف (مخاطر نوع الخط، ومؤشر الثقة، ومشغّل الشبكة، وسجل نقل الرقم أو استبدال شريحة SIM، ودرجة مخاطر الاحتيال). تُحتسب رسوم قدرها $0.05 لكل عملية تحقق إضافةً إلى سعر التحقق من الهاتف.
`phone_intelligence_score_action`	إجراء	الإجراء عندما تكون درجة مخاطر الاحتيال للهاتف أكبر من أو تساوي `phone_intelligence_score_threshold`.
`phone_intelligence_score_threshold`	عدد صحيح	درجة مخاطر الاحتيال (`0`–`100`، وكلما ارتفعت كانت المخاطر أعلى) التي تُفعّل `phone_intelligence_score_action`. الافتراضي `80`.
`phone_type_risk_action`	إجراء	الإجراء عندما يُوسم الرقم بأنه من نوع هاتف عالي المخاطر.
`recent_port_action`	إجراء	الإجراء عندما نُقل الرقم مؤخراً (إشارة نقل الرقم أو استبدال شريحة SIM).
`low_phone_trust_action`	إجراء	الإجراء عندما يكون مؤشر ثقة الهاتف أقل من أو يساوي `phone_trust_index_threshold`.
`phone_trust_index_threshold`	عدد صحيح	مؤشر الثقة (`0`–`100`، وكلما انخفض كانت المخاطر أعلى) الذي يُطبَّق عنده `low_phone_trust_action` عندما يكون أقل من هذه القيمة أو مساوياً لها. الافتراضي `30`.
`phone_social_enabled`	قيمة منطقية	يفعّل فحص البصمة الاجتماعية، أي المنصات التي يكون الرقم المتحقَّق منه مسجلاً فيها، ومنها منصات المراسلة والتواصل الاجتماعي والتجارة الإلكترونية والمنصات المهنية. تُحتسب رسوم قدرها $0.05 لكل عملية تحقق إضافةً إلى سعر التحقق من الهاتف، بشكل مستقل عن `phone_enrichment_enabled`.
`phone_no_social_presence_action`	إجراء	الإجراء عندما لا يُعثر على الرقم مسجلاً في أي منصة من المنصات التي يغطيها الفحص الاجتماعي، وهي إشارة شائعة إلى الهوية الاصطناعية. الافتراضي `NO_ACTION`.
`cross_org_fraud_phone_action`	إجراء	الحكم عندما وُسم هذا الرقم بأنه احتيالي من مؤسسة أخرى في الشبكة.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

التحقق من الهاتف معطّل إلى أن تُكمل المؤسسة أول عملية شحن للرصيد.

إثراء استخبارات الهاتف إضافة اختيارية. عندما تكون قيمة phone_enrichment_enabled هي true، يُثرى كل تحقق مكتمل من الهاتف باستخبارات الهاتف، ويُحتسب $0.05 عن كل طلب بالإضافة إلى تكلفة التحقق من الهاتف المعتادة. لا تُطبَّق الإجراءات القائمة على الدرجة إلا بعد توفر درجة الإثراء، أما إجراءات مؤشر الثقة ونوع الهاتف والنقل فتُطبَّق بمجرد تشغيل الإثراء.فحص البصمة الاجتماعية إضافة ثانية ومنفصلة. عندما تكون قيمة phone_social_enabled هي true، يُبلغ كل تحقق مكتمل من الهاتف أيضاً عن المنصات الإلكترونية المسجل فيها الرقم، أي منصات المراسلة ووسائل التواصل الاجتماعي والتجارة الإلكترونية والخدمات المهنية، ويُحتسب $0.05 عن كل طلب. يمكن تفعيلها مع phone_enrichment_enabled أو من دونها، فالإضافتان مسعّرتان ومحتسبتان بشكل مستقل. يُعدّ الاستعلام الذي لا يجد الرقم في أي من المنصات التي يغطيها إجابةً صالحة وقابلة للفوترة، ويُفعّل phone_no_social_presence_action. استخدم phone.social_profiles_registered (عدد المنصات المسجل فيها الرقم) للتفريع حسب النتيجة في مخطط سير العمل.

التحقق من البريد الإلكتروني

قيمة الميزة: EMAIL_VERIFICATION.

حقل الإعداد	النوع	الوصف
`email_code_size`	عدد صحيح	حجم رمز OTP، من `4` إلى `8`.
`email_max_retries`	عدد صحيح	الحد الأقصى لمحاولات إعادة الإرسال، من `1` إلى `5`.
`email_max_check_attempts`	عدد صحيح	الحد الأقصى لمحاولات التحقق من رمز OTP، من `1` إلى `5`.
`email_alphanumeric_code`	قيمة منطقية	يستخدم رموز بريد إلكتروني أبجدية رقمية.
`breached_email_action`	إجراء	الإجراء الذي يُتخذ مع عناوين البريد الإلكتروني المُخترَقة.
`disposable_email_action`	إجراء	الإجراء الذي يُتخذ مع عناوين البريد الإلكتروني المؤقتة.
`duplicated_email_action`	إجراء	الإجراء الذي يُتخذ مع عناوين البريد الإلكتروني المكررة.
`only_corporate_emails_allowed`	قيمة منطقية	يرفض عناوين البريد الإلكتروني غير المؤسسية.
`email_enrichment_enabled`	قيمة منطقية	يفعّل إثراء ذكاء البريد الإلكتروني (قابلية التسليم، وسمعة النطاق، والتعرض لاختراقات البيانات، ودرجة مخاطر الاحتيال). تُحتسب $0.05 عن كل عملية تحقق إضافةً إلى سعر التحقق من البريد الإلكتروني.
`email_intelligence_score_action`	إجراء	الإجراء الذي يُتخذ عندما تكون درجة مخاطر الاحتيال للبريد الإلكتروني أكبر من أو تساوي `email_intelligence_score_threshold`.
`email_intelligence_score_threshold`	عدد صحيح	درجة مخاطر الاحتيال (`0`–`100`، وكلما ارتفعت الدرجة ازدادت المخاطر) التي تُفعّل `email_intelligence_score_action`. القيمة الافتراضية `80`.
`recent_email_breach_action`	إجراء	الإجراء الذي يُتخذ عندما يظهر البريد الإلكتروني في اختراق بيانات معروف وحديث.
`frequent_email_breach_action`	إجراء	الإجراء الذي يُتخذ عندما يظهر البريد الإلكتروني في عدد كبير من اختراقات البيانات المعروفة.
`email_social_enabled`	قيمة منطقية	يفعّل فحص البصمة الاجتماعية، وهو تحديد المنصات التي يُسجَّل فيها العنوان الموثَّق، ومنها منصات البريد الإلكتروني والتواصل الاجتماعي والمهنية والتجارة الإلكترونية والترفيه. تُحتسب $0.05 عن كل عملية تحقق إضافةً إلى سعر التحقق من البريد الإلكتروني، ومستقلةً عن `email_enrichment_enabled`.
`email_no_social_presence_action`	إجراء	الإجراء الذي يُتخذ عندما لا يُسجَّل العنوان في أي من المنصات التي يغطيها فحص البصمة الاجتماعية، وهي إشارة شائعة إلى هوية اصطناعية. القيمة الافتراضية `NO_ACTION`.
`cross_org_fraud_email_action`	إجراء	الحكم الذي يصدر عندما تُبلغ مؤسسة أخرى في الشبكة بأن هذا العنوان احتيالي.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

إثراء ذكاء البريد الإلكتروني إضافة اختيارية. عندما تكون قيمة email_enrichment_enabled هي true، تُثرى كل عملية تحقق مكتملة من البريد الإلكتروني بذكاء البريد الإلكتروني، وتُحتسب $0.05 عن كل طلب إضافةً إلى التكلفة القياسية للتحقق من البريد الإلكتروني. يسري الإجراء المعتمد على الدرجة بمجرد توفر درجة الإثراء، وتسري إجراءات الاختراق بمجرد تشغيل الإثراء.فحص البصمة الاجتماعية إضافة ثانية ومستقلة. عندما تكون قيمة email_social_enabled هي true، تُبلغ كل عملية تحقق من البريد الإلكتروني تكتمل أيضًا عن المنصات الإلكترونية التي يُسجَّل فيها العنوان، ومنها مزودو البريد الإلكتروني ووسائل التواصل الاجتماعي والخدمات المهنية والتجارة الإلكترونية والترفيه، وتُحتسب $0.05 عن كل طلب. يمكن تفعيله مع email_enrichment_enabled أو دونه، لأن الإضافتين مسعّرتان ومفوترتان بشكل مستقل. يُعدّ البحث الذي لا يجد العنوان في أي من المنصات التي يغطيها إجابةً صالحةً وقابلةً للفوترة، ويُفعّل email_no_social_presence_action. استخدم email.social_profiles_registered (عدد المنصات المسجَّل فيها العنوان) للتفريع حسب النتيجة في مخطط سير العمل.

التحقق من قواعد البيانات

قيمة الميزة: DATABASE_VALIDATION.

حقل الإعداد	النوع	الوصف
`database_validation_countries`	كائن	رمز الدولة ISO3 يُربط بـ `{ "services": ["service_id"] }`. استخدم معرّفات الخدمات من كتالوج التحقق من قواعد البيانات.
`database_validation_partial_match_action`	إجراء	الإجراء الذي يُنفَّذ عندما يعيد التحقق من قواعد البيانات تطابقاً جزئياً.
`database_validation_no_match_action`	إجراء	الإجراء الذي يُنفَّذ عندما يعيد التحقق من قواعد البيانات عدم وجود أي تطابق.
`database_validation_not_applicable_action`	إجراء	الإجراء الذي يُنفَّذ عندما لا يمكن تشغيل التحقق من قواعد البيانات لأن المستند لا يحمل المعرّف الذي تتطلبه الخدمات المُعدّة (مثلاً جواز سفر لا يحتوي على رقم الهوية الوطنية). القيمة الافتراضية هي `NO_ACTION`.
`database_validation_field_sources`	كائن	المكان الذي تُقرأ منه مدخلات قاعدة البيانات التي لا تستطيع أي خطوة سابقة في المخطط تعبئتها. يحدد `source` الجهة المُنتجة، ويحدد `key` القيمة داخلها: مفتاح حقل Document AI لـ `document_ai`، ومعرّف عقدة الاستبيان لـ `questionnaire`، و`expected_details.<field>` أو `metadata.<key>` لـ `expected_data`. يُحَلّ التطابق التام للمفتاح مع خطوة سابقة تلقائياً، ولا يُحفظ عمداً، بحيث لا يؤدي تغيير اسم حقل Document AI إلى تثبيت ربط قديم في الإعداد. يُرفض الإدخال غير الصالح برمز `400` يذكر حقل المدخل المعني. الصيغة: `{"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

مثال:

{
  "feature": "DATABASE_VALIDATION",
  "config": {
    "database_validation_countries": {
      "BRA": {
        "services": ["SERVICE_ID_FROM_CATALOG"]
      }
    },
    "database_validation_field_sources": {
      "tax_id": {
        "source": "expected_data",
        "key": "expected_details.document_number"
      }
    },
    "database_validation_no_match_action": "REVIEW",
    "database_validation_partial_match_action": "REVIEW"
  }
}

database_validation_countries هو ما يجعل هذه الخطوة تُنفّذ أي فحص. تُقبل ميزة DATABASE_VALIDATION المحفوظة من دونه، ثم لا تُنفّذ أي فحص على الإطلاق، لذا أرسل دائماً دولة واحدة على الأقل مع معرّف خدمة واحد على الأقل.

يُرفض معرّف الخدمة الذي لا تستطيع الخطوة تشغيله برمز 400 يذكره ويوضح السبب، ولا يُحفظ شيء. ويشمل ذلك معرّفاً غير موجود في الكتالوج، ومعرّفاً يتبع دولة أخرى، وخدمةً غير متاحة بعد، وخدمةً تُقدَّم فقط عبر endpoint المستقلة POST /v3/database-validation/. تُرفض بالطريقة نفسها الخدمة التي لا توفّر أي خطوة سابقة مدخلاتها، مع سرد المدخلات الناقصة. تُحذف الخدمة التي يحملها سير العمل المحفوظ ولم تعد قابلة للتشغيل عند حفظه مرة أخرى. على سبيل المثال، يقرأ سير العمل الأرجنتيني رقم DNI والجنس من التحقق من الهوية، ويطابقهما مع RENAPER من دون صورة سيلفي:

{
  "workflow_label": "Argentina DNI check",
  "features": [
    {"feature": "OCR"},
    {
      "feature": "DATABASE_VALIDATION",
      "config": {"database_validation_countries": {"ARG": {"services": ["arg_renaper_data"]}}}
    }
  ]
}

استخدم arg_renaper بدلاً من ذلك، بعد خطوة LIVENESS، لمطابقة صورة السيلفي أيضاً مع الصورة التي يحتفظ بها RENAPER. راجع RENAPER لمعرفة درجة مطابقة الوجه والحد المعتمد لها.

التحقق من الحساب البنكي

قيمة الميزة: BANK_VERIFICATION. يتحقق المستخدم من حساب بنكي، ثم تُقارَن هوية صاحب الحساب التي يبلّغ عنها البنك بالهوية التي أثبتتها خطوة سابقة في سير العمل. يتم ذلك بإحدى طريقتين: تسجيل الدخول إلى البنك (open_banking)، حيث يسجّل المستخدم الدخول لدى بنكه، أو فحص الحساب (account_lookup)، حيث يكتب المستخدم بيانات حسابه ويؤكد البنك الاسم المرتبط به. يحدد bank_method_order وmethods في كل دولة الطرق التي تقدمها الدولة وأيّها يأتي أولاً؛ راجع طرق التحقق من الحساب البنكي. تُنتج الخطوة أدلة، وهي درجة تطابق اسم صاحب الحساب والمقارنة التي أنتجتها ورموز الأسباب، ثم تحوّل مفاتيح bank_*_action هذه الأدلة إلى حالة. يحدد أمران ما إذا كانت العقدة تعمل أصلاً. bank_countries قائمة بيضاء، فالخريطة الفارغة لا تعرض أي بنك ولا تُجري أي فحص. ويحتاج صاحب الحساب إلى ما يُقارَن به: أضف قبل العقدة خطوة OCR أو DATABASE_VALIDATION أو QUESTIONNAIRE، أو أرسل expected_details عند إنشاء الجلسة، أو اربط الحقول بنفسك عبر bank_field_sources. وبدون أيّ من ذلك لا يمكن أن تكون الملكية إلا unknown، وهذا ما يحدد bank_reference_identity_missing_action كيفية التعامل معه.

ما زال التحقق من الحساب البنكي قيد الإطلاق، لذا لا تُقبل عقدة BANK_VERIFICATION إلا في حساب فعّلت فيه هذه الميزة. وفي غير ذلك يُرفض الحفظ ويوضح ذلك. والمسار الذي تُنفَّذ به الخطوة لا يُضبط هنا أيضاً: فهو زوج provider_key وfallback_to_native الذي تضبطه لك Marketplace في وحدة التحكم.

ربط الحساب

حقل الإعداد	النوع	الوصف
`bank_countries`	object	الدول التي يجوز للمستخدم ربط حساب بنكي فيها. قائمة بيضاء: الخريطة الفارغة تعني أن العقدة لا تعرض شيئاً ولا تُنفّذ أي فحص. يضيّق `institutions` منتقي البنوك إلى معرّفات مؤسسات محددة، بينما يعرض `"all"` كل بنك في الدولة يدعم التحقق من الهوية. تُحفظ الدولة التي لا يخدمها أي مسار من مسارات العقدة: إذ تعرض بدائلها فقط وخيار المتابعة بدون بنكك، راجع عندما لا يتمكن الشخص من التحقق من حسابه البنكي. يُرفض عند الحفظ أي رمز لا يسمّي دولة. يحدد `methods` الطرق التي تعرضها الدولة من تسجيل الدخول إلى البنك (`open_banking`) وفحص الحساب (`account_lookup`) وترتيبها، ويتجاوز `bank_method_order`: يبدأ المستخدم بالطريقة الأولى وتُعرض عليه الثانية كبديل احتياطي. يُرفض عند الحفظ أي بلد مفعّل يذكر في `methods` طريقة لا يخدمها أي مسار من مسارات العقدة في تلك الدولة، وكذلك أي بلد يخدمه مسار ويترك `methods` بلا أي طريقة. الشكل: `{"<ISO3>": {"enabled": true\|false, "institutions": ["<institution_id>", ...]\|"all", "methods"?: ["open_banking"\|"account_lookup", ...]}}`.
`bank_method_order`	string[]	أيّ الطريقتين تعرضهما الخطوة وترتيبهما، في كل دولة لا تحدد لنفسها `methods`: `open_banking` (تسجيل الدخول إلى البنك: يسجّل المستخدم الدخول لدى بنكه، وهذه الطريقة وحدها تقرأ الأرصدة والمعاملات والدخل) و`account_lookup` (فحص الحساب: دون تسجيل دخول، ويقتصر على الملكية). في كل دولة يبدأ المستخدم بأول طريقة يخدمها مسار هناك، وتُعرض عليه الأخرى كبديل احتياطي؛ والطريقة التي لا يخدمها أي مسار في دولة تُستبعد هناك. مطلوب طريقة واحدة على الأقل. الحفظ الذي لا يرسل أيّ طريقة يحصل على `["open_banking", "account_lookup"]`، إلا إذا أرسل `bank_open_banking_enabled` أو `bank_account_lookup_enabled`، فتحددانها.
`bank_scopes`	object	ما يُطلب من المستخدم الموافقة على مشاركته. `ownership` هو ما يتحقق منه المنتج ولا يمكن إيقافه. يكشف `identifiers` رقم IBAN أو رقم الحساب كاملاً؛ أما `balances` و`transactions` و`income` فتقرأ بيانات مالية فعلية، ويُحتسب كل منها بشكل منفصل، ويُرفض عند الحفظ ما لم يكن تطبيقك يملك صلاحية البيانات المالية. تقرأ البيانات طريقة تسجيل الدخول إلى البنك وحدها: فلا تُرفض الدولة التي تعرض فحص الحساب، ويمر المستخدم الذي تحقق بفحص الحساب دون هذه البيانات، وتسردها النتيجة في `financial_data.not_collected`. لا يُطلب أي نطاق معطّل أبداً، فلا يعرضه البنك على شاشة موافقته. القيمة الافتراضية `ownership` وحده. الشكل: `{"ownership": true, "identifiers": true\|false, "balances": true\|false, "transactions": true\|false, "income": true\|false}`.
`bank_eligible_account_types`	string[]	أنواع الحسابات التي يجوز للمستخدم اختيارها: `checking` و`current` و`savings` و`business` و`other`. لا تُقبل بطاقات الائتمان والقروض وحسابات الاستثمار أبداً، لأنها لا تثبت ملكية حساب دفع. القيمة الافتراضية هي الحساب الجاري وحساب الشيكات.
`bank_account_selection`	string	`user` يتيح للمستخدم اختيار الحساب الذي يُتحقَّق منه من بين الحسابات المرتبطة؛ و`auto` يأخذ أول حساب مؤهل.
`bank_require_oauth_only`	boolean	يعرض فقط المؤسسات التي يمكن الوصول إليها عبر OAuth أو من تطبيق إلى تطبيق، ولا يعرض أبداً شاشة قديمة لالتقاط بيانات الاعتماد. وفي الأسواق التي تجعل الصيرفة المفتوحة OAuth المسار الوحيد، لا يغيّر هذا الإعداد شيئاً.
`bank_max_attempts`	integer	عدد محاولات تسجيل الدخول إلى البنك التي يحصل عليها المستخدم، من `1` إلى `5`؛ ويستهلك الإيداع الصغير أو رفع كشف الحساب محاولة أيضاً. لفحص الحساب إعداده الخاص `bank_account_check_max_attempts`. وبعد أن تكون كل طرق التحقق من المستخدم، بما فيها رفع كشف الحساب، قد استنفدت محاولاتها دون ربط ناجح، يحدد `bank_attempts_exhausted_action` ما يحدث.
`bank_connection_timeout_minutes`	integer	المدة التي يبقى فيها الاتصال الذي بدأه المستخدم مفتوحاً قبل ترك المحاولة، من `5` إلى `60` دقيقة.
`bank_allow_skip`	boolean	أُلغي واستُعيض عنه بـ `bank_continue_without_bank`: يستطيع المستخدم الآن دائماً المتابعة دون بنك. يُقرأ لإصدار واحد من عملية حفظ لا ترسل `bank_continue_without_bank`: فالقيمة `true` تضبط `from_start` وأي قيمة أخرى تضبط `when_needed`. ويكتب كل حفظ القيمة من جديد: `true` لـ `from_start` و`false` لـ `when_needed`.

عندما لا يستطيع المستخدم التحقق

يستطيع المستخدم دائماً المتابعة دون بنك، ولا تترك الخطوة المستخدم عالقاً أبداً. راجع عندما لا يتمكن الشخص من التحقق من حسابه البنكي.

حقل الإعداد	النوع	الوصف
`bank_continue_without_bank`	string	عندما تعرض الخطوة Continue without your bank. تعرضه القيمة `when_needed`، وهي الافتراضية، مرة واحدة عندما لا تعمل أي طريقة مع دولة المستخدم أو مصرفه، أو عندما لا يمكن الوصول إلى بنكه ولا تستطيع أي طريقة أخرى التحقق منه، مثلاً لأن فحص الحساب تعذّر عليه الوصول إلى البنك أيضاً، أو عندما يقول إنه لا يملك خدمات مصرفية عبر الإنترنت. أما `from_start` فتعرضه أيضاً على الشاشة الأولى. لا يمكن إيقافه. الحفظ الذي لا يرسل هذا المفتاح ولا `bank_allow_skip` يحصل على القيمة `when_needed`.
`bank_statement_standalone_enabled`	boolean	مع `bank_statement_enabled`، تُعرض أيضاً خانة رفع كشف الحساب عندما لا تحدث أي محاولة عبر البنك، في أي دولة، حتى في دولة لا تغطيها أي طريقة لتسجيل الدخول إلى البنك أو فحص الحساب. يُحتسب عندها بشكل مستقل باسم `bank_statement_upload`، بسعر USD 0.20 لكل كشف حساب يُقيَّم، قبل سعر عقدك أو السعر الخاص: راجع الأسعار. يمكن لجلسات البيئة التجريبية اختبار هذه الميزة دون فوترة. مفعّلة افتراضياً.

ما يترتب على متابعة المستخدم للجلسة يحدده bank_unsupported_action أو bank_attempts_exhausted_action أو bank_skipped_action، بحسب سبب المتابعة، ما لم تكن محاولة قُيّمت قبله قد حسمت الخطوة بالفعل: راجع إجراءات الحكم.

مقارنة صاحب الحساب

حقل الإعداد	النوع	الوصف
`bank_reference_identity`	string	الخطوة السابقة التي توفر الهوية التي تُقارَن بها هوية صاحب الحساب: `kyc` (التحقق من الهوية)، أو `database_validation`، أو `expected_details` (ما أرسلته عند إنشاء الجلسة)، أو `questionnaire`، أو `auto` لاستخدام أيٍّ منها أنتجه سير العمل. تُعاد الخطوة التي وفّرت الهوية فعلياً في النتيجة باسم `reference_identity_source`.
`bank_field_sources`	object	المكان الذي تُقرأ منه قيمة حقل من الهوية المرجعية عندما لا توجد خطوة سابقة في المخطط تستطيع ملء هذا الحقل. مفتاح الخريطة هو أحد القيم `full_name` أو `first_name` أو `last_name` أو `address`. يسمّي `source` الجهة المنتِجة، ويسمّي `key` القيمة داخلها: مفتاح حقل Document AI في حالة `document_ai`، ومعرّف عقدة الاستبيان في حالة `questionnaire`، و`expected_details.<field>` أو `metadata.<key>` في حالة `expected_data`. لا يجوز للقيمة التي تحت `expected_details.` أن تشير إلا إلى حقل تحمله حمولة إنشاء الجلسة فعلاً: `address` أو `country` أو `date_of_birth` أو `first_name` أو `gender` أو `id_country` أو `identification_number` أو `ip_address` أو `last_name` أو `nationality` أو `poa_country`. يُرفض الإدخال المشوّه عند الحفظ، ولا يُتجاهل. الشكل: `{"full_name"\|"first_name"\|"last_name"\|"address": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`
`bank_name_match_threshold`	integer	عند هذه الدرجة أو فوقها يُعدّ اسم صاحب الحساب مطابقاً. من `50` إلى `100`، والقيمة الافتراضية `85`.
`bank_partial_match_floor`	integer	أدنى من هذه الدرجة يُعدّ الاسم غير مطابق. من `0` إلى `99`، والقيمة الافتراضية `70`. النطاق الواقع بين الحد الأدنى والعتبة هو التطابق الجزئي، لذلك يجب أن يكون الحد الأدنى أقل من العتبة بشكل صارم، وإلا رُفض الحفظ. القيمة الصريحة `null` تعني هنا «استخدم القيمة الافتراضية»، ولهذا يُرفض عتبة قدرها `50` بلا حد أدنى، إذ يُتحقق منه على أنه `50` مقابل الحد الأدنى الافتراضي وهو `70`.
`bank_require_address_match`	boolean	يشترط أيضاً أن يطابق عنوان صاحب الحساب. الاسم الذي بلغ العتبة، لكن عنوانه دون مستواها، يتحول إلى تطابق جزئي. المؤسسة التي لا تُرجع عنواناً تُعفى من هذا الشرط، أما الجلسة التي ليس لها عنوان خاص بها للمقارنة فلا تُعفى، وتنتهي بتطابق جزئي. متوقف افتراضياً.
`bank_use_provider_score`	boolean	يقرأ أيضاً درجة المؤسسة الخاصة بمطابقة اسم صاحب الحساب، ويسمح لها بالحسم عندما تكون أعلى من درجة Didit، أو عندما لم يكن لدى Didit اسم صاحب حساب يقيّمه أصلاً. النتيجة المحسومة بهذه الطريقة تسجّل `provider_only` طريقةً للمطابقة، والاتصال الذي لم يُرجع هذه الدرجة يسجّل تحذير `provider_score_unavailable`. مفعّل افتراضياً.
`bank_show_match_result_to_user`	boolean	يعرض نتيجة الملكية للمستخدم داخل تدفق التحقق. عند الإيقاف تُسجَّل النتيجة في الجلسة ولا تُعرض له أبداً.

فحص الحساب

تنطبق هذه المفاتيح على فحص الحساب وحده. يحتفظ تسجيل الدخول إلى البنك بتطابقاته القريبة وbank_max_attempts الخاص به.

حقل الإعداد	النوع	الوصف
`bank_account_check_accept_close_match`	boolean	مفعّل افتراضياً: الاسم الذي يمنحه البنك درجةً بين `bank_partial_match_floor` و`bank_name_match_threshold` يُعدّ تطابقاً قريباً. يؤكد المستخدم الاسم الذي يحتفظ به البنك عند تفعيل `bank_suggest_holder_name`، ويحسم `bank_partial_match_action` النتيجة. عند الإيقاف يُعدّ هذا التطابق القريب عدم تطابق (`OWNER_NAME_MISMATCH`، ويحسمه `bank_no_match_action`) ويستنفد المحاولة.
`bank_account_check_max_attempts`	integer	عدد مرات فحص الحساب التي يحصل عليها المستخدم، من `1` إلى `5`، والقيمة `3` عند عدم التحديد: أي عدد المرات التي يمكنه فيها كتابة تفاصيل الحساب لفحص يرد عليه البنك. عدد منفصل عن `bank_max_attempts`. الفحص الذي يُرفض بصيغته المكتوبة (مثل IBAN غير صالح) أو الذي لا يستطيع البنك الرد عليه لا يستنفد أي محاولة.

البيانات المالية

يعمل bank_expected_currencies مع موافقة ownership الافتراضية وحدها. أما المفاتيح الثلاثة الأخرى فتقرأ بيانات مالية حقيقية، لذلك يحتاج كل منها إلى نطاق الموافقة المطابق له في bank_scopes، ويُرفض الحفظ بدونه.

حقل الإعداد	النوع	الوصف
`bank_expected_currencies`	string[]	رموز العملات وفق ISO 4217 التي يُتوقع أن يكون الحساب بها. القائمة الفارغة تعني أي عملة، ويُبلَّغ عن عدم التطابق عبر `bank_currency_mismatch_action`.
`bank_min_balance`	number	الحد الأدنى للرصيد المتاح، بعملة الحساب نفسها. إذا انخفض الرصيد عنه يُطلق `bank_low_balance_action`. يحتاج إلى نطاق `balances`. القيمة `0` حدّ فاصل حقيقي وليست كترك المفتاح خارج الإعداد: فالحساب المكشوف يُطلق الإجراء. هذا الإجراء افتراضياً هو `NO_ACTION`، أي يترك الحكم دون تغيير، لذلك فإن رفض الحساب المكشوف يتطلب أيضاً `bank_low_balance_action: "DECLINE"`.
`bank_transactions_history_days`	عدد صحيح	المدة التي يُقرأ فيها سجل المعاملات، من `30` إلى `365` يومًا. القيمة الافتراضية `90`. يتطلب النطاق `transactions`.
`bank_refresh_enabled`	قيمة منطقية	إعادة جلب البيانات المالية للحساب بعد أن يكون القرار قد اتُّخذ للخطوة، ما دامت موافقة البنك سارية. يتطلب نطاقًا واحدًا على الأقل من النطاقات `balances` أو `transactions` أو `income`. وعند انتهاء الموافقة لاحقًا يُعمل بالإجراء المحدد في `bank_consent_expired_action`.

ما يُخزَّن

حقل الإعداد	النوع	الوصف
`bank_store_full_identifiers`	قيمة منطقية	تخزين معرّفات الحساب دون إخفاء، بدلًا من تخزينها مُقنّعة. يتطلب النطاق `identifiers`. وحتى مع ذلك لا تُعاد الصيغة غير المُقنّعة إلا إلى الجهة المستدعية التي تملك إذن قراءة التحقق من البنك.
`bank_store_raw_owner_data`	قيمة منطقية	الاحتفاظ بتفاصيل صاحب الحساب التي أعادتها المؤسسة إلى جانب أدلة الملكية. عند إيقافه لا يُحتفظ إلا بالمقارنة نفسها: الدرجات وطريقة المطابقة ورموز الأسباب.

إجراءات القرار

يقبل كل مفتاح هنا القيم DECLINE أو REVIEW أو NO_ACTION ما لم يكن مقيّدًا، ويعود إلى القيمة الافتراضية أدناه إذا حذفته أو أرسلت null. لا يُعتمد افتراضيًا أي شيء ليس دليلًا إيجابيًا على الملكية، ولا يُرفض الطلب إلا عند وجود دليل ثابت ضد المستخدم.

حقل الإعداد	النوع	الوصف
`bank_no_match_action`	إجراء مقيّد	القرار عندما يتبيّن أن صاحب الحساب ليس الشخص الموثَّق، أي أن أعلى درجة لمطابقة الاسم أقل من `bank_partial_match_floor`. استخدم `DECLINE` أو `REVIEW`. القيمة الافتراضية `DECLINE`.
`bank_partial_match_action`	إجراء	القرار عندما يقع اسم صاحب الحساب بين `bank_partial_match_floor` و`bank_name_match_threshold`. القيمة الافتراضية `REVIEW`، ولا يؤدي أبدًا إلى الموافقة افتراضيًا.
`bank_not_verifiable_action`	إجراء	القرار عندما تتصل المؤسسة ولكنها لا تعيد هوية لصاحب الحساب للمقارنة. القيمة الافتراضية `REVIEW`.
`bank_unknown_action`	إجراء	القرار عندما تعذّر جلب الأدلة بعد إعادة المحاولات، أي فشل عابر. القيمة الافتراضية `REVIEW`.
`bank_reference_identity_missing_action`	إجراء	القرار عندما لا تكون أي خطوة سابقة قد أنتجت هوية تُقارَن بصاحب الحساب، فلا يمكن أن تكون الملكية إلا `unknown`. القيمة الافتراضية `REVIEW`.
`bank_joint_account_action`	إجراء	القرار عندما يكون للحساب أكثر من صاحب. القيمة الافتراضية `NO_ACTION`.
`bank_business_account_action`	إجراء	القرار عندما تُصنّف المؤسسة صاحب الحساب على أنه شركة لا شخص. القيمة الافتراضية `REVIEW` في سير عمل الأشخاص، و`NO_ACTION` في سير عمل الشركات (KYB) حيث يكون صاحب الحساب شركة هو ما تتوقعه الجلسة.
`bank_unsupported_action`	إجراء	القرار عندما يتابع المستخدم بدون بنك لأنه لا توجد طريقة يمكنها التحقق من دولته أو بنكه: لا يخدم أي مسار لتسجيل الدخول إلى البنك أو للتحقق من الحساب تلك الدولة، أو أن البنك الذي اختاره لا يمكن استخدامه في هذه الخطوة. تكون النتيجة عندئذ `continued_without_bank` بقيمة true و`NOT_COVERED` ضمن رموز أسبابها. القيمة الافتراضية `REVIEW`.
`bank_skipped_action`	إجراء مقيّد	القرار عندما يختار المستخدم المتابعة بدون البنك الخاص بك مع وجود طريقة للتحقق. تكون النتيجة عندئذ `continued_without_bank` بقيمة true و`SKIPPED` ضمن رموز أسبابها. استخدم `DECLINE` أو `REVIEW`. القيمة الافتراضية `REVIEW`.
`bank_attempts_exhausted_action`	إجراء مقيّد	القرار عندما يستنفد المستخدم محاولات كل طريقة للتحقق لا تزال معروضة عليه، بما فيها رفع كشف الحساب (`bank_max_attempts`، و`bank_account_check_max_attempts` حيث تتيح الدولة التحقق من الحساب)، دون اتصال ناجح بالبنك، وكذلك عندما يتابع بعد ذلك بدون بنك. استخدم `DECLINE` أو `REVIEW`. القيمة الافتراضية `DECLINE`.
`bank_consent_expired_action`	إجراء	القرار عندما تنتهي موافقة البنك بعد أن يكون القرار قد اتُّخذ للخطوة. له معنى فقط مع `bank_refresh_enabled`. القيمة الافتراضية `NO_ACTION`.
`bank_currency_mismatch_action`	إجراء	القرار عندما لا تكون عملة الحساب ضمن `bank_expected_currencies`. القيمة الافتراضية `NO_ACTION`.
`bank_country_mismatch_action`	إجراء	القرار عندما تختلف دولة المؤسسة عن الدولة المتوقعة أو دولة المستند. القيمة الافتراضية `NO_ACTION`.
`bank_low_balance_action`	إجراء	القرار عندما يكون الرصيد المتاح أقل من `bank_min_balance`. يتطلب النطاق `balances`. القيمة الافتراضية `NO_ACTION`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

ضوابط إضافية

هذه المفاتيح اختيارية. يقبل كل مفتاح إجراء القيم DECLINE أو REVIEW أو NO_ACTION.

حقل الإعداد	النوع	الوصف
`bank_abandoned_action`	إجراء	القرار عندما تنتهي الخطوة دون تطابق، بعد أن يترك الشخص العملية لدى بنكه ولا يعود إليها أبدًا (انتهت مهلة إحدى المحاولات).
`bank_account_age_action`	إجراء	القرار عندما يكون الحساب أحدث من `bank_account_age_days`، وهو نمط شائع لاستخدام الحسابات كبغال مالية.
`bank_account_age_days`	عدد صحيح	يُعدّ الحساب جديدًا إذا بدأ سجله منذ أقل من هذا العدد من الأيام، وتتراوح القيمة بين 1 و365، والقيمة الافتراضية 30. تُقرأ من سجل المعاملات، لذا لا تُستخدم إلا مع النطاق `transactions`.
`bank_account_lookup_enabled`	قيمة منطقية	مُهمَل: استخدم `bank_method_order` و`bank_countries.<ISO3>.methods`. يُقرأ لإصدار واحد من الحفظ الذي لا يرسل `bank_method_order`: عند تفعيل `bank_open_banking_enabled` يحدد هذا الحقل الترتيب، فيأتي التحقق من الحساب بعد تسجيل الدخول إلى البنك إذا كان مفعّلًا، ويُحذف إذا كان مُعطّلًا أو غير مضبوط. تُعيد كل عملية حفظ كتابة قيمته لتعبّر عما إذا كانت أي دولة تقدّم التحقق من الحساب.
`bank_account_type_action`	إجراء	القرار عندما يكون الحساب المتحقَّق منه حساب توفير.
`bank_address_match_threshold`	عدد صحيح	عند هذه الدرجة أو أعلى منها يُعدّ عنوان صاحب الحساب متطابقًا، وتتراوح القيمة بين 50 و100، والقيمة الافتراضية 70. تُقرأ فقط مع `bank_require_address_match`.
`bank_address_mismatch_action`	إجراء	القرار عندما يختلف عنوان صاحب الحساب، فيتحول التطابق إلى تطابق قريب. يُستخدم فقط مع `bank_require_address_match`.
`bank_auto_add_countries`	قيمة منطقية	إتاحة مسار لكل دولة يمكن لأحد مسارات هذه العقدة خدمتها، بما فيها الدول المضافة بعد حفظ العقدة، باستثناء الدول التي أوقفتها `bank_countries`. تكون القيمة مُعطّلة عندما لا يوجد المفتاح، فلا تتوسع عقدة موجودة من تلقاء نفسها.
`bank_cash_flow_action`	إجراء	القرار عند دخول الأموال وخروجها مباشرةً، أو عند وصول تحويلات صغيرة كثيرة (تدفق نقدي عابر). يتطلب النطاق `transactions`.
`bank_dob_match_enabled`	boolean	مقارنة تاريخ ميلاد صاحب الحساب، عندما يشاركه البنك، بتاريخ الميلاد المتحقَّق منه. لا يغيّر عدم التطابق نتيجة الملكية أبداً، بل يُطلق `bank_dob_mismatch_action`. مفعّل افتراضياً.
`bank_dob_match_threshold`	integer	عند هذه الدرجة أو أعلى يتطابق تاريخ الميلاد، وتتراوح القيمة من 50 إلى 100، والافتراضي 70. التاريخ إما هو نفسه في اليوم نفسه أو لا، لذلك يُحتسب بدرجة 100 أو 0.
`bank_dob_mismatch_action`	إجراء	القرار عند اختلاف تاريخ ميلاد صاحب الحساب. يُستخدم فقط مع `bank_dob_match_enabled`.
`bank_email_match_enabled`	boolean	مقارنة البريد الإلكتروني المسجَّل لدى البنك بالبريد الإلكتروني المتحقَّق منه في الجلسة. يُطلق عدم التطابق `bank_email_mismatch_action`. معطّل افتراضياً.
`bank_email_match_threshold`	integer	عند هذه الدرجة أو أعلى يتطابق البريد الإلكتروني، وتتراوح القيمة من 50 إلى 100، والافتراضي 70.
`bank_email_mismatch_action`	إجراء	القرار عند اختلاف البريد الإلكتروني لصاحب الحساب. يُستخدم فقط مع `bank_email_match_enabled`.
`bank_evidence_retention_days`	integer	تُحذف أدلة البنك بعد هذا العدد من الأيام من صدور القرار: 30 أو 90 أو 365 أو 1825. القيمة null تُبقي الأدلة مع الجلسة. يُحذف ما يلي: بيانات صاحب الحساب، والهوية التي قورنت بها، ومعرّفات الحساب، والبيانات المالية، وكشف الحساب المرفوع، ويُلغى أي اتصال ما زال نشطاً. تبقى النتيجة ودرجات التقييم ورموز الأسباب. حذف الجلسة يحذف كل شيء، أيهما يحدث أولاً.
`bank_fallback_used_action`	إجراء	القرار عند التحقق من الحساب عبر الإيداعات الصغيرة أو رفع كشف الحساب.
`bank_match_any_holder`	boolean	يتطابق الحساب المشترك أو المملوك بشكل مشترك عندما يتطابق أي صاحب مدرج مع الشخص. عند التعطيل، لا يتطابق إلا أول صاحب يدرجه البنك. مفعّل افتراضياً.
`bank_microdeposits_enabled`	boolean	تقديم الإيداعات الصغيرة كبديل: يصل إلى الحساب إيداعان صغيران، ويُدخل الشخص المبلغين. تُعرض فقط في دولة يستطيع مسارها إرسالهما، وبعد محاولة تحقق بنكي مدفوعة في الجلسة نفسها. تُقدَّم دون رسوم إضافية، ويدفع العميل سعر المسار مرة واحدة. يمكن لجلسات البيئة التجريبية اختبارها دون فوترة. صاحب الحساب هو الاسم الذي تحقق منه الجلسة، والذي يُقرّ الشخص بأن الحساب مسجَّل باسمه، لذلك يُسجَّل الحساب المتحقَّق منه تحذير `holder_declared`. مفعّل افتراضياً.
`bank_mule_score_action`	إجراء	القرار عندما تبلغ درجة الحساب المستخدم كوسيط `bank_mule_score_threshold` أو تتجاوزه.
`bank_mule_score_threshold`	integer	عند بلوغ درجة الحساب المستخدم كوسيط هذا الحد أو تجاوزه، وتتراوح من 0 إلى 100، يُطلق `bank_mule_score_action`؛ والافتراضي 70. تجمع الدرجة بين حساب جديد، والتدفق النقدي العابر، وتفريغ الرصيد، والتحويلات الصغيرة الواردة الكثيرة، وتُقرأ من سجل المعاملات (النطاق `transactions`).
`bank_open_banking_enabled`	boolean	مهجور: استخدم `bank_method_order` و`bank_countries.<ISO3>.methods`. يُقرأ لإصدار واحد من حفظٍ لا يرسل `bank_method_order`: مع `bank_account_lookup_enabled`، يحدد الترتيب، وهو تسجيل الدخول البنكي إذا كان مفعّلاً أو غير محدد. يكتبه كل حفظ من جديد بقيمة تعني ما إذا كانت أي دولة تقدّم تسجيل الدخول البنكي.
`bank_phone_match_enabled`	boolean	مقارنة رقم الهاتف المسجَّل لدى البنك برقم الهاتف المتحقَّق منه في الجلسة. يُطلق عدم التطابق `bank_phone_mismatch_action`. معطّل افتراضياً.
`bank_phone_match_threshold`	integer	عند هذه الدرجة أو أعلى يتطابق رقم الهاتف، وتتراوح القيمة من 50 إلى 100، والافتراضي 70.
`bank_phone_mismatch_action`	إجراء	القرار عند اختلاف رقم هاتف صاحب الحساب. يُستخدم فقط مع `bank_phone_match_enabled`.
`bank_popular_mode`	string	`auto` (الافتراضي) يرتّب البنوك الشائعة حسب البنوك التي يربط الناس حساباتهم بها أكثر في الدولة، أما `manual` فيعرض بدلاً من ذلك `popular_institutions` لكل دولة من `bank_countries`، بترتيبها.
`bank_statement_document_checks_action`	إجراء	القرار عندما يحمل كشف الحساب المرفوع دليلاً على التحرير أو التلاعب. الافتراضي `REVIEW`.
`bank_statement_enabled`	boolean	إتاحة رفع كشف الحساب البنكي كبديل: كشف من آخر 3 أشهر، يُفحص للتلاعب، ويُطابَق اسم صاحبه كما يُطابَق اسم صاحب الحساب لدى البنك. يُقدَّم دون رسوم إضافية بعد محاولة تحقق بنكي مدفوعة في الجلسة نفسها. ومع `bank_statement_standalone_enabled` يُعرض أيضاً دون محاولة بنكية قبله، في أي دولة، ويُفوتَر بشكل مستقل. يمكن لجلسات البيئة التجريبية اختباره دون فوترة. معطّل افتراضياً.
`bank_suggest_holder_name`	boolean	عند التطابق القريب، يعرض على الشخص الاسم الذي يحتفظ به البنك للحساب، ويطلب منه تأكيد أنه له أو ربط حساب آخر. تُسجَّل إجابته كـ `holder_confirmation`، وينهي التأكيد الخطوة وفق `bank_partial_match_action`. مفعّل افتراضياً.
`fallback_to_native`	boolean	ما إذا كان الاتصال بمزوّد من السوق الذي تعذّر إنشاؤه سيعود إلى المسار الأصلي لـ Didit. معطّل افتراضياً: فالعودة الصامتة ستستنزف رصيد Didit لديك في جلسة كنت تتوقع أن تعمل بموجب عقد مزوّدك الخاص. يُسجَّل الاتصال الناتج عن العودة إلى المسار الأصلي كـ `credential_source = native` ويُفوتَر بسعر المسار الأصلي.
`provider_key`	string	المسار الذي يشغّل الخطوة. الفارغ (الافتراضي) هو التحقق البنكي الأصلي من Didit، وهو منتج مستقل عن المزوّد توجّهه Didit إلى مزوّد الخدمات المصرفية المفتوحة الإقليمي الذي يخدم دولة المستخدم ومؤسسته، وفق عقود Didit وفوترتها. القيمة التي تسمّي مزوّدًا من السوق تعني أن هذا التطبيق قد ربط بيانات اعتماد ذلك المزوّد، فتعمل الجلسة وتُفوتَر وتُلغى في حسابك لدى المزوّد، ولا تحتسب Didit سوى رسوم منصة السوق. يُرفض الحفظ لأي مزوّد غير متصل.

مثال لكائن config، لحساب يكون فيه التحقق البنكي مفعّلاً والمسار الذي اخترته يغطي الدولة التي تدرجها:

{
  "bank_method_order": ["open_banking", "account_lookup"],
  "bank_countries": {
    "ESP": { "enabled": true, "institutions": "all" }
  },
  "bank_scopes": { "ownership": true },
  "bank_eligible_account_types": ["checking", "current"],
  "bank_name_match_threshold": 85,
  "bank_partial_match_floor": 70,
  "bank_partial_match_action": "REVIEW",
  "bank_no_match_action": "DECLINE"
}

bank_countries هو ما يجعل هذه الخطوة تعمل فعلاً، ويُتحقَّق منه مقابل المسار الذي تعمل عليه العقدة، لا مقابل قائمة عامة. تُرفض عند الحفظ أي دولة لا يستطيع ذلك المسار فيها إثبات ملكية الحساب، ويُذكر اسمها في الخطأ، لذا اقرأ الخطأ ولا تفترض أن الدولة قُبلت وستُتخطى وقت التشغيل.

AML

قيمة الميزة: AML. لفحص الأشخاص وفق KYC، استخدم الحقول التالية:

حقل الإعداد	النوع	الوصف
`is_aml_ongoing_monitoring_enabled`	قيمة منطقية	يفعّل مراقبة AML المستمرة.
`aml_score_approve_threshold`	عدد صحيح	حد الموافقة.
`aml_score_review_threshold`	عدد صحيح	حد المراجعة.
`aml_match_score_threshold`	عدد صحيح	حد درجة التطابق للتطابقات المحتملة.
`aml_name_weight`	عدد صحيح	وزن الاسم. إذا قُدّم أي وزن لـ AML، يجب أن يساوي مجموع أوزان الاسم وتاريخ الميلاد والدولة `100`.
`aml_dob_weight`	عدد صحيح	وزن تاريخ الميلاد.
`aml_country_weight`	عدد صحيح	وزن الدولة.
`create_cases_on_hit`	قيمة منطقية	افتح حالة تلقائيًا عندما يُرجع الفحص تطابقًا، بدلًا من ترك التطابق ليُفرز من الجلسة. متوقف افتراضيًا.
`case_blueprint`	UUID	القالب الذي تُبنى عليه الحالة المُنشأة تلقائيًا. لا يكون له معنى إلا مع `create_cases_on_hit`، وعند عدم تعيينه يُستخدم الإعداد الافتراضي للحساب.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

للفحص الخاص بالشركات وفق KYB، استخدم الحقول التالية:

حقل الإعداد	النوع	الوصف
`kyb_score_approve_threshold`	عدد صحيح	حد موافقة AML للشركة.
`kyb_score_review_threshold`	عدد صحيح	حد مراجعة AML للشركة.
`kyb_enable_ongoing_monitoring`	قيمة منطقية	يفعّل مراقبة AML المستمرة في KYB.
`kyb_company_aml_match_score_threshold`	عدد صحيح	حد درجة التطابق لفحص AML للشركة.
`kyb_company_aml_name_weight`	عدد صحيح	وزن اسم الشركة. يجب أن يساوي مجموع أوزان AML للشركة `100` عند تقديمها.
`kyb_company_aml_dob_weight`	عدد صحيح	وزن تاريخ التأسيس أو تاريخ الميلاد.
`kyb_company_aml_country_weight`	عدد صحيح	وزن الدولة.

فحص كيان استخرجته خطوة Document AI

تقرأ خطوة AML عادةً الجهة التي تفحصها من خطوة OCR (شخص) أو من خطوة KYB_REGISTRY (شركة). أما سير العمل الذي تكون خطوة الاستخراج الوحيدة فيه هي DOCUMENT_AI، أي المستندات غير الموحدة مثل شهادة ضريبية أو عقد تأسيس، فلا يتوفر فيه أيٌّ من الخطوتين، لذا يجب أن يحدد مصدر كل مدخل من مدخلات الفحص.

حقل الإعداد	النوع	الوصف
`aml_field_sources`	كائن	مصدر الكيان الذي تفحصه هذه الخطوة. يحدد `source` المُنتج، ويحدد `key` القيمة داخله: مفتاح حقل Document AI للمصدر `document_ai`، أو معرّف عقدة الاستبيان للمصدر `questionnaire`، أو `expected_details.<field>` أو `metadata.<key>` للمصدر `expected_data`. مفتاح الخريطة هو أحد مدخلات الفحص الأربعة: `full_name` و`date_of_birth` و`nationality` و`document_number`، ويُقرأ للشركة على أنه الاسم القانوني وتاريخ التأسيس والدولة والرقم التسجيل. يُربط حقل Document AI المُعرَّف أصلًا بأحد هذه المدخلات الأربعة تلقائيًا، ولا يُحفظ عمدًا، حتى لا تُثبَّت ربطة قديمة عند تغيير اسم الحقل. الربط الصريح يتقدم على الربط التلقائي وعلى مستند الهوية معًا، وأي ربط لا يُحل إلى شيء وقت التشغيل يترك المدخل فارغًا ولا يعود إلى بديل. في سير عمل الأعمال (KYB)، تكون الشركة التي تُرجعها خطوة `KYB_REGISTRY` هي المرجع: لا يتجاوز مدخلاتها إلا الربط الصريح، ولا يُطبَّق الربط التلقائي على سجل الشركة الذي تُرجعه خطوة السجل، وعند عدم وجود خطوة سجل تكون الخريطة هي الهوية كاملةً. الشكل: `{"full_name"\|"date_of_birth"\|"nationality"\|"document_number": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`.
`aml_entity_type`	نص	`person` أو `company`. القيمة الافتراضية `person` في سير عمل الأشخاص (KYC)، و`company` في سير عمل الأعمال (KYB). اضبطها على `company` لفحص الشركة المذكورة في مستند مرفوع من دون خطوة `KYB_REGISTRY`: يبحث المزود في سجلات الشركات، وتُحتسب درجة التطابق على أنها لشركة.
`aml_incomplete_data_action`	إجراء	الحكم عندما يُجرى الفحص على هوية أقل من كاملة (الاسم وتاريخ الميلاد والدولة). القيمة الافتراضية `REVIEW`. تسمح قيمة `NO_ACTION` بالمتابعة ببيانات ناقصة في سير عمل يعلم أنه لا يحتفظ إلا بالاسم. يُجرى الفحص في الحالتين، ويُسجَّل سجل البيانات الجزئية في الحالتين، وهذا الإعداد يحدد فقط أثرها في الحالة.

مثال: فحص الشركة المذكورة في acta constitutiva مكسيكية، من دون أي مستند هوية في سير العمل:

{
  "feature": "AML",
  "config": {
    "aml_entity_type": "company",
    "aml_field_sources": {
      "full_name": { "source": "document_ai", "key": "razon_social" },
      "document_number": { "source": "document_ai", "key": "rfc" },
      "date_of_birth": { "source": "document_ai", "key": "fecha_constitucion" },
      "nationality": { "source": "document_ai", "key": "pais" }
    },
    "aml_incomplete_data_action": "REVIEW"
  }
}

إذا لم تكن هناك خطوة OCR ولا خطوة KYB_REGISTRY قبلها، يجب أن تكون خطوة AML قادرة على تعبئة full_name، إذ لا يوجد بحث لدى المزود من دون اسم. سير العمل الذي لا يربط أي مدخل، أو الذي يربط مفتاح Document AI لا تستخرجه أي خطوة سابقة، يُرفض عند الحفظ بدلًا من أن يُحفظ ولا يفحص شيئًا. دقة AML تتبع مباشرةً عدد المعرّفات التي تقدمها: الفحص بالاسم فقط هو ما يُنتج حجمًا كبيرًا من الإيجابيات الكاذبة.

تحليل الجهاز وعنوان IP

قيمة الميزة: IP_ANALYSIS.

حقل الإعداد	النوع	الوصف
`ip_mismatch_action`	إجراء	الإجراء عندما لا يتطابق موقع IP الجغرافي مع البيانات المتوقعة.
`ip_location_not_determined_action`	إجراء	القرار عندما لا يُسجَّل أي عنوان IP يحدِّد المستخدم النهائي، فلا يكون للجلسة موقع IP على الإطلاق: الدولة والمدينة ومزود خدمة الإنترنت (ISP) والإحداثيات والمنطقة الزمنية غير متاحة، ولا يمكن تنفيذ `ip_geofencing_by_country` ومقارنة دولة المستند وفحوصات VPN ومراكز البيانات. القيمة الافتراضية هي `NO_ACTION`، وهي تُبقي تحذير `IP_LOCATION_NOT_DETERMINED` ظاهراً في الجلسة دون تغيير قرارها؛ اضبط `REVIEW` أو `DECLINE` إذا كان يجب ألا تمرّ جلسة غير محددة الموقع.
`vpn_detection_action`	إجراء	الإجراء عند رصد استخدام VPN أو خادم وكيل.
`expected_ip_mismatch_action`	إجراء	الإجراء عندما لا يطابق عنوان IP العنوان المتوقع.
`duplicated_ip_action`	إجراء	الإجراء عندما يُعاد استخدام عنوان IP بشكل مريب.
`duplicated_device_action`	إجراء	الإجراء عندما يُعاد استخدام البصمة الدائمة نفسها للجهاز عبر جلسات من قيم `vendor_data` مختلفة.
`recovered_device_action`	إجراء	الإجراء عندما يربط استرداد البصمة في الإصدار 2 الجلسة بجهاز سبق رؤيته بثقة عالية بعد تغيّر معرّف الجهاز الدائم.
`is_ip_geofencing_enabled`	منطقي	يفعّل قيود الجغرافيا عبر IP. عندما تكون القيمة `false`، يُحفظ `ip_geofencing_by_country` دون تطبيقه.
`ip_geofencing_by_country`	كائن	قواعد موقع IP لكل دولة، مفهرسة برمز الدولة ISO-3: `{"USA": {"allowed": true, "states": {"California": {"allowed": false}}}}`. تتجاوز إدخالات الولاية/المنطقة إعداد الدولة، والدول غير المدرجة مسموح بها.
`ip_geofencing_action`	إجراء	الإجراء عندما يقع IP الجلسة في دولة أو ولاية/منطقة غير مسموح بها. القيمة الافتراضية هي `DECLINE`.
`automation_detected_action`	إجراء	القرار عندما يبدو أن الأتمتة تقود الجلسة بدلاً من شخص.
`cross_org_fraud_device_action`	إجراء	القرار عندما وسمت مؤسسة أخرى في الشبكة هذا الجهاز بأنه احتيالي.
`cross_org_fraud_ip_action`	إجراء	القرار عندما وسمت مؤسسة أخرى في الشبكة عنوان IP هذا بأنه احتيالي.
`device_app_tampered_action`	إجراء	القرار عندما يبدو الملف الثنائي للتطبيق المضيف معدّلاً.
`device_blocklist_action`	إجراء	القرار عندما يكون الجهاز في قائمة الحظر الخاصة بالمؤسسة.
`device_debugger_action`	إجراء	القرار عندما يكون مُصحِّح أخطاء مرتبطاً بالتطبيق المضيف.
`device_emulator_action`	إجراء	القرار عندما يكون الجهاز محاكيًا لا جهازاً فعلياً.
`device_hooking_action`	إجراء	القرار عند رصد عملية ربط أو تزويد بالأدوات أثناء التشغيل.
`device_integrity_missing_action`	إجراء	القرار عندما لا تُعاد أي إقرار سلامة للجهاز من المنصة.
`device_rooted_action`	إجراء	القرار عندما يكون الجهاز مُجذَّر أو مكسور الحماية.
`multiple_devices_action`	إجراء	القرار عندما تُدار الجلسة من أكثر من جهاز.
`device_liveness_attack_history_action`	إجراء	الإجراء عندما استُخدم الجهاز نفسه (بمطابقته عبر معرّف الجهاز الدائم) في جلسة سابقة لمستخدم آخر حُكم بأن التقاط الحيوية الخاص به هجوم (التحذير `DEVICE_LINKED_TO_LIVENESS_ATTACK`). القيمة الافتراضية هي `NO_ACTION`.
`device_model_inconsistency_action`	إجراء	الإجراء عندما تم الإبلاغ عن الجهاز نفسه (بمطابقته عبر معرّف الجهاز الدائم) على أنه طراز مختلف في جلسة سابقة (التحذير `DEVICE_MODEL_INCONSISTENT`). القيمة الافتراضية هي `NO_ACTION`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

مثال:

{
  "feature": "IP_ANALYSIS",
  "config": {
    "vpn_detection_action": "REVIEW",
    "duplicated_device_action": "REVIEW",
    "recovered_device_action": "REVIEW",
    "is_ip_geofencing_enabled": true,
    "ip_geofencing_by_country": {
      "USA": { "allowed": true, "states": { "California": { "allowed": false } } },
      "RUS": { "allowed": false, "states": null }
    },
    "ip_geofencing_action": "DECLINE"
  }
}

استخدم recovered_device_action بشكل منفصل عن duplicated_device_action عندما تريد مراقبة الأجهزة المستردة بثقة عالية قبل رفضها تلقائياً. هذا مفيد أثناء الإطلاق التدريجي، لأن مطابقات الأجهزة المستردة مصممة لكشف حلقات الاحتيال، لكن ينبغي معايرتها مع حركة المرور الخاصة بك.

التحقق من الموقع

قيمة الميزة: GEOLOCATION. يتحقق من موقع الشخص أثناء التحقق، استناداً إلى موقع الجهاز أو موقع عنوان IP للاتصال، مقارنةً بالمناطق المسموح بها والمناطق المحظورة وموقع عنوان IP وعنوان المستند. راجع التحقق من الموقع لمعرفة طريقة عمل الخطوة، وتقريرها لحقول القرار. ضعها بعد التحقق من الهوية أو إثبات العنوان إذا أردت قياس المسافة إلى عنوان المستند، لأن المسافة لا تُقاس إلا عند وجود عنوان مسجَّل. عندما يكون geolocation_position_source غير مضبوط، تحتاج المسافة إلى موقع عنوان IP إلى خطوة تحليل الجهاز وعنوان IP في سير العمل نفسه. جميع المفاتيح اختيارية: الخطوة ذات config فارغ تطلب من الجهاز موقعاً بدقة 250 متراً، لا يتجاوز عمره 120 ثانية، وتمنح الشخص 3 محاولات، ولا تطبّق أي قاعدة للمناطق. لكل نتيجة مفتاح إجراء خاص بها. ويأخذ مفتاح الإجراء الذي تتركه غير مضبوط القيمةَ الافتراضية لـgeolocation_preset الذي اخترته، أو القيمةَ الافتراضية لكل مفتاح المذكورة أدناه إذا لم تختر أي إعداد مسبق. يكون الإجراء الافتراضي للموقع غير المؤكد أو المرفوض هو REVIEW، وليس DECLINE أبداً، لأن رفض الإذن أو اتساع نصف القطر ليس دليلاً على الاحتيال. الإجراء الذي تحدده صراحةً يتقدّم دائماً على الإعداد المسبق. التحدي المُعاد تشغيله (LOCATION_REPLAY_DETECTED) والتحقق من سلامة الجهاز الفاشل (LOCATION_INTEGRITY_FAILED) يؤديان دائماً إلى الرفض، ولا يملكان مفتاح إجراء.

حقل الإعداد	النوع	الوصف
`geolocation_position_source`	نص	مصدر الموقع. يطلب `device_and_ip` موقع الجهاز ويقارنه بموقع عنوان IP للاتصال الذي يُرسَل منه (ويُجرى بحث عن معلومات IP عندما لا يكون ذلك العنوان مخزناً مؤقتاً بعد). أما القيمة غير المضبوطة (الافتراضية) فتطلب موقع الجهاز أيضاً، وتقارنه، كما كان قبل وجود هذا المفتاح، بموقع عنوان IP الذي رصدته خطوة تحليل الجهاز وعنوان IP في الجلسة، لذلك لا توجد مسافة من دون تلك الخطوة، ولا يُبحث عن الاتصال أبداً. الاستثناء هو عقدة تتصرف بناءً على نتيجة VPN أو بروكسي أو Tor (إجراءها الخاص أو إعدادها المسبق): تبحث عن الاتصال لتلك النتيجة وتقارن الجهاز به، تماماً كما يفعل `device_and_ip`. لا يقارن `device_only` الموقع بموقع عنوان IP أبداً، ويبحث عن الاتصال فقط لتلك النتائج. أما `ip_only` فلا يسأل الشخص أبداً، ويحكم على موقع عنوان IP للاتصال بدلاً من ذلك، على مستوى المدينة بنصف قطر 50 كم، من دون أي قاعدة للدقة أو الحداثة أو منح موقع تقريبي؛ ومع `geolocation_areas` يُحكم على المدينة الساحلية ضمن دولتها ما لم تقع دولة أخرى ضمن ذلك النصف. في العقدة التي تطلب موقع الجهاز، تُعامَل المحاولة التي لا يتوفر فيها موقع للجهاز بحسب ما إذا كانت رفضًا أو فشلًا: لا يحلّ موقع عنوان IP محلها أبداً.
`geolocation_preset`	نص	القيم الافتراضية لكل إجراء غير مضبوط في هذه العقدة. `licensing`: خارج منطقة، أو في منطقة محظورة، أو عند VPN أو Tor أو محاكٍ، يُرفض الطلب؛ ويُراجَع البروكسي والنتائج الأخرى، ويبقى غياب إقرار الجهاز بلا إجراء. `fraud_screening`: الشيء نفسه، إلا أن ما يرفضه Licensing يذهب إلى المراجعة. القيمة Null تُبقي على الافتراضات المعتادة منذ زمن طويل. الإجراء المضبوط صراحةً يتقدّم دائماً.
`geolocation_accuracy_mode`	نص	ما يُطلب من الجهاز. `precise` يطلب من نظام التشغيل موقعاً دقيقاً، ويُعاد طلب الموقع من الشخص الذي يمنح موقعاً تقريبياً فقط ما دامت المحاولات متبقية، ثم يُحكم عليه بواسطة `geolocation_approximate_action`. أما `approximate_allowed` فيقبل منح الموقع التقريبي من دون هذا الحكم. ينطبق `geolocation_max_accuracy_radius_m` في الحالتين. القيمة الافتراضية `precise` عند عدم الضبط.
`geolocation_max_accuracy_radius_m`	عدد صحيح	أوسع نصف قطر لعدم اليقين، بالأمتار، يمكن أن يكون لموقع الجهاز ولا يزال يُحتسب. من 10 إلى 50000 متر؛ القيمة 250 عند عدم الضبط. الموقع الأوسع، أو الموقع الذي لا يُبلغ عن نصف قطره، يحدث فيه ما يحدده `geolocation_low_accuracy_behavior` ويُحكم عليه بواسطة `geolocation_low_accuracy_action`. ليس لعقدة `ip_only` نصف قطر للجهاز، ولا تطبّقه أبداً.
`geolocation_max_accuracy_radius_unit`	نص	الوحدة التي تعرض بها الكونسول `geolocation_max_accuracy_radius_m`. للعرض فقط: القيمة المخزنة هي دائماً بالأمتار، ولا تعتمد عليها أي قاعدة، وتمرّرها بيانات الخطوة فقط ليتمكن العميل من عرض الوحدة نفسها.
`geolocation_low_accuracy_behavior`	نص	ما يحدث لموقع أوسع من `geolocation_max_accuracy_radius_m`، أو لموقع بلا نصف قطر: `ask_again` (الافتراضي) يطلب من الشخص المحاولة مجدداً ما دامت المحاولات متبقية؛ `fail` ينهي الخطوة من المحاولة الأولى.
`geolocation_max_age_seconds`	عدد صحيح	أقصى عمر، بالثواني، يمكن أن يكون عليه موقع الجهاز عند استلامه في الخادم. من 5 إلى 3600 ثانية؛ القيمة 120 عند عدم الضبط. الموقع الأقدم يُطلب من الشخص مجدداً ما دامت المحاولات متبقية، ثم يُحكم عليه بواسطة `geolocation_stale_fix_action`.
`geolocation_timeout_seconds`	عدد صحيح	المدة التي يتركها العميل للجهاز كي يبحث عن موقع في كل محاولة، بالثواني؛ يمرّرها الخادم في بيانات الخطوة ولا يفرض شيئاً بنفسه. من 5 إلى 120 ثانية؛ القيمة 20 عند عدم الضبط. المحاولة التي لا تجد موقعاً في الوقت المحدد تُرسَل بالقيمة `timeout`، وتُطلب من جديد ما دامت المحاولات متبقية، ثم يُحكم عليها بواسطة `geolocation_unavailable_action`.
`geolocation_max_attempts`	عدد صحيح	عدد المحاولات التي يحصل عليها الشخص في هذه العقدة. من 1 إلى 5 محاولات؛ القيمة 3 عند عدم الضبط. المحاولة التي ما زال الشخص قادراً على تغييرها (رفض، أو موقع واسع أو قديم أو تقريبي، أو نتيجة متعلقة بالمنطقة أو بأداة إخفاء الهوية تتصرف فيها العقدة) تُطلب من جديد ما دامت المحاولات متبقية، والمحاولة الأخيرة هي التي تحسم الخطوة. الموقع المزيّف، أو نتيجة المحاكي التي تتصرف فيها العقدة، ينهي الخطوة عند المحاولة التي أبلغت عنه.
`geolocation_allow_qr_handoff`	قيمة منطقية	إتاحة المتابعة على هاتف عبر رمز QR بينما الخطوة ما تزال مفتوحة (`allow_qr_handoff` في بيانات الخطوة، و`can_handoff` في كل إجابة إرسال). تعمل حزم SDK الأصلية أصلاً على الهاتف ولا تعرض الرمز أبداً. مفعّل افتراضياً.
`geolocation_allow_skip`	قيمة منطقية	السماح للشخص بالمتابعة دون موقع في أي وقت، من شاشة المقدمة أو شاشة إعادة المحاولة (`skipped: true`). يُنهي التخطي الخطوة ويُحكم عليه بواسطة `geolocation_unavailable_action`، باستثناء التخطي الذي يجيب على رفض ضمن `geolocation_refusal_path` بالقيمة `continue_without_location`، فيُسجَّل بوصفه ذلك الرفض. غير مفعّل افتراضياً.
`geolocation_deep_link_enabled`	boolean	يُمرَّر إلى العميل باسم `deep_link_enabled` في بيانات الخطوة، فيُعرض على الشخص فتح تطبيق العميل الخاص به بدلًا من ذلك. لا يطبّق الخادم أي قاعدة عليه. مُعطّل افتراضيًا.
`geolocation_refusal_path`	string	الخيار المتاح للمتابعة عند رفض الوصول إلى الموقع. `retry_then_handoff` (الافتراضي) يطلب الإذن مجددًا ما دامت المحاولات متاحة ويعرض التحويل إلى الهاتف؛ و`continue_without_location` يتيح للشخص المتابعة مع تسجيل الرفض؛ و`end_session` ينهي الخطوة والجلسة عند أول رفض، ويتطلب أن تكون قيمة `geolocation_permission_denied_action` هي المراجعة أو الرفض، وأن يكون لدى سير العمل نهاية بقرار مرفوضة أو قيد المراجعة أو قرار نهائي. يُحسم قرار الجلسة من الخطوات التي نُفِّذت، ولا يكون مقبولًا أبدًا؛ وفي سير عمل لا يمكنه الانتهاء بهذا القرار، تُستخدم النهاية غير المقبولة الأخرى (مرفوضة بدلًا من قيد المراجعة، وقيد المراجعة بدلًا من مرفوضة).
`is_geolocation_geofencing_enabled`	boolean	يُفعِّل قواعد المناطق. لا تُطبَّق `geolocation_areas` أو `geolocation_geofencing_by_country` القديمة إلا عندما تكون هذه القيمة صحيحة، ولا تُدرج بيانات الخطوة `available_areas` إلا حينها. مُعطّل افتراضيًا. عند تفعيله، تتطلب قائمة `geolocation_areas` منطقة مسموحًا بها واحدة على الأقل.
`geolocation_areas`	array	المناطق المسموح بها والمحظورة، وتُطبَّق عندما يكون `is_geolocation_geofencing_enabled` صحيحًا. لا يجتاز الموقع الاختبار إلا إذا كان داخل منطقة مسموح بها، والمنطقة المحظورة تتغلب دائمًا على المنطقة المسموح بها. يُحسب الموقع وفق دائرة الدقة كاملةً: الدائرة التي تعبر حافة تحسم النتيجة تكون غير محددة، ولا تُعد خارج المنطقة أبدًا. تنتهي الدولة أو المنطقة عند بداية اليابسة الأخرى، لا عند الساحل. والموقع الذي تضعه الحدود على غير اليابسة (واجهة بحرية أو رصيف قطعه خط الساحل المبسّط) يكون غير محدد لكل دولة أو منطقة ضمن نطاق يساوي نصف قطره زائدًا 12 ميلًا بحريًا. `id` هو الاسم الذي تستخدمه قواعد الفروع و`geolocation.inside_areas` و`geolocation.blocked_areas`؛ ويحدد `kind` الشكل: `country` لدولة كاملة لها حدود منشورة بمعرّف ISO 3166-1 alpha-3 (الإقليم الذي ترسمه الحدود جزءًا من دولة أخرى يكون `region`، مثل ريونيون بوصفها `FR-RE` التابعة لفرنسا، أو بونير وسينت أوستاتيوس وسابا بوصفها `NL-BQ1` إلى `NL-BQ3`)، و`region` لرموز ISO 3166-2 لمناطق دولة واحدة لها حدود منشورة، و`circle` (من 1 إلى 500 كم)، و`polygon` (من 3 إلى 200 نقطة، وهي حلقة لا تتقاطع حوافها ولا تلامس بعضها). بحد أقصى 50 منطقة، ومعرّفات فريدة، ومنطقة مسموح بها واحدة على الأقل عندما يكون التحديد الجغرافي مفعّلًا. لا يمكن دمجه مع `geolocation_geofencing_by_country`.
`geolocation_geofencing_by_country`	object	قواعد السماح والرفض للدولة والمنطقة بحسب الموقع الذي يحدده الجهاز نفسه، وتُطبَّق فقط عندما يكون `is_geolocation_geofencing_enabled` صحيحًا. له البنية نفسها التي لـ`ip_geofencing_by_country` في تحليل IP، باستثناء أن مفاتيح `states` تكون رموز ISO 3166-2 (مثل `US-NJ`) لا أسماء الولايات، لأن الموقع يُحل إلى تقسيم إداري وليس إلى اسم مدينة يوفره مزوّد الخدمة. الدولة غير المدرجة مسموح بها. يُرفض حفظ قاعدة منطقة لدولة ليس لها حدود ISO 3166-2 منشورة، بدلًا من تجاهلها بصمت.
`geolocation_ip_distance_km`	integer	أقصى مسافة مسموح بها بالكيلومترات بين موقع الجهاز وموقع IP، بعد طرح نصفي قطري عدم اليقين في الحالتين، وبعدها يُطبَّق `geolocation_ip_distance_action`. القيمة 200 عند حذف المفتاح، وتعطيل المقارنة بتحديد القيمة null. لا تُقارن إلا العقدة التي تكون فيها قيمة `geolocation_position_source` هي `device_and_ip` أو غير مُعيّنة، ويحدد هذا المفتاح موقع IP الذي تُقارن به.
`geolocation_ip_distance_unit`	string	الوحدة التي يعرض بها الكونسول `geolocation_ip_distance_km`. للعرض فقط: القيمة المخزنة دائمًا بالكيلومترات، ولا تعتمد عليها أي قاعدة.
`geolocation_document_distance_km`	integer	أقصى مسافة بالكيلومترات يمكن أن يبعد فيها الموقع (وهو موقع IP في عقدة `ip_only`) عن العنوان الذي يسميه `geolocation_document_distance_basis`، قبل أن يُطبَّق `geolocation_document_distance_action`. إذا كانت غير مُعيّنة أو null (وهو الافتراضي)، فالقاعدة معطّلة.
`geolocation_document_distance_unit`	string	الوحدة التي يعرض بها الكونسول `geolocation_document_distance_km`. للعرض فقط: القيمة المخزنة دائمًا بالكيلومترات، ولا تعتمد عليها أي قاعدة.
`geolocation_document_distance_basis`	string	العنوان الذي تُقاس منه `geolocation_document_distance_km`: `document` (الافتراضي: عنوان وثيقة الهوية، ثم إثبات العنوان)، أو `proof_of_address` وحده، أو `declared` (وهو `expected_details.address` المُعطى عند إنشاء الجلسة، بعد ترميزه جغرافيًا).
`geolocation_travel_tolerance_enabled`	boolean	يُستثنى البعد عن العنوان إذا رُصد الشخص نفسه (نفس `vendor_data`) ضمن نطاق `geolocation_travel_usual_area_km` من ذلك العنوان خلال آخر `geolocation_travel_max_days` يومًا. لا يُستثنى أبدًا VPN أو موقع مزيّف أو منطقة محظورة أو الوجود خارج المناطق المسموح بها. لا يُعد الشخص مرصودًا هناك إلا إذا قاس الجهاز الموقع فعليًا: فقراءة الموقع الوهمية أو المُحاكاة، أو المحاكي، أو فشل إقرار الجهاز، لا تُحتسب أبدًا.
`geolocation_travel_usual_area_km`	integer	نصف القطر حول العنوان الذي يُعد المنطقة المعتادة للشخص. من 10 إلى 500 كم؛ القيمة 100 عند عدم التحديد.
`geolocation_travel_max_days`	integer	المدة التي يبقى فيها الموقع البعيد سفرًا بعد رصد الشخص في المنطقة المعتادة. من 1 إلى 90 يومًا؛ القيمة 14 عند عدم التحديد.
`geolocation_consecutive_mismatch_count`	integer	يُرفع LOCATION_CONSECUTIVE_MISMATCHES عندما يتكرر هذا الفحص وفحوصات الشخص السابقة (نفس `vendor_data`) خارج المناطق المسموح بها، أو في منطقة محظورة، أو بعيدة عن العنوان، لهذا العدد من المرات متتالية. لا يمدّ الفحص الذي لم يقارن شيئًا السلسلة ولا يقطعها، وكذلك الموقع الذي لم يقِسه الجهاز (قراءة موقع وهمية أو مُحاكاة، أو محاكٍ، أو فشل إقرار). من 2 إلى 10؛ القيمة null (الافتراضي) تعني أن القاعدة معطّلة.
`geolocation_approximate_action`	action	الحكم عندما يمنح المستخدم موقعًا تقريبيًا بينما يطلب `geolocation_accuracy_mode` موقعًا دقيقًا. القيمة الافتراضية `REVIEW`.
`geolocation_blocked_area_action`	action	الحكم عندما يقع الموقع، مع دائرة دقته كاملةً، داخل منطقة محظورة من `geolocation_areas`. القيمة الافتراضية هي الرفض.
`geolocation_consecutive_mismatch_action`	إجراء	الحكم عند الوصول إلى `geolocation_consecutive_mismatch_count` من حالات عدم التطابق المتتالية. القيمة الافتراضية هي المراجعة.
`geolocation_document_distance_action`	إجراء	الحكم عندما يبتعد موقع الجهاز عن عنوان المستند أكثر من `geolocation_document_distance_km`. يُرمَّز العنوان جغرافياً بدقة محدودة، لذا تُعد هذه الإشارة ضعيفة. القيمة الافتراضية هي `REVIEW`.
`geolocation_emulator_action`	إجراء	الحكم عندما يُبلغ التطبيق الذي شارك الموقع بأنه يعمل على محاكٍ. لا يستطيع المتصفح الإبلاغ عن ذلك. ما لم تكن القيمة «لا إجراء»، فإنه ينهي الخطوة عند تلك المحاولة، لأن إعادة الفحص لا يمكن أن تغيّر الجهاز. لا إجراء ما لم تُحدَّد القيمة أو تنص إحدى الإعدادات المسبقة على خلاف ذلك.
`geolocation_geofence_undetermined_action`	إجراء	الحكم عندما يتعذر تحديد ما إذا كان الموقع داخل السياج الجغرافي أو خارجه، لأن دائرة الدقة الخاصة به تصل إلى الحد. عدم اليقين لا يُعامَل أبداً على أنه خارج السياج. القيمة الافتراضية هي `REVIEW`.
`geolocation_geofencing_action`	إجراء	الحكم عندما يقع موقع الجهاز، ودائرة عدم اليقين الخاصة به كاملةً، خارج `geolocation_geofencing_by_country`. القيمة الافتراضية هي `DECLINE`.
`geolocation_integrity_missing_action`	إجراء	الحكم عندما يرسل عميل أصلي موقعاً دون token لإثبات الجهاز. القيمة الافتراضية هي لا إجراء. تُسجَّل عملاء الويب على أنها غير مدعومة لا مفقودة، لأن أي متصفح لا يستطيع إثبات الجهاز.
`geolocation_ip_distance_action`	إجراء	الحكم عندما تزيد المسافة بين موقع الجهاز وموقع IP الخاص بالجلسة عن `geolocation_ip_distance_km`، بعد طرح نصفي قطر عدم اليقين لكليهما. القيمة الافتراضية هي `REVIEW`.
`geolocation_low_accuracy_action`	إجراء	الحكم عندما لا تحقق أي محاولة الدقة المطلوبة: إما أن أفضل موقع له نصف قطر لعدم اليقين أوسع من `geolocation_max_accuracy_radius_m`، أو أنه لم يُبلغ عن نصف قطر أصلاً. الموقع الذي لا يحمل نصف قطر لا يُحسب أبداً على أنه يستوفي الحد. القيمة الافتراضية هي `REVIEW`.
`geolocation_mock_location_action`	إجراء	الحكم عندما يُبلغ نظام التشغيل بأن الموقع محاكى وليس مقاساً (مزوّد المواقع الوهمية في Android، أو المحاكاة البرمجية في iOS). القيمة الافتراضية هي `REVIEW`.
`geolocation_permission_denied_action`	إجراء	الحكم عندما يرفض المستخدم نافذة طلب الموقع أو يتجاهلها في كل محاولة مسموح بها. القيمة الافتراضية هي المراجعة: الرفض اختيار وليس إشارة احتيال.
`geolocation_proxy_action`	إجراء	الحكم عندما يمر الاتصال الذي شارك الموقع عبر وكيل مفتوح أو مجهول أو وكيل ترحيل خاص. لا إجراء ما لم تُحدَّد القيمة أو تنص إحدى الإعدادات المسبقة على خلاف ذلك.
`geolocation_stale_fix_action`	إجراء	الحكم عندما يكون الموقع قد قيس قبل وصوله إلى الخادم بأكثر من `geolocation_max_age_seconds`. القيمة الافتراضية هي `REVIEW`.
`geolocation_tor_action`	إجراء	الحكم عندما يكون الاتصال الذي شارك الموقع عقدة خروج Tor. لا إجراء ما لم تُحدَّد القيمة أو تنص إحدى الإعدادات المسبقة على خلاف ذلك.
`geolocation_unavailable_action`	إجراء	الحكم عندما لا يمكن الحصول على أي موقع: إما أن خدمات الموقع متوقفة أو مقيدة، أو أن نظام تحديد المواقع لم يُرجِع شيئاً، أو أن المحاولة انتهت مهلتها، أو أن المستخدم تخطى الخطوة، أو أن العميل قديم ولا يدعمها. القيمة الافتراضية هي `REVIEW`.
`geolocation_vpn_action`	إجراء	الحكم عندما يكون الاتصال الذي شارك الموقع VPN تجارياً. ما لم تكن القيمة «لا إجراء»، يُطلب من الشخص إيقافه والتحقق مرة أخرى ما دامت المحاولات متاحة. لا إجراء ما لم تُحدَّد القيمة أو تنص إحدى الإعدادات المسبقة على خلاف ذلك.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية. يمكنك استهداف حقول `geolocation.*` المذكورة في تقرير التحقق من الموقع.

أشكال المناطق

لكل عنصر في geolocation_areas معرّف id (من 1 إلى 64 حرفاً من A-Z a-z 0-9 _ -، وفريد في القائمة)، وlabel اختياري (حتى 80 حرفاً)، وtype قيمته allowed أو blocked، وkind يحدد شكل المنطقة.

`kind`	الحقول الإضافية	المعنى
`country`	`country` (ISO 3166-1 alpha-3)	دولة كاملة لها حدود منشورة.
`region`	`country`، `regions` (رموز ISO 3166-2 لتلك الدولة)	منطقة فرعية أو أكثر من دولة واحدة لها حدود منشورة.
`circle`	`center` (`latitude`، `longitude`)، `radius_km` (من 1 إلى 500)	كل نقطة تقع ضمن دائرة نصف قطرها المحدد حول المركز.
`polygon`	`points` (من 3 إلى 200 عنصر من `latitude`، `longitude`)	حلقة مغلقة لا تتقاطع حوافها مع بعضها ولا تتلامس.

تحتوي القائمة على 50 منطقة كحد أقصى، ويجب أن تتضمن منطقة allowed واحدة على الأقل عندما تكون is_geolocation_geofencing_enabled مساوية لـ true. لا يمكن إرسال geolocation_areas وgeolocation_geofencing_by_country معاً، وgeolocation_refusal_path: "end_session" يتطلب أن تكون geolocation_permission_denied_action مساوية لـ REVIEW أو DECLINE. ترفض API المنطقة التي لا يمكن أن تتطابق أبداً، مثل منطقة من دولة لا تتوفر لها حدود منشورة، ولا تحفظها. مثال:

{
  "feature": "GEOLOCATION",
  "config": {
    "geolocation_position_source": "device_and_ip",
    "geolocation_preset": "licensing",
    "geolocation_max_accuracy_radius_m": 250,
    "geolocation_max_attempts": 3,
    "is_geolocation_geofencing_enabled": true,
    "geolocation_areas": [
      { "id": "spain", "label": "Spain", "type": "allowed", "kind": "country", "country": "ESP" },
      { "id": "ceuta-melilla", "type": "blocked", "kind": "region", "country": "ESP", "regions": ["ES-CE", "ES-ML"] }
    ],
    "geolocation_ip_distance_km": 200,
    "geolocation_ip_distance_action": "REVIEW",
    "geolocation_vpn_action": "DECLINE"
  }
}

إثبات العنوان

قيمة الميزة: PROOF_OF_ADDRESS.

حقل الإعداد	النوع	الوصف
`poa_documents_allowed`	كائن	إعداد نوع مستند إثبات العنوان لكل رمز دولة ISO3. يجب تفعيل نوع مستند صالح واحد على الأقل.
`poa_languages_allowed`	كائن	يربط رمز اللغة وفق ISO 639-1 بالقيمة `0` أو `1`. يجب تفعيل لغة واحدة على الأقل.
`poa_name_or_address_mismatch_action`	إجراء	الإجراء عندما لا يطابق الاسم أو العنوان البيانات المتوقعة.
`poa_document_issues_action`	إجراء	الإجراء عندما يعاني المستند من مشكلات في الجودة أو الاستخراج.
`poa_max_attempts_exceeded_action`	إجراء مقيّد	الإجراء عندما يتجاوز المستخدم الحد المسموح به لمحاولات إعادة المحاولة. استخدم `DECLINE` أو `REVIEW`.
`poa_document_authenticity_action`	إجراء مقيّد	الإجراء عندما تفشل فحوص الأصالة. استخدم `DECLINE` أو `REVIEW`.
`poa_document_unproven_text_replacement_action`	إجراء	الإجراء عندما يتم مسح حقل نصي وإعادة كتابته بخط آخر، ولا يحتوي الملف على دليل يثبت ما إذا تغيّر محتواه (`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`).
`poa_unsupported_document_type_action`	إجراء	الإجراء عندما يكون نوع المستند غير مدعوم.
`poa_unsupported_language_action`	إجراء	الإجراء عندما تكون لغة المستند غير مدعومة.
`poa_issuer_not_identified_action`	إجراء	الإجراء عندما لا يتم التعرف على الجهة المُصدِرة للمستند.
`poa_issue_date_not_detected_action`	إجراء	الإجراء عندما يكون تاريخ الإصدار مفقودًا.
`poa_unparsable_or_invalid_address_action`	إجراء	الإجراء عندما يكون العنوان غير صالح أو تعذّر تحليله.
`address_validation_enabled`	قيمة منطقية	يتحقق من العنوان الذي تقرأه هذه الخطوة (المطبوع على إثبات العنوان؛ ولا يُتحقق إلا من الملف الذي اجتاز فحوص المستند) مقابل البيانات المرجعية للعناوين البريدية: يؤكد وجود العنوان ويوحّده بصيغة قياسية، ولا يربطه بأي شخص أبدًا. تكون النتيجة في كائن `address_validation` الخاص بالخطوة ضمن القرار. تُحتسب تكلفة قدرها $0.10 عن كل عنوان يتم التحقق منه؛ ولا تُحتسب أي تكلفة إذا تعذّر تنفيذ التحقق (`unavailable`). مُعطّل افتراضيًا.
`address_not_verified_action`	إجراء	الإجراء عندما لا تتمكن التحقق من العنوان من تأكيد العنوان حتى مستوى المبنى (`ADDRESS_NOT_VERIFIED`: `partially_verified` أو `not_verified`). ينطبق فقط عندما يكون `address_validation_enabled` مُفعّلًا. القيمة الافتراضية `NO_ACTION`، وهي تكتفي بتسجيل التحذير.
`poa_name_match_score_threshold`	عدد صحيح	حد مطابقة الاسم.
`poa_max_retry_attempts`	عدد صحيح	الحد الأقصى لمحاولات إعادة المحاولة، من `2` إلى `5`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

الاستبيانات

قيمة الميزة: QUESTIONNAIRE.

حقل الإعداد	النوع	الوصف
`questionnaire_uuid`	UUID	مطلوب. استخدم `questionnaire_id` الذي تُرجعه `POST /v3/questionnaires/`.
`review_questionnaire_manually`	قيمة منطقية	يرسل ردود الاستبيانات إلى المراجعة اليدوية.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية. يمكنك استهداف حقول `questionnaire.answers.<question_id>`.

سجل الشركات (KYB)

قيمة الميزة: KYB_REGISTRY.

حقل الإعداد	النوع	الوصف
`kyb_accepted_countries`	كائن	قائمة السماح القديمة لرموز الدول وفق ISO3 من أجل البحث في سجل الشركات. حلّت محلها `kyb_registry_countries_config`؛ ما زالت قابلة للقراءة، وما زالت تُشتق منها للتدفقات الحالية، لكنها لم تعد الطريقة المعتمدة لضبط التدفقات الجديدة.
`kyb_manual_company_action`	إجراء	الإجراء عندما تتطلب الشركة معالجة يدوية.
`kyb_registry_fields_config`	كائن	ظهور كل حقل وإلزامه في نموذج السجل ضمن التدفق المستضاف. انظر أدناه.
`kyb_registry_countries_config`	كائن	توجيه السجل لكل دولة، بالصيغة `{"<ISO2>": {"enabled": bool, "tier": "basic" \| "shareholders" \| "ubo"}}`. تُحدد كل دولة مفعّلة المستوى الذي تُحتسب تكلفته عند اختيار شركة (`basic` هو مستوى Lite)، ولا يمكن تفعيل إلا المستويات التي تُعلن endpoint الأسعار أنها متاحة لتلك الدولة. يجب تفعيل دولة واحدة على الأقل: يُرفض فحص السجل الذي لا يبحث في أي مكان. تُحتسب تكلفة الشركات المُدخلة يدويًا بشكل منفصل، ولا تستخدم هذا الإعداد.
`kyb_registry_monitoring_enabled`	قيمة منطقية	إبقاء سجل الشركة في المراقبة المستمرة بعد نتيجة Shareholders أو UBO: أي تغيير في الحالة أو المسؤولين أو الملكية أو العنوان يعيد الجلسة إلى المراجعة ويُطلق webhook. متاح فقط حيث يوفّر مزود السجل خدمة المراقبة. USD 2.00 لكل شركة سنويًا، ويمكن إلغاؤه في أي وقت. مُعطّل افتراضيًا.
`kyb_vat_invalid_action`	إجراء	الإجراء عندما يفشل رقم ضريبة القيمة المضافة للشركة في التحقق من خلال نظام VIES التابع للاتحاد الأوروبي. القيمة الافتراضية `REVIEW`.
`kyb_vat_unverified_action`	إجراء	الإجراء عندما يتعذّر التحقق من رقم ضريبة القيمة المضافة لأن خدمة VIES غير متاحة. القيمة الافتراضية `NO_ACTION`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

يربط kyb_registry_fields_config كل مفتاح حقل قابل للتهيئة بالكائن {"enabled": bool, "required": bool}. تعني enabled: false إخفاء الحقل، وتعني enabled: true, required: false عرضه كحقل اختياري، وتعني enabled: true, required: true جعله إلزاميًا عند الإرسال. تبقى company_name وcountry_code وregion دائمًا ظاهرة ومطلوبة، ولا يمكن تهيئتها. عندما يُحذف الكائن، أو يكون null أو {}، تُطبّق القيمة الافتراضية: يكون incorporation_date وحده مطلوبًا، وكل حقل آخر اختياري.

{
  "kyb_registry_fields_config": {
    "registration_number": { "enabled": true, "required": true },
    "incorporation_date": { "enabled": true, "required": true },
    "vat_number": { "enabled": true, "required": false },
    "control_scheme": { "enabled": false, "required": false }
  }
}

مفاتيح الحقول القابلة للتهيئة: registration_number، incorporation_date، legal_address، vat_number، alternative_names، tax_number، company_type، legal_entity_identifier، location_of_registration، nature_of_business، registered_capital_amount، registered_capital_currency، website، email، phone، control_scheme. انظر حقول نموذج السجل القابلة للتهيئة لمعرفة سلوك المستخدم النهائي، والتحقق من ضريبة القيمة المضافة والرقم الضريبي لمعرفة كيفية التحقق من vat_number وtax_number.

مستندات KYB

قيمة الميزة: KYB_DOCUMENTS.

حقل الإعداد	النوع	الوصف
`kyb_required_document_groups`	كائن أو مصفوفة	مطلوب. مجموعات مستندات KYB المطلوبة.
`kyb_document_subtype_config`	كائن	تفعيل النوع الفرعي لكل مستند وإعدادات العمر الخاصة به.
`kyb_document_tampering_action`	إجراء مقيّد	الإجراء عند اكتشاف التلاعب. استخدم `DECLINE` أو `REVIEW`.
`kyb_document_unproven_text_replacement_action`	إجراء	الإجراء عند تفريغ حقل نصي في مستند شركة وإعادة كتابته بخط آخر، ولا يحتوي الملف على دليل يثبت ما إذا تغيّر محتواه (`KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`).
`kyb_document_critical_mismatch_action`	إجراء مقيّد	الإجراء عند وجود تعارضات حرجة في المستندات. استخدم `DECLINE` أو `REVIEW`.
`kyb_document_non_critical_mismatch_action`	إجراء	الإجراء عند وجود تعارضات غير حرجة في المستندات.
`kyb_document_age_action`	إجراء	الإجراء عند عدم استيفاء قواعد عمر المستند.
`kyb_document_max_retry_attempts`	عدد صحيح	حد إعادة المحاولة لمستندات KYB.
`kyb_document_max_attempts_exceeded_action`	إجراء مقيّد	الإجراء عند تجاوز الحد الأقصى للمحاولات. استخدم `DECLINE` أو `REVIEW`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

الأشخاص الرئيسيون في KYB

قيمة الميزة: KYB_KEY_PEOPLE.

حقل الإعداد	النوع	الوصف
`kyb_ubo_ownership_threshold`	عدد صحيح	حد ملكية المستفيد الحقيقي (UBO)، من `0` إلى `100`.
`kyb_shareholder_ownership_threshold`	عدد صحيح	حد ملكية المساهم، من `0` إلى `100`. لا يمكن أن يكون أعلى من `kyb_ubo_ownership_threshold`.
`kyb_key_people_ownership_required`	قيمة منطقية	يتطلب إدخال نسبة ملكية لكل شخص رئيسي مُقدَّم. يُفرض عند الإرسال ويُعرض في صفحة التحقق المستضافة، التي تُظهر الحقل كحقل مطلوب. القيمة الافتراضية `false`.
`kyb_require_ubo_kyc`	قيمة منطقية	يتطلب من المستفيدين الحقيقيين إكمال سير عمل التحقق من الشخص.
`kyb_ubo_verification_workflow`	UUID	مطلوب عندما تكون قيمة `kyb_require_ubo_kyc` هي `true`. يجب أن يشير إلى سير عمل غير KYB في نفس التطبيق.
`kyb_require_officer_kyc`	قيمة منطقية	يتطلب من المسؤولين إكمال التحقق من الشخص.
`kyb_shareholder_verification_workflow`	UUID	سير عمل التحقق من الشخص للمساهمين.
`kyb_officer_verification_workflow`	UUID	سير عمل التحقق من الشخص للمسؤولين.
`kyb_require_corporate_ubo_kyb`	قيمة منطقية	يتطلب من المستفيدين الحقيقيين من الشركات إكمال KYB.
`kyb_corporate_ubo_verification_workflow`	UUID	مطلوب عندما تكون قيمة `kyb_require_corporate_ubo_kyb` هي `true`. يجب أن يشير إلى سير عمل KYB في نفس التطبيق.
`kyb_reject_if_ubo_rejected`	قيمة منطقية	يرفض الشركة عندما يُرفض التحقق المطلوب من المستفيد الحقيقي.
`kyb_wait_for_all_ubos`	قيمة منطقية	ينتظر اكتمال جميع عمليات التحقق المطلوبة من المستفيدين الحقيقيين قبل اتخاذ القرار في جلسة KYB.
`kyb_role_config`	كائن أو مصفوفة	إعدادات لكل دور. يجب أن يتضمن كل دور KYC مطلوب `verification_workflow`.
`kyb_reuse_verified_individuals`	قيمة منطقية	يعيد استخدام الأفراد الذين تم التحقق منهم متى أمكن ذلك.
`kyb_notify_parties_by_email`	قيمة منطقية	يرسل إشعارات بالبريد الإلكتروني إلى الأشخاص الرئيسيين المدعوين.
`kyb_key_people_company_fields`	كائن	تفاصيل الشركة التي تُجمع لشخص رئيسي من نوع CORPORATE. بنفس شكل قائمة الواصفات وبنفس القواعد الواردة في `kyb_key_people_person_fields`. الشكل: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`.
`kyb_key_people_document_mismatch_action`	إجراء	الحكم عندما لا يتوافق مستند الشخص الرئيسي مع التفاصيل المصرّح بها له.
`kyb_key_people_person_fields`	كائن	التفاصيل الشخصية التي تُجمع لكل شخص رئيسي فردي، على شكل قائمة مرتبة من واصفات الحقول (وليست خريطة). `key` مطلوب ولا يكون فارغاً. `type` يجب أن يكون أحد القيم text أو number أو date أو phone أو email. تشير `custom` إلى حقل أضافه العميل بدلاً من الحقول المدمجة. الشكل: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`.
`kyb_key_people_prefill_from_registry`	قيمة منطقية	يملأ قائمة الأشخاص الرئيسيين مسبقاً من نتيجة سجل الشركات، ليؤكد العميل المعلومات ويصححها بدلاً من كتابة كل مسؤول ومساهم يدوياً.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية.

Document AI

قيمة الميزة: DOCUMENT_AI. يطلب من المستخدم مستنداً واحداً أو أكثر، ويستخرج الحقول المسمّاة التي تحددها باستخدام نموذج رؤية. يصبح كل حقل مُعدّ قيمة قابلة للتفرع document_ai.<key>، وتكون نتيجة الخطوة في document_ai.status.

حقل الإعداد	النوع	الوصف
`document_ai_documents`	مصفوفة	مطلوب. المستندات المراد طلبها (`3` على الأكثر). كل عنصر كائن مستند (انظر أدناه).
`document_ai_unreadable_document_action`	إجراء	الإجراء عند تعذّر قراءة المستند أو عدم إمكانية استخراج أي بيانات منه.
`document_ai_missing_required_fields_action`	إجراء	الإجراء عند تعذّر استخراج حقل مطلوب.
`document_ai_document_tampering_action`	إجراء مقيّد	الإجراء عند ظهور علامات تلاعب في المستند. استخدم `DECLINE` أو `REVIEW`.
`document_ai_name_mismatch_action`	إجراء	الإجراء عند عدم تطابق الاسم الكامل المستخرج مع الهوية المتحقق منها. يتطلب حقلاً مُعلّماً بـ `is_full_name`.
`document_ai_unsupported_file_action`	إجراء	الإجراء عند عدم دعم نوع الملف المرفوع.
`document_ai_max_attempts_exceeded_action`	إجراء مقيّد	الإجراء عند تجاوز المستخدم محاولات إعادة المحاولة المسموح بها. استخدم `DECLINE` أو `REVIEW`.
`document_ai_name_match_score_threshold`	عدد صحيح	الحد الأدنى للدرجة (من `0`–`100`) لكي يتطابق الاسم الكامل المستخرج مع الهوية المتحقق منها. إذا كانت الدرجة أقل منه، يُطبّق `document_ai_name_mismatch_action`.
`document_ai_max_retry_attempts`	عدد صحيح	حد إعادة المحاولة، من `2` إلى `5`.
`status_rules`	مصفوفة	قواعد حالة مخصصة اختيارية. يمكنك استهداف حقول `document_ai.<key>`.

كل عنصر في document_ai_documents هو مستند:

حقل المستند	النوع	الوصف
`document_key`	نص	مطلوب. معرّف ثابت للمستند، فريد ضمن الخطوة.
`title`	نص	مطلوب. العنوان الذي يظهر للمستخدم.
`description`	نص	مطلوب. تعليمات تظهر للمستخدم حول ما يجب رفعه.
`title_i18n`	كائن	اختياري. رمز الإعدادات المحلية للعنوان المترجم (مثلاً `{ "es": "Comprobante de fondos" }`).
`description_i18n`	كائن	اختياري. رمز الإعدادات المحلية للوصف المترجم.
`fields`	مصفوفة	مطلوب. الحقول المراد استخراجها (حقل واحد على الأقل). يجب أن تكون مفاتيح الحقول فريدة ضمن المستند.

كل عنصر في fields الخاص بالمستند هو حقل:

الحقل	النوع	الوصف
`key`	نص	مطلوب. مفتاح JSON ثابت للقيمة المستخرجة، فريد ضمن المستند. استخدمه للتفرع بالشكل `document_ai.<key>`.
`name`	نص	مطلوب. تسمية الحقل المفهومة للبشر.
`name_i18n`	كائن	اختياري. رمز الإعدادات المحلية إلى اسم الحقل المترجم.
`instruction`	نص	اختياري. تعليمة تخبر النموذج بدقة بما يجب استخراجه لهذا الحقل.
`type`	نص	نوع الحقل: `text` أو `number` أو `date`. القيمة الافتراضية `text`.
`required`	قيمة منطقية	هل يجب أن يكون الحقل موجوداً. القيمة الافتراضية `false`. عند ضبطها على `true` وكانت القيمة مفقودة، يُطبّق `document_ai_missing_required_fields_action`.
`is_full_name`	قيمة منطقية	اختياري، والقيمة الافتراضية `false`. يحدد الحقل الذي تكون قيمته الاسم الكامل لصاحب المستند، ويُقارن بالهوية المتحقق منها (الاسم الوارد في التحقق من الهوية، أو البيانات المتوقعة للجلسة). يمكن ضبط حقل واحد كحد أقصى لكل مستند على `true`. هذا الحقل غير إلزامي، فقد لا يحدد المستند أي حقل، وفي هذه الحالة لا تُجرى أي مقارنة للأسماء لذلك المستند. لا يمكن أن يكون الاسم الكامل إلا من حقول `text`.

مثال:

{
  "feature": "DOCUMENT_AI",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "title_i18n": { "es": "Comprobante de fondos" },
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": false
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW",
    "document_ai_name_match_score_threshold": 80
  }
}

التوقيع الإلكتروني

قيمة الميزة: SIGNATURE. تتيح للشخص المتحقَّق منه، أو للأشخاص الرئيسيين في الشركة، التوقيع على المستندات، بالمستوى البسيط (الافتراضي) أو المتقدم (AES). ضعها بعد الخطوات التي تتحقق من الموقِّع: التحقق من الهوية، والتحقق من البريد الإلكتروني أو رقم الهاتف للحصول على الرمز. راجع التوقيع الإلكتروني.

حقل الإعداد	النوع	الوصف
`signature_documents`	array	المستندات المرفوعة إلى سير العمل هذا في الواجهة، بالترتيب الذي يراه الموقِّع، بالصيغة `[{"uuid", "title", "file_name", "pages", "size_bytes"}]`. يُقرأ من هذه البيانات قيم `uuid` وترتيبها فقط، أما الباقي فيُؤخذ من الملفات المخزَّنة. الحد الأقصى 20 مستنداً و50 MB في المجموع. الافتراضي `[]`.
`signature_documents_source`	string	مصدر المستندات: `workflow` (الافتراضي)، أو `session` (`sign.documents` في إنشاء جلسة)، أو `both` (مستندات سير العمل أولاً).
`signature_require_read_to_end`	boolean	يجب على الموقِّع الوصول إلى نهاية كل مستند لا يحتوي على حقول قبل الموافقة عليه. الافتراضي `true`.
`signature_consent_per_document`	boolean	يوافق الموقِّع على كل مستند لا يحتوي على حقول على حدة. بالنسبة للمستندات التي تحتوي على حقول، تحلّ الحقول الإرشادية والموافقة النهائية محل هذه الموافقة. الافتراضي `true`.
`signature_signer`	string	من يوقِّع: `verified_person` (الافتراضي، KYC)، أو بالنسبة لـ KYB إما `legal_representative` (الأشخاص الرئيسيون الذين لديهم الدور `representative` أو `authorized_signatory`) أو `key_people` (كل شخص رئيسي لديه جلسة KYC).
`signature_level`	string	`simple` (الافتراضي): لا يتطلب التحقق من الهوية أو التحقق من البريد الإلكتروني أو التحقق من رقم الهاتف أو رمزاً، إذ يكتب الموقِّع اسمه ويوقِّع عبر رابط الجلسة. `aes`: يتطلب عملية تحقق من الهوية مقبولة، وبريداً إلكترونياً أو هاتفاً متحققاً منه، ورمزاً لمرة واحدة. يُرفض `simple` للموقِّعين من نوع `legal_representative` و`key_people` مع الرمز `signature_simple_requires_verified_person`. طالما أن `signature_availability.aes` بقيمة `false` في سير العمل، فإن حفظ خطوة `aes` جديدة يعيد `400` مع `aes_not_available`. `qes` قادمة قريباً، وحفظها يعيد `400` مع `qes_not_available`.
`signature_format`	string	`pades` (الافتراضي). يُرفض `xades` و`cades` مع AES برمز الخطأ `signature_format_not_supported`.
`signature_otp_channel`	string	الوجهة التي يُرسل إليها الرمز لمرة واحدة: `email` (الافتراضي) أو `sms`. يُرسل فقط إلى جهة اتصال متحقق منها سابقاً في الجلسة.
`signature_email_signed_copy`	boolean	إرسال نسخة من المستندات الموقَّعة إلى بريد الموقِّع. يتطلب بريداً إلكترونياً متحققاً منه. الافتراضي `true`.
`signature_evidence_page`	boolean	إلحاق صفحة الأدلة بكل ملف PDF موقَّع. الافتراضي `true`.
`signature_link_validity_days`	integer	مدة صلاحية رابط التوقيع، من `1` إلى `30` يوماً من إنشاء الجلسة. الافتراضي `7`.
`signature_declined_action`	action	القرار عندما يرفض الموقِّع. لا تُحتسب أي رسوم. الافتراضي `REVIEW`.
`signature_otp_failed_action`	action	القرار بعد إدخال 3 رموز خاطئة أو بعد طلب أكثر من 5 رموز. الافتراضي `DECLINE`.
`signature_name_mismatch_action`	action	القرار عندما لا يتطابق الاسم المُصرَّح به للشخص الرئيسي مع اسمه المتحقَّق منه. الافتراضي `DECLINE`.
`signature_identity_not_verified_action`	action	القرار عندما لا يملك الموقِّع دليل هوية مقبول. الافتراضي `DECLINE`.
`signature_document_changed_action`	action	القرار عندما لا يعود المستند يطابق قيمة SHA-256 المسجَّلة عند عرضه. الافتراضي `DECLINE`.
`status_rules`	array	قواعد حالة مخصصة اختيارية. يمكنك استهداف `signature.status` و`signature.level` و`signature.format`.

تُوضع الحقول الموجودة في مستندات سير العمل في محرر القوالب في الواجهة. أما مستندات الجلسة، فأرسل حقولها في sign.documents[].fields، وأرسل قيم حقول api.<key> في sign.field_values. راجع إنشاء جلسة. مثال للمستندات المُرسلة مع كل جلسة:

{
  "feature": "SIGNATURE",
  "config": {
    "signature_documents_source": "session",
    "signature_signer": "verified_person",
    "signature_level": "aes",
    "signature_otp_channel": "email",
    "signature_link_validity_days": 14,
    "signature_declined_action": "REVIEW"
  }
}

​قواعد التحقق

​قواعد الحالة المشتركة

​المقارنة مع خطوة محددة

​OCR / التحقق من الهوية

​الطرق حسب الدولة

​NFC / جواز السفر الإلكتروني

​كشف الحيوية

​مطابقة الوجه

​تقدير العمر

​التحقق من رقم الهاتف

​التحقق من البريد الإلكتروني

​التحقق من قواعد البيانات

​التحقق من الحساب البنكي

​ربط الحساب

​عندما لا يستطيع المستخدم التحقق

​مقارنة صاحب الحساب

​فحص الحساب

​البيانات المالية

​ما يُخزَّن

​إجراءات القرار

​ضوابط إضافية

​AML

​فحص كيان استخرجته خطوة Document AI

​تحليل الجهاز وعنوان IP

​التحقق من الموقع

​أشكال المناطق

​إثبات العنوان

​الاستبيانات

​سجل الشركات (KYB)

​مستندات KYB

​الأشخاص الرئيسيون في KYB

​Document AI

​التوقيع الإلكتروني

قواعد التحقق

قواعد الحالة المشتركة

المقارنة مع خطوة محددة

OCR / التحقق من الهوية

الطرق حسب الدولة

NFC / جواز السفر الإلكتروني

كشف الحيوية

مطابقة الوجه

تقدير العمر

التحقق من رقم الهاتف

التحقق من البريد الإلكتروني

التحقق من قواعد البيانات

التحقق من الحساب البنكي

ربط الحساب

عندما لا يستطيع المستخدم التحقق

مقارنة صاحب الحساب

فحص الحساب

البيانات المالية

ما يُخزَّن

إجراءات القرار

ضوابط إضافية

AML

فحص كيان استخرجته خطوة Document AI

تحليل الجهاز وعنوان IP

التحقق من الموقع

أشكال المناطق

إثبات العنوان

الاستبيانات

سجل الشركات (KYB)

مستندات KYB

الأشخاص الرئيسيون في KYB

Document AI

التوقيع الإلكتروني