ابدأ الآن
التكامل / SDKs
التحقق من المستخدمين
التحقق من الشركات
مراقبة المعاملات
سجل التغييراتنظرة عامة
يتبع كل تقرير خاص بميزة شكل المُسلسِل V3 المعرَّف فيservice-didit-verification. يظهر الكائن نفسه في ثلاثة مواضع، لذلك فإن المخطط الموجود هنا هو المصدر المرجعي الوحيد لجميع هذه المواضع:
GET /v3/session/{sessionId}/decision/: تُعاد كل ميزة في مصفوفة بصيغة الجمع (id_verifications[]،nfc_verifications[]،liveness_checks[]،face_matches[]،poa_verifications[]،phone_verifications[]،email_verifications[]،aml_screenings[]،ip_analyses[]،database_validations[]،questionnaire_responses[]،signatures[]،bank_verifications[](راجع طرق التحقق البنكي)، والمكافئات الخاصة بـ KYB وهيregistry_checks[]وdocument_verifications[]وkey_people_checks[]).- حمولات webhook (
status.updatedوdata.updated): الشكل نفسه داخل الغلافdecision. - واجهات برمجة التطبيقات المستقلة: تعيد الاستجابات ككائن واحد (البحث بالوجه وتقدير العمر والمصادقة البيومترية) وتستخدم مجموعة الحقول نفسها.
قدّم V3 سير العمل متعدد المثيلات: يحمل كل كائن ميزة الحقل
node_id الذي يربط التقرير بعقدة الرسم البياني لسير العمل التي أنتجته. أما endpoints V2 (بصيغة المفرد، مثل kyc وface وaml)، فما زالت متوافقة مع الإصدارات السابقة، لكنها تعيد أول مثيل فقط.الحقول المشتركة
يعرض كل كائن تقرير الحقول التالية:| الحقل | النوع | الوصف |
|---|---|---|
status | نص | حالة دورة الحياة على مستوى الميزة، وهي إحدى القيم الواردة في تعداد الحالة. المصدر: common/config/choices.py:FeatureStatusChoices (الأسطر 343-348). يستخدم الحقل status على المستوى الأعلى للجلسة الأم تعداد الجلسة الأوسع StatusChoices (الأسطر 106-117). |
node_id | نص | null | معرّف عقدة الرسم البياني لسير العمل. يُملأ في سير العمل متعدد المثيلات في V3، ويكون null في الجلسات القديمة ذات الميزة الواحدة. |
warnings | مصفوفة من كائنات التحذير | إشارات المخاطر المصفّاة حسب هذه الميزة وnode_id. تُعاد بواسطة Session.get_logs(...) (sessions/models/session.py:1611). |
portrait_image وfront_image وdocument_file و…) روابط موقعة مسبقاً بنافذة صلاحية محدودة، لذا نزّلها فوراً بدلاً من تخزين الرابط. تُعرض الأمثلة بالصيغة https://<media-host>/....
كائن التحذير
يُعاد في كل مصفوفةwarnings[]. المخطط من logs/serializers/log.py:8-65 (LogV3Serializer).
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
feature | نص (تعداد) | لا | الميزة التي أصدرت التحذير. القيم من LogWarningChoices (common/config/choices.py:190-204): ID_VERIFICATION، NFC، LIVENESS، FACEMATCH، PROOF_OF_ADDRESS، PHONE، EMAIL، AML، LOCATION، DATABASE_VALIDATION، QUESTIONNAIRE، KYB_REGISTRY، KYB_DOCUMENTS، KYB_KEY_PEOPLE. | "ID_VERIFICATION" |
risk | نص | لا | رمز مخاطرة ثابت (مثل DOCUMENT_EXPIRED وLOW_LIVENESS_SCORE). القيم من logs/choices.py:RiskChoices. يُستخدم مفتاحاً للوصول إلى جداول الأوصاف. | "DOCUMENT_EXPIRED" |
additional_data | كائن | null | نعم | سياق خاص بالمخاطرة (مثل عتبات الدرجات والحقول المطابَقة). يختلف شكله باختلاف رمز المخاطرة. | { "score": 42.1, "threshold": 70 } |
log_type | نص (تعداد) | لا | إحدى القيم error أو warning أو information. من LogTypeChoices (common/config/choices.py:207-210). | "error" |
short_description | نص | لا | تسمية مقروءة للمخاطرة. من logs/choices.py:RISK_SHORT_DESCRIPTIONS. | "Document expired" |
long_description | نص | لا | شرح مقروء أطول، مناسب للعرض على المستخدم النهائي. من logs/choices.py:RISK_LONG_DESCRIPTIONS. | "The document's expiration date has passed, rendering it no longer valid for use." |
node_id | نص | null | نعم | عقدة الرسم البياني لسير العمل التي رُفع عليها التحذير. تكون null في سجلات V2 القديمة التي لا تحمل node_id. | "first_id_verification" |
{
"feature": "ID_VERIFICATION",
"risk": "DOCUMENT_EXPIRED",
"additional_data": null,
"log_type": "error",
"short_description": "Document expired",
"long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
"node_id": "first_id_verification"
}
كائنات التقارير
تتناول بقية الأقسام كل كائن تقرير خاص بكل ميزة على حدة. نص عنوان H3 ثابت عمدًا حتى تتمكن الوثائق الأخرى من إنشاء روابط عميقة إليه مباشرةً.التحقق من الهوية
تُعاد لكل مستند KYC/الهوية يقدّمه المستخدم. يظهر كعنصر فيid_verifications[] ضمن GET /v3/session/{sessionId}/decision/ وداخل الحقل kyc في استجابات الإصدار V2. المصدر: kyc/serializers/kyc.py:383-414 (IDVerificationV3Serializer، ويمتد من IDVerificationV2Serializer في kyc/serializers/kyc.py:320-380).
| الحقل | النوع | قابل للقيمة الفارغة | الوصف | المثال |
|---|---|---|---|---|
status | نص | لا | راجع تعداد الحالات. | "Approved" |
document_type | نص | نعم | فئة المستند بصيغة مقروءة (Passport، Identity Card، Driver's License، Residence Permit، Health Insurance Card، Tax Card، Social Security Card، Work Permit، Visa، Public Service Card، Birth Certificate، Firearm License، Other). المصدر: DOC_TYPE_MAPPING (common/config/choices.py:1275-1289). | "Passport" |
document_subtype | نص | نعم | رمز النوع الفرعي للمستند من سجل مستندات Didit، ومُصفّى حسب ما تقبله إعدادات المستندات في سير العمل. تتضمن المستندات الخاصة بمنطقة معينة اسم المنطقة. قائمة الرموز الكاملة: أنواع المستندات الفرعية. | "QUEENSLAND_DRIVER_LICENSE_GENERIC" |
document_number | نص | نعم | رقم المستند المستخرج عبر OCR. | "AB1234567" |
personal_number | نص | نعم | المعرّف الشخصي أو الوطني المستخرج عبر OCR. | "99999999R" |
portrait_image | نص (URL) | نعم | رابط موقَّع مسبقًا لقصاصة الوجه. | "https://<media-host>/.../portrait.jpg?..." |
front_image | نص (URL) | نعم | رابط موقَّع مسبقًا للوجه الأمامي المنظّف للمستند. | "https://<media-host>/.../front.jpg?..." |
front_video | نص (URL) | نعم | رابط موقَّع مسبقًا لفيديو التقاط الوجه الأمامي (عند توفره). | "https://<media-host>/.../front.mp4?..." |
back_image | نص (URL) | نعم | رابط موقَّع مسبقًا للوجه الخلفي المنظّف للمستند. | "https://<media-host>/.../back.jpg?..." |
back_video | نص (URL) | نعم | رابط موقَّع مسبقًا لفيديو التقاط الوجه الخلفي. | null |
full_front_image | نص (URL) | نعم | التقاط الوجه الأمامي كاملًا دون قص (بالإطار الكامل). | "https://<media-host>/.../full_front.jpg?..." |
full_back_image | نص (URL) | نعم | التقاط الوجه الخلفي كاملًا دون قص (بالإطار الكامل). | null |
front_image_camera_front | نص (URL) | نعم | صورة من الكاميرا الأمامية التُقطت في الوقت نفسه مع الوجه الأمامي للمستند. | null |
back_image_camera_front | نص (URL) | نعم | صورة من الكاميرا الأمامية التُقطت في الوقت نفسه مع الوجه الخلفي للمستند. | null |
front_image_camera_front_face_match_score | عدد عشري (0-100) | نعم | درجة التطابق بين صورة الوجه على المستند ولقطة الكاميرا الأمامية. | null |
back_image_camera_front_face_match_score | عدد عشري (0-100) | نعم | مثل الحقل أعلاه، ولكن للالتقاط الخلفي. | null |
document_selfie_face_matches | مصفوفة | نعم | جلسات سابقة أو إدخالات من قائمة حظر الوجوه تطابق صورة السيلفي المُلتقطة أثناء التقاط المستند. الصيغة مطابقة لعناصر liveness_checks[].matches. القيمة null إذا لم يُجرَ البحث، والقيمة [] إذا لم يتطابق شيء. | null |
front_image_quality_score | كائن | نعم | مقاييس جودة الصورة الأمامية: درجات من 0 إلى 100 (focus_score، brightness_score، resolution_score، overall_score)، إضافةً إلى brightness_issue (ok، too_dark، too_bright) وis_document_fully_visible (قيمة منطقية). | { "focus_score": 91.0, "overall_score": 88.5 } |
back_image_quality_score | كائن | نعم | البنية نفسها المستخدمة في front_image_quality_score. | null |
date_of_birth | نص (YYYY-MM-DD) | نعم | تاريخ الميلاد المستخرج عبر OCR. | "1990-05-12" |
age | عدد صحيح | نعم | العمر المحسوب بالسنوات وقت الاستخراج. | 35 |
expiration_date | نص (YYYY-MM-DD) | نعم | تاريخ انتهاء صلاحية المستند. | "2032-05-11" |
date_of_issue | نص (YYYY-MM-DD) | نعم | تاريخ إصدار المستند. | "2022-05-11" |
issuing_state | نص (ISO 3166-1 alpha-3) | نعم | رمز الدولة المُصدِرة. | "ESP" |
issuing_state_name | نص | نعم | اسم الدولة المُصدِرة مترجمًا إلى لغة العرض. | "Spain" |
first_name | نص | نعم | الاسم أو الأسماء الأولى المستخرجة عبر OCR. | "María" |
last_name | نص | نعم | اسم العائلة أو الأسماء العائلية المستخرجة عبر OCR. | "García López" |
full_name | نص | نعم | الاسم الكامل بعد التوحيد (يوفره المزوّد). | "María García López" |
gender | نص | نعم | القيمة M أو F أو قيمة أخرى يوفرها المزوّد. | "F" |
address | نص | نعم | سطر العنوان الخام المستخرج عبر OCR. | "Calle Mayor 1, 28001 Madrid" |
formatted_address | نص | نعم | العنوان بعد تحديد موقعه الجغرافي وتنسيقه (عند إمكانية تحليله). | "Calle Mayor 1, 28001 Madrid, Spain" |
parsed_address | كائن | نعم | العنوان المنظّم بعد تحديد موقعه الجغرافي: street_1، street_2، city، region، country، postal_code، address_type، formatted_address، document_location ({latitude, longitude})، raw_results، is_best_match. المصدر: kyc/utils/address.py:147-197. | { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" } |
place_of_birth | نص | نعم | مكان الميلاد المستخرج عبر OCR. | "Madrid" |
marital_status | نص | نعم | عند إمكانية استخراجها. | null |
nationality | نص (ISO 3166-1 alpha-3) | نعم | الجنسية المستخرجة عبر OCR. | "ESP" |
extra_fields | كائن | نعم | حقول خاصة بنوع المستند لا يغطيها المخطط الأساسي (مثل فئات رخصة القيادة). | { "DL Class": "B" } |
mrz | كائن | نعم | حقول MRZ المحللة عند وجودها (document_number، birth_date، expiry_date، surname، given_names، …). | { "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" } |
extra_files | مصفوفة من النصوص (URL) | لا | روابط موقَّعة مسبقًا لأي ملفات إضافية مرفوعة. | [] |
matches | مصفوفة من الكائنات | لا | تطابقات المستندات عبر الجلسات. كل عنصر: { session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }. الحقل front_image_url رابط موقَّع مسبقًا. | [] |
verification_method | string | لا | الطريقة التي أنتجت هذا الصف من طريقة التحقق من الهوية: document أو id_lookup أو wallet. تكون القيمة دائماً document للمستند المصوَّر، بما في ذلك كل جلسة أُنشئت قبل توفر الطرق الأخرى. | "id_lookup" |
assurance | string | لا | مستوى الضمان المشتق من verification_method: documentary أو data_match أو cryptographic. | "data_match" |
wallet_provider | string | null | نعم | معرّف المحفظة في الكتالوج عندما تُنتج محفظة هذا الصف (mitid, bankid_se, itsme, …). تكون null في غير ذلك. | "mitid" |
fallback_from | object | null | نعم | سبب إنهاء طريقة لا تعتمد على المستند لخطوة التحقق من الهوية: { method, reason, action }. يُعيَّن عند فشل استعلام عن المصدر أو تسجيل دخول عبر محفظة: في الصف المرفوض عندما كان مفتاح الدولة مضبوطاً على decline (action: "decline")، وفي التحقق من المستند الذي يكمل به المستخدم عندما كان fallback_to_document (action: "fallback_to_document"). تكون null عندما لا يُسجَّل أي فشل سابق لطريقة غير المستند. | { "method": "id_lookup", "reason": "no_match", "action": "decline" } |
id_lookup | object | null | نعم | أدلة المصدر، وتظهر فقط عندما يكون verification_method هو id_lookup: source (المصدر الدقيق الذي جرى الاستعلام عنه، وهو سجل حكومي في معظم الدول، أو ملف مكتب ائتمان أو سجلات سكنية في بعض الدول)، وchecked_at، وattempts، وmax_attempts، وoutcome (match, partial_match, no_match, provider_error, format_rejected)، وcomparison[] ({ field, label, provided, record, result }؛ إذ إن field هو أحد القيم identification_number أو full_name أو date_of_birth أو address، وresult هو match أو partial أو no_match؛ وقد تتضمن الإصدارات السابقة صفاً من نوع provider يحمل error)، وsource_errors[] (في بيئة التجهيز الحالية: تشخيصات منفصلة للمصادر؛ تحقق من طرحها في الإنتاج)، وregistry_portrait (رابط موقّع مسبقاً، فقط للمصادر التي تعيده)، وface_match_score. | انظر أدناه |
wallet_verification | object | null | نعم | أدلة الاعتماد، وتظهر فقط عندما يكون verification_method هو wallet: provider وprovider_name وissuing_authority وissuing_country وcredential_type وlevel_of_assurance (low, substantial, high) وverified_at وsignature_valid وattributes (ما شاركته المحفظة) وportrait (رابط موقّع مسبقاً عندما تشارك المحفظة صورة) وface_match_score. | انظر أدناه |
document_liveness | object | null | نعم | درجات حيوية المستند لكل نوع احتيال (portrait_replace, printed_copy, screen_replay)، وتُعرض سواء أُطلق تحذير أم لا. لكل نوع: score (من 0 إلى 100، وكلما ارتفعت القيمة زاد احتمال أن يكون المستند أصلياً؛ والقيمة الأقل هي التي استند إليها القرار)، وfront، وback، وdecline_threshold، وreview_threshold، وbucket (approve, review, decline, أو null). تُحفظ العتبات والتصنيف وقت التقييم، وتكون الثلاثة جميعها null عندما تتعذر أدلة التقييم التاريخية، مع بقاء الدرجات المخزنة ظاهرة. تكون null عندما لم يُجرَ الفحص. انظر درجات حيوية المستند. للإصدار V3 فقط. | { "portrait_replace": { "score": 96.46, "bucket": "approve" } } |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_id_verification" |
warnings | array | لا | انظر كائن التحذير. | [] |
region | string | نعم | المنطقة أو الولاية في دولة الإصدار، عندما يحدّدها المستند. | "CA" |
extracted_data | object | نعم | لقطة من البيانات المستخرجة من المستند التي عُرضت على الشخص لمراجعتها، وتُحفظ بجانب القيم المؤكدة لتتمكن من مقارنتها. تكون null عندما لم يُطلب من الشخص المراجعة. | |
barcodes | array of objects | لا | بيانات مقروءة من باركودات المستند، إدخال واحد لكل باركود يتضمن type وposition وdata وdata_raw وside. تكون [] عندما لا توجد باركودات. | [] |
{
"status": "Approved",
"document_type": "Passport",
"document_subtype": "PASSPORT_GENERIC",
"document_number": "AB1234567",
"personal_number": "99999999R",
"portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
"front_image": "https://<media-host>/.../front.jpg?signature=...",
"front_video": null,
"back_image": "https://<media-host>/.../back.jpg?signature=...",
"back_video": null,
"full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
"full_back_image": null,
"front_image_camera_front": null,
"back_image_camera_front": null,
"front_image_camera_front_face_match_score": null,
"back_image_camera_front_face_match_score": null,
"front_image_quality_score": {
"focus_score": 91.0,
"brightness_score": 88.0,
"brightness_issue": "ok",
"is_document_fully_visible": true,
"resolution_score": 95.0,
"overall_score": 88.5
},
"back_image_quality_score": null,
"date_of_birth": "1990-05-12",
"age": 35,
"expiration_date": "2032-05-11",
"date_of_issue": "2022-05-11",
"issuing_state": "ESP",
"issuing_state_name": "Spain",
"first_name": "María",
"last_name": "García López",
"full_name": "María García López",
"gender": "F",
"address": "Calle Mayor 1, 28001 Madrid",
"formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
"parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" },
"place_of_birth": "Madrid",
"marital_status": null,
"nationality": "ESP",
"extra_fields": {},
"mrz": {
"document_number": "AB1234567",
"surname": "GARCIA",
"given_names": "MARIA",
"birth_date": "900512",
"expiry_date": "320511"
},
"extra_files": [],
"matches": [],
"node_id": "first_id_verification",
"verification_method": "document",
"assurance": "documentary",
"wallet_provider": null,
"fallback_from": null,
"id_lookup": null,
"wallet_verification": null,
"document_liveness": {
"portrait_replace": {
"score": 96.46,
"front": 96.46,
"back": 98.2,
"decline_threshold": 35,
"review_threshold": 70,
"bucket": "approve"
},
"printed_copy": {
"score": 91.2,
"front": 91.2,
"back": 93.7,
"decline_threshold": 35,
"review_threshold": 77,
"bucket": "approve"
},
"screen_replay": {
"score": 99.9,
"front": 99.9,
"back": 99.5,
"decline_threshold": 30,
"review_threshold": 70,
"bucket": "approve"
}
},
"warnings": []
}
null.
{
"status": "Approved",
"issuing_state": "ZAF",
"first_name": "Thabo",
"last_name": "Mokoena",
"full_name": "Thabo Mokoena",
"date_of_birth": "1991-06-15",
"personal_number": "9106155043088",
"node_id": "first_id_verification",
"verification_method": "id_lookup",
"assurance": "data_match",
"wallet_provider": null,
"fallback_from": null,
"id_lookup": {
"source": "Department of Home Affairs",
"checked_at": "2026-09-04T09:12:44Z",
"attempts": 1,
"max_attempts": 2,
"outcome": "match",
"comparison": [
{ "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
{ "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
{ "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
],
"registry_portrait": "https://<media-host>/.../registry_portrait.jpg?signature=...",
"face_match_score": 96.4
},
"wallet_verification": null,
"warnings": []
}
{
"status": "Approved",
"issuing_state": "DNK",
"first_name": "Freja",
"last_name": "Nielsen",
"full_name": "Freja Nielsen",
"date_of_birth": "1988-03-02",
"node_id": "first_id_verification",
"verification_method": "wallet",
"assurance": "cryptographic",
"wallet_provider": "mitid",
"fallback_from": null,
"id_lookup": null,
"wallet_verification": {
"provider": "mitid",
"provider_name": "MitID",
"issuing_authority": "Danish Agency for Digital Government",
"issuing_country": "DNK",
"credential_type": "person_identification",
"level_of_assurance": "substantial",
"verified_at": "2026-09-04T09:12:44Z",
"signature_valid": true,
"attributes": {
"full_name": "Freja Nielsen",
"date_of_birth": "1988-03-02",
"cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
},
"portrait": null,
"face_match_score": null
},
"warnings": []
}
التحقق عبر NFC
تُعاد لكل قراءة لشريحة في مستند هوية: شريحة ePassport وفق ICAO 9303 أو شريحة eID، أو قراءة بطاقة My Number Card اليابانية عبر JPKI (chip_protocol: "jpki"). تظهر كعنصر nfc_verifications[] في GET /v3/session/{sessionId}/decision/ (واحد لكل سجل KYC رئيسي). المصدر: kyc/serializers/epassport.py:121-139 (NFCV3Serializer، ويمتد NFCV2Serializer في kyc/serializers/epassport.py:83-118).
| الحقل | النوع | قابل للقيمة الفارغة | الوصف | مثال |
|---|---|---|---|---|
status | string | لا | انظر تعداد الحالة. | "Approved" |
portrait_image | string (URL) | نعم | رابط موقّع مسبقاً إلى صورة الوجه المستخرجة من الشريحة. | "https://<media-host>/.../nfc_portrait.jpg?..." |
signature_image | string (URL) | نعم | رابط موقّع مسبقاً إلى صورة التوقيع المستخرجة من الشريحة (عندما تكون مخزنة على الشريحة). | null |
chip_data | object | نعم | البيانات الشخصية المُحلَّلة من مجموعات البيانات (Data Groups) الموجودة في الشريحة، مُسطَّحة (kyc/utils/epassport.py:165-212): dgs (مجموعات البيانات المقروءة)، وsurname، وname، وcountry، وnationality، وbirth_date (YYYY-MM-DD)، وexpiry_date (YYYY-MM-DD)، وsex (M/F)، وdocument_type (رمز المستند في MRZ)، وdocument_number، وoptional_data، وأرقام التحقق في MRZ (birth_date_hash, expiry_date_hash, document_number_hash, optional_data_hash, final_hash)، وmrz_string، وmrz_type (TD1/TD2/TD3)؛ إضافةً إلى place_of_birth وaddress (وكذلك full_name وfull_name_non_latin للأسماء غير اللاتينية) عندما تحمل الشريحة DG11، وتغيب هذه المفاتيح في غير ذلك. تكون null عندما تُتخطّى خطوة NFC. | { "document_number": "AB1234567", "name": "MARIA" } |
authenticity | object | نعم | { sod_integrity, dg_integrity }؛ وتكون null في قراءة JPKI. يتحقق sod_integrity من أن توقيع Document Security Object (SOD) يتسلسل إلى CSCA صالحة لدولة الإصدار، وأن DSC لم تُلغَ ولم تنتهِ صلاحيتها؛ ويتحقق dg_integrity من أن تجزئات كل Data Group تطابق SOD. وعندما تكون القيمتان true فهذا يعني أن الشريحة أصلية وغير معدَّلة. | { "sod_integrity": true, "dg_integrity": true } |
certificate_summary | object | نعم | ملخص شهادة موقّع المستند (kyc/utils/epassport.py:338-348): issuer، وsubject، وserial_number (عدد صحيح)، وnot_valid_before، وnot_valid_after (YYYY-MM-DD HH:MM:SS)، إضافةً إلى كائن validation بالصيغة { csca_verified, dsc_revoked, dsc_expired, csca_expired } (kyc/views/epassport.py:86). | { "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" } |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_nfc" |
is_nfc_skipped | boolean | لا | القيمة true عندما تُتخطّى خطوة NFC هذه صراحةً بدلًا من قراءتها، ويوضح skip_reason السبب. | false |
skip_reason | string | نعم | سبب تخطي الخطوة، ويُضبط فقط عندما تكون is_nfc_skipped القيمة true. إحدى القيم USER_SKIPPED أو DOCUMENT_WITHOUT_CHIP أو CHIP_CERTIFICATE_UNAVAILABLE أو DEVICE_WITHOUT_NFC أو INTEGRATION_WITHOUT_NFC_ACCESS أو MRZ_KEY_UNAVAILABLE أو JPKI_UNAVAILABLE؛ راجع أسباب التخطي. يتضمن payload القرار أيضًا الحقل nfc_skip_reason على مستوى الجلسة بالتصنيف نفسه، ويشمل خطوات NFC التي تم تجاوزها قبل إنشاء أي تقرير. | null |
chip_protocol | string | لا | طريقة قراءة الشريحة: icao (شريحة ICAO 9303 لجواز السفر ePassport أو لبطاقة الهوية الإلكترونية eID) أو jpki (بطاقة My Number اليابانية). في حالة jpki، تكون القيم portrait_image وsignature_image وchip_data وauthenticity وcertificate_summary مساوية لـ null. وتُضبط هذه القيمة أيضًا على الخطوات المتخطاة. | "icao" |
jpki | object | نعم | ما أثبتته قراءة بطاقة My Number: certificate_types وchain_valid وsignature_valid وrevocation_status (good أو revoked أو unchecked) وca_generation وcertificate_expires_at وcertificates[] وattributes (الاسم وتاريخ الميلاد والجنس والعنوان من شهادة التوقيع) وattributes_match_ocr وmismatched_attributes. لا تُعاد أبدًا الشهادات ولا أرقامها التسلسلية ولا التوقيعات. القيمة null لشرائح ICAO، وللخطوات المتخطاة، وعندما تنتهي الخطوة دون أي قراءة للبطاقة. راجع حقول JPKI. | null |
warnings | array | لا | راجع كائن التحذير. | [] |
{
"status": "Approved",
"portrait_image": "https://<media-host>/.../nfc_portrait.jpg?signature=...",
"signature_image": null,
"chip_data": {
"dgs": ["DG1", "DG2", "DG11"],
"surname": "GARCIA LOPEZ",
"name": "MARIA",
"country": "ESP",
"nationality": "ESP",
"birth_date": "1990-05-12",
"expiry_date": "2032-05-11",
"sex": "F",
"document_type": "P",
"document_number": "AB1234567",
"optional_data": "",
"birth_date_hash": "4",
"expiry_date_hash": "7",
"document_number_hash": "3",
"optional_data_hash": "",
"final_hash": "8",
"mrz_string": "P<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
"mrz_type": "TD3",
"place_of_birth": "MADRID",
"address": "CALLE MAYOR 1, MADRID"
},
"authenticity": { "sod_integrity": true, "dg_integrity": true },
"certificate_summary": {
"issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
"subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
"serial_number": 118120836164494130086420187336801405660,
"not_valid_before": "2020-11-18 10:21:11",
"not_valid_after": "2031-02-18 10:21:11",
"validation": {
"csca_verified": true,
"dsc_revoked": false,
"dsc_expired": false,
"csca_expired": false
}
},
"node_id": "first_nfc",
"is_nfc_skipped": false,
"skip_reason": null,
"chip_protocol": "icao",
"jpki": null,
"warnings": []
}
فحص الحيوية
تُعاد لكل جلسة فحص حيوية. تظهر كعنصرliveness_checks[] في GET /v3/session/{sessionId}/decision/. المصدر: face/serializers/face.py:301-320 (LivenessV3Serializer، يمتد من LivenessV2Serializer في face/serializers/face.py:216-298).
| الحقل | النوع | يقبل null | الوصف | المثال |
|---|---|---|---|---|
status | string | لا | راجع تعداد الحالة. | "Approved" |
method | string (enum) | نعم | ACTIVE_3D أو FLASHING أو PASSIVE (LivenessMethodChoices، common/config/choices.py:514-517). يُشغَّل الوضع السلبي عندما تكون جلسات سطح المكتب مسموحة والمستخدم على سطح المكتب. | "PASSIVE" |
score | float (0-100) | نعم | درجة ثقة فحص الحيوية، مُقرَّبة إلى منزلتين عشريتين. | 92.41 |
reference_image | string (URL) | نعم | عنوان URL موقَّع مسبقًا لاقتطاع الوجه المرجعي للمستخدم. | "https://<media-host>/.../reference.jpg?..." |
video_url | string (URL) | نعم | عنوان URL موقَّع مسبقًا لفيديو فحص الحيوية (في الوضع النشط فقط). | "https://<media-host>/.../liveness.webm?..." |
age_estimation | float | نعم | العمر المقدَّر (بالسنوات) للوجه الأكبر في الصورة المرجعية. | 34.2 |
matches | array of objects | لا | مطابقات الوجه عبر الجلسات. كل عنصر: { session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }. القيمة source هي session أو imported أو list_entry أو retained_template. تحمل المطابقة من نوع القالب المحفوظ الحقول vendor_user_id وvendor_data وbiometric_template_id، أما حقول الجلسة والصورة وتفاصيل الهوية والحالة وخدمة API فقيمتها null. | [] |
face_quality | float (0-100) | نعم | درجة جودة الوجه في فحص الحيوية السلبي (مُحوَّلة إلى نسبة مئوية). | 87.50 |
face_luminance | float (0-100) | نعم | درجة سطوع الوجه في فحص الحيوية السلبي (مُحوَّلة من النطاق 0-255 إلى نسبة مئوية). | 54.12 |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_liveness" |
warnings | array | لا | راجع كائن التحذير. | [] |
{
"status": "Approved",
"method": "PASSIVE",
"score": 92.41,
"reference_image": "https://<media-host>/.../reference.jpg?signature=...",
"video_url": null,
"age_estimation": 34.2,
"matches": [],
"face_quality": 87.50,
"face_luminance": 54.12,
"node_id": "first_liveness",
"warnings": []
}
مطابقة الوجه
تُعاد لكل مقارنة مطابقة وجه (عادةً بين وجه المستخدم في فحص الحيوية وصورة المستند الشخصية). تظهر كعنصرface_matches[] في GET /v3/session/{sessionId}/decision/. المصدر: face/serializers/face.py:367-389 (FaceMatchV3Serializer، يمتد من FaceMatchV2Serializer في face/serializers/face.py:323-364).
| الحقل | النوع | يقبل null | الوصف | المثال |
|---|---|---|---|---|
status | string | لا | راجع تعداد الحالة. | "Approved" |
score | float (0-100) | نعم | درجة التشابه، مُقرَّبة إلى منزلتين عشريتين. عندما يعيد المزوّد unmatched_faces[].Confidence فقط، تُحوَّل إلى 100 - confidence. | 97.83 |
source_image_session_id | string (UUID) | نعم | الجلسة التي وفّرت الصورة الشخصية المحفوظة لتكون مصدر الصورة (المرجعية)، وتُضبط في التدفقات القائمة على الصورة الشخصية، مثل المصادقة البيومترية أو الصورة الشخصية المقدَّمة عند إنشاء الجلسة. تكون القيمة null عندما تكون الصورة المرجعية هي صورة المستند الشخصية من الجلسة نفسها. | null |
source_image | string (URL) | نعم | عنوان URL موقَّع مسبقًا للصورة المصدر (المرجعية)، وهي عادةً صورة المستند الشخصية، أو الصورة الشخصية المحفوظة في تدفقات المصادقة البيومترية. | "https://<media-host>/.../source.jpg?..." |
target_image | string (URL) | نعم | عنوان URL موقَّع مسبقًا للصورة الهدف (وجه الشخص الحي) الملتقطة أثناء فحص الحيوية. | "https://<media-host>/.../target.jpg?..." |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_face_match" |
warnings | array | لا | راجع كائن التحذير. | [] |
face_coverage | object | نعم | تحدد ما إذا كانت eyes (العينان) وmouth (الفم) وface (الوجه) مغطاة في الصورة الملتقطة. تحمل كل منطقة الحقول covered وcalibrated وvisibility_score، والقيمة calibrated: false تعني دليلًا ظليًا لا يفعّل أي تحذير. تُعيده GET /v3/session/{sessionId}/decision/ فقط، ولا يظهر أبدًا في حمولات webhook. | { "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } } |
{
"status": "Approved",
"score": 97.83,
"source_image_session_id": null,
"source_image": "https://<media-host>/.../source.jpg?signature=...",
"target_image": "https://<media-host>/.../target.jpg?signature=...",
"node_id": "first_face_match",
"warnings": []
}
البحث بالوجه
تُرجَع بواسطة واجهة برمجة تطبيقات البحث بالوجه المستقلة (POST /v3/face-search/). لا يظهر البحث بالوجه أبدًا كمصفوفة بصيغة الجمع في /v3/session/{sessionId}/decision/. عند حفظه باستخدام save_api_request=true، تظهر الجلسة هناك كعنصر FACE_SEARCH ضمن features[]، مع عنصر في liveness_checks[] يحمل matches المخزنة. المصادر: apis/serializers/face_search.py:8-79 (FaceSearchResponseSerializer الذي يغلّف FaceSearchDetailsSerializer)؛ وتُبنى قواميس المطابقة في face/utils/utils.py:869-884.
الاستجابة ذات المستوى الأعلى:
| الحقل | النوع | قابل للفراغ | الوصف | مثال |
|---|---|---|---|---|
request_id | string (UUID) | لا | معرّف الجلسة المحفوظة عند save_api_request=true (ويمكن استخدامه مع GET /v3/session/{sessionId}/decision/)؛ وإلا فهو معرّف ارتباط مؤقت بصيغة UUID. | "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f" |
face_search | object | لا | payload تفاصيل البحث، وتوضحها الحقول أدناه. | — |
vendor_data | string | نعم | قيمة vendor_data المرسلة في الطلب كما هي. | null |
metadata | object | نعم | قيمة metadata المرسلة في الطلب كما هي. | null |
created_at | string (ISO 8601) | لا | الطابع الزمني للطلب من جهة الخادم. | "2026-06-12T01:04:42.763237+00:00" |
face_search:
| الحقل | النوع | قابل للفراغ | الوصف | مثال |
|---|---|---|---|---|
status | string | لا | تكون القيمة Declined فقط عند تفعيل تحذير FACE_IN_BLOCKLIST أو POSSIBLE_FACE_IN_BLOCKLIST، وتكون Approved في غير ذلك. المطابقات المكررة وحدها لا تؤدي إلى رفض الطلب أبدًا (apis/views/face_search.py:242-248). | "Approved" |
total_matches | integer | لا | عدد المطابقات المُرجعة في matches[] (0–5). | 1 |
matches | مصفوفة من كائنات مطابقة البحث بالوجه | لا | حتى 5 مطابقات فوق حد التشابه الأدنى، مرتبة تنازليًا حسب درجة التشابه (تأتي الإدخالات الموجودة في قائمة الحظر أولًا مع search_type=blocklisted_or_approved). | […] |
user_image | object | لا | نتيجة الكشف عن الصورة المرسلة: { entities: [{ bbox, confidence }], best_angle }، ويوجد كيان واحد لكل وجه مكتشف. | { "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 } |
warnings | مصفوفة من الكائنات | لا | شكل مختصر للتحذيرات في هذه الواجهة المستقلة، ولا يتضمن node_id. يحدد عقد المُسلسِل الحقول { risk, additional_data, log_type, short_description, long_description } (apis/serializers/face_search.py:49-54)، أما payload الفعلية عند التشغيل فتتضمن أيضًا feature، وقيمته دائمًا "LIVENESS" (apis/views/face_search.py:332-341). | [] |
كائن مطابقة البحث بالوجه
| الحقل | النوع | قابل للفراغ | الوصف | مثال |
|---|---|---|---|---|
session_id | string (UUID) | نعم | معرّف جلسة التحقق المطابقة. تكون null عندما يكون source بقيمة imported أو list_entry أو retained_template. | "a3f2a6f1-…" |
session_number | integer | نعم | رقم الجلسة المطابقة بصيغة سهلة القراءة في لوحة التحكم؛ تكون null للمطابقات التي ليست جلسات. | 1024 |
similarity_percentage | float (0-100) | لا | درجة التشابه بين الوجه المرسل والوجه المطابق. | 96.42 |
source | string (enum) | لا | مصدر تسجيل الوجه المطابق: session (جلسة تحقق أو استدعاء مستقل محفوظ)، وimported (رفع مباشر لصورة الوجه في ملف تعريف المستخدم)، وlist_entry (وجه مرتبط بقائمة)، وretained_template (القالب البيومتري الخالي من الصور والمحفوظ بعد حذف الجلسة المصدر). | "session" |
vendor_data | string | نعم | قيمة vendor_data الخاصة بالجلسة المطابقة، أو الخاصة بالمستخدم المرتبط في مطابقات imported وretained_template. | "user-12345" |
vendor_user_id | string (UUID) | نعم | المستخدم المرتبط. تكون null لمطابقات list_entry وللجلسات التي لا يوجد لها مستخدم. | "2f7c1a9e-…" |
biometric_template_id | string (UUID) | نعم | القالب المحفوظ الذي تمت مطابقته. يُضبط فقط لمطابقات retained_template، ويُستخدم مع GET/DELETE /v3/biometric-templates/{id}/. | null |
verification_date | string (ISO 8601) | نعم | وقت التقاط الوجه المطابق، أو وقت الاحتفاظ بالقالب في حالة retained_template؛ وتكون null لمطابقات list_entry. | "2024-11-04T09:14:02Z" |
user_details | object | نعم | { full_name, document_type, document_number } من التحقق من المستند في الجلسة المطابقة. في مطابقات imported يُضبط full_name فقط. تكون null عندما لا توجد بيانات هوية، وتكون دائمًا null لمطابقات retained_template. | { "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" } |
match_image_url | string (URL) | نعم | الوجه المرجعي للمستخدم المطابق: رابط موقّع مسبقًا عندما يكون save_api_request=true، ومسار التخزين الخام في غير ذلك. تكون دائمًا null لمطابقات retained_template لأنها لا تحتوي على صورة. | "https://<media-host>/.../matched.jpg?..." |
status | string | نعم | حالة التحقق للجلسة المطابقة (انظر تعداد الحالات)؛ تكون null للمطابقات التي ليست جلسات. | "Approved" |
is_blocklisted | boolean | لا | هل الوجه المطابق موجود في قائمة الحظر الخاصة بالوجوه لديك. تكون القيمة دائمًا false لمطابقات retained_template، ويُبلَّغ عن الوجه الموجود في قائمة الحظر بشكل منفصل كمطابقة list_entry. | false |
is_allowlisted | boolean | لا | هل الوجه المطابق موجود في إحدى قوائم السماح لديك. | false |
api_service | string (enum) | نعم | نوع الواجهة المستقلة للجلسة المطابقة بالأحرف الكبيرة (مثل PASSIVE_LIVENESS وFACE_MATCH)؛ تكون null لجلسات سير العمل ولمطابقات ليست جلسات. | null |
{
"request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f",
"face_search": {
"status": "Approved",
"total_matches": 1,
"matches": [
{
"session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f",
"session_number": 1024,
"similarity_percentage": 96.42,
"source": "session",
"vendor_data": "user-12345",
"verification_date": "2024-11-04T09:14:02Z",
"user_details": {
"full_name": "María García López",
"document_type": "Passport",
"document_number": "AB1234567"
},
"match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
"status": "Approved",
"is_blocklisted": false,
"is_allowlisted": false,
"api_service": null
}
],
"user_image": {
"entities": [
{
"bbox": [40, 40, 120, 120],
"confidence": 0.732973
}
],
"best_angle": 0
},
"warnings": []
},
"vendor_data": null,
"metadata": null,
"created_at": "2026-06-12T01:04:42.763237+00:00"
}
فحص AML
يُرجَع لكل كيان يخضع للفحص. يظهر كعنصرaml_screenings[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وجلسات KYB على حد سواء. المصدر: aml/serializers/aml.py:63-85 (AMLV3Serializer، ويمتد من AMLV2Serializer في aml/serializers/aml.py:28-60).
| الحقل | النوع | قابل للفراغ | الوصف | مثال |
|---|---|---|---|---|
status | string | لا | انظر تعداد الحالات. | "Approved" |
total_hits | integer | لا | عدد نتائج الفحص (يكون حاضرًا دائمًا، والقيمة الافتراضية 0). | 2 |
entity_type | string (enum) | نعم | person أو company (EntityTypeChoices، common/config/choices.py:675-677). | "person" |
hits | مصفوفة من الكائنات | لا | عنصر واحد لكل نتيجة. الحقول الرئيسية: id وcaption وmatch (قيمة منطقية) وtarget (قيمة منطقية | null، وتحدد ما إذا كان الكيان هو الهدف المباشر للإدراج في القائمة)، وmatch_score (درجة التطابق، وهي درجة الثقة في الهوية، ورقم عشري من 0 إلى 100) وrisk_score (درجة مخاطر الكيان، ورقم عشري من 0 إلى 100) وscore (القيمة المتقادمة، ورقم عشري من 0 إلى 1)، وdatasets[] (مثل PEP وPEP Level 1-4 وSanctions وAdverse Media وWarnings and Regulatory Enforcement وFitness and Probity)، وproperties (الأسماء والأسماء المستعارة وتواريخ الميلاد، …)، وfeatures وurl وfirst_seen وlast_seen وrca_name وrisk_view وscore_breakdown وpep_matches وsanction_matches وwarning_matches وadverse_media_matches وadverse_media_details وlinked_entities وadditional_information، وreview_status (Unreviewed وConfirmed Match وFalse Positive وInconclusive، ويمكن تعديلها عبر endpoint تحديث حالة نتيجة AML، AMLHitStatusChoices). | […] |
score | عدد عشري (0-100) | نعم | درجة الفحص الإجمالية: أعلى risk_score بين النتائج غير المعلَّمة بـ False Positive (aml/services/aml.py:832-842)؛ وتكون 0 عندما تكون كل نتائج المطابقة إيجابيات كاذبة. تكون null حتى يتم حسابها. | 42.7 |
screened_data | كائن | نعم | نسخة من البيانات المرسلة إلى الفحص: full_name وnationality وdate_of_birth وdocument_number. | { "full_name": "María García López", "date_of_birth": "1990-05-12" } |
is_ongoing_monitoring_enabled | قيمة منطقية | لا | هل الكيان مشترك في إعادة الفحص ضمن المراقبة المستمرة. | false |
next_ongoing_monitoring_bill_date | نص (YYYY-MM-DD) | نعم | يُحسب بالصيغة last_aml_bill_date + 365 days عندما تكون المراقبة المستمرة مفعّلة. وهو تاريخ الفوترة، وليس تاريخ فحص. | null |
last_ongoing_screening_at | نص (ISO 8601) | نعم | الوقت الذي أكملت فيه المراقبة المستمرة آخر إعادة فحص لهذا السجل، سواء تغيّرت النتيجة أم لا. تكون null إذا لم تُعَد إعادة الفحص أبدًا، ولا تُملأ بأثر رجعي. | "2026-09-12T04:03:11Z" |
last_ongoing_screening_datasets_updated_at | نص (ISO 8601) | نعم | أحدث تحديث لمجموعة بيانات AML أبلغ عنه المزوّد لذلك الفحص. تكون null عندما لا يُبلَّغ عن تاريخ لمجموعة البيانات، ولا تُقدَّر أبدًا. | null |
node_id | نص | null | نعم | معرّف عقدة سير العمل (V3). | "first_aml" |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
{
"status": "In Review",
"total_hits": 1,
"entity_type": "person",
"hits": [
{
"id": "Q7XW3-aml-hit-1",
"caption": "Maria Garcia Lopez",
"match": true,
"target": true,
"match_score": 86.4,
"risk_score": 42.7,
"datasets": ["PEP Level 2"],
"properties": {
"name": ["María García López", "M. García"],
"alias": ["Maria Garcia"],
"birthDate": ["1990-05-12"]
},
"url": "https://example.org/registry/entities/Q7XW3",
"first_seen": "2023-11-02T00:00:00Z",
"last_seen": "2026-05-01T00:00:00Z",
"review_status": "Unreviewed"
}
],
"score": 42.7,
"screened_data": {
"full_name": "María García López",
"date_of_birth": "1990-05-12",
"nationality": "ES",
"document_number": "AB1234567"
},
"is_ongoing_monitoring_enabled": false,
"next_ongoing_monitoring_bill_date": null,
"last_ongoing_screening_at": null,
"last_ongoing_screening_datasets_updated_at": null,
"node_id": "first_aml",
"warnings": []
}
تحليل عنوان IP
تُعاد لكل موقع شبكة يتم التقاطه. يظهر كـip_analyses[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وKYB على حد سواء. المصدر: kyc/serializers/location.py:196-243 (IPAnalysisSerializerV3).
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
status | نص | لا | راجع تعداد الحالات. | "Approved" |
node_id | نص | null | نعم | معرّف عقدة سير العمل (V3). | "first_ip_analysis" |
device_brand | نص | نعم | علامة الجهاز التجارية المستخلصة من وكيل المستخدم. | "Apple" |
device_model | نص | نعم | طراز الجهاز. | "iPhone" |
browser_family | نص | نعم | عائلة المتصفح. | "Mobile Safari" |
os_family | نص | نعم | عائلة نظام التشغيل. | "iOS" |
platform | نص | نعم | المنصة العامة (mobile، desktop، tablet). | "mobile" |
device_fingerprint | نص | نعم | تجزئة بصمة ثابتة لكل جهاز. | "f2a3…" |
ip_country | نص | نعم | اسم الدولة المحدَّد من العنوان. | "Spain" |
ip_country_code | نص (ISO 3166-1 alpha-2) | نعم | رمز الدولة المحدَّد من العنوان. | "ES" |
ip_state | نص | نعم | المنطقة أو الولاية المحدَّدة من العنوان. | "Comunidad de Madrid" |
ip_city | نص | نعم | المدينة المحدَّدة من العنوان. | "Madrid" |
latitude | عدد عشري | نعم | خط العرض المستنتج من العنوان. | 40.4168 |
longitude | عدد عشري | نعم | خط الطول المستنتج من العنوان. | -3.7038 |
ip_address | نص | نعم | العنوان الذي تم التقاطه. | "203.0.113.42" |
isp | نص | نعم | اسم مزوّد خدمة الإنترنت. | "Telefonica de Espana" |
organization | نص | نعم | اسم المؤسسة (غالبًا ما يكون مطابقًا لمزوّد خدمة الإنترنت). | "Telefonica de Espana" |
is_vpn_or_tor | قيمة منطقية | نعم | تكون true عندما ينتمي العنوان إلى VPN أو وكيل أو عقدة خروج Tor. | false |
is_data_center | قيمة منطقية | نعم | تكون true عندما ينتمي العنوان إلى ASN معروف لخدمات الاستضافة أو مراكز البيانات. | false |
time_zone | نص | نعم | اسم المنطقة الزمنية وفق IANA. | "Europe/Madrid" |
time_zone_offset | نص | نعم | الإزاحة عن UTC. | "+02:00" |
ip | كائن | لا | { location, distance_from_id_document, distance_from_poa_document }. وlocation = { latitude, longitude }. المسافات بالكيلومترات، وتكون null عندما يكون أحد الطرفين مفقودًا. | { "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 } |
id_document | كائن | لا | { location, distance_from_ip, distance_from_poa_document }. موقع وثيقة الهوية مستنتج من issuing_state والعنوان المحلَّل. | { "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 } |
poa_document | كائن | لا | { location, distance_from_ip, distance_from_id_document }. تم ترميز عنوان إثبات العنوان جغرافيًا. | { "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 } |
matches | مصفوفة من الكائنات | لا | عمليات مطابقة عبر الجلسات للعنوان أو للجهاز. كل عنصر: { session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }. تكون match_type إما ip_address أو device_fingerprint، وتكون match_source إما ip_address أو persistent_id أو legacy_fp أو recovered_high (المطابقات المستعادة تحمل أيضًا recovery_similarity وtls_ja4_corroborated وrecovery_gate_reason). محدودة بخمس مطابقات للعنوان وخمس مطابقات للجهاز. | [] |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
browser_version, os_version | نص | نعم | إصداران للمتصفح ونظام التشغيل من وكيل المستخدم. | "17.4" |
user_agent, accept_language | نص | نعم | سلسلة وكيل المستخدم ورأس Accept-Language الذي أرسله المتصفح. | "en-US,en;q=0.9" |
session_identifier, session_age_ms | نص، عدد صحيح | نعم | جلسة التصفح التي نُفّذت فيها الخطوة، وعمرها بالمللي ثانية. | 48210 |
coords_accuracy | عدد عشري | نعم | نصف قطر الدقة، بالأمتار، للإحداثيات التي أبلغ عنها الجهاز. | 35.0 |
raw_device_data | كائن | نعم | إشارات الجهاز الخام المجمّعة للخطوة. | {} |
{
"status": "Approved",
"node_id": "first_ip_analysis",
"device_brand": "Apple",
"device_model": "iPhone",
"browser_family": "Mobile Safari",
"os_family": "iOS",
"platform": "mobile",
"device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
"ip_country": "Spain",
"ip_country_code": "ES",
"ip_state": "Comunidad de Madrid",
"ip_city": "Madrid",
"latitude": 40.4168,
"longitude": -3.7038,
"ip_address": "203.0.113.42",
"isp": "Telefonica de Espana",
"organization": "Telefonica de Espana",
"is_vpn_or_tor": false,
"is_data_center": false,
"time_zone": "Europe/Madrid",
"time_zone_offset": "+02:00",
"ip": {
"location": { "latitude": 40.4168, "longitude": -3.7038 },
"distance_from_id_document": 3.4,
"distance_from_poa_document": 1.1
},
"id_document": {
"location": { "latitude": 40.4165, "longitude": -3.7026 },
"distance_from_ip": 3.4,
"distance_from_poa_document": 4.0
},
"poa_document": {
"location": { "latitude": 40.4170, "longitude": -3.7040 },
"distance_from_ip": 1.1,
"distance_from_id_document": 4.0
},
"matches": [],
"warnings": []
}
التحقق من الموقع
تُعاد لكل خطوة التحقق من الموقع. تظهر كـgeolocation_checks[] في GET /v3/session/{sessionId}/decision/: عنصر واحد لكل خطوة، وهو محاولتها المقبولة. يسرد geolocation_attempts[] كل محاولة لكل خطوة، من الأقدم إلى الأحدث. يكون كلاهما null لسير العمل الذي لا يتضمن هذه الخطوة. المصدر: GeolocationDecisionSerializer.
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
node_id | نص | نعم | عقدة سير العمل التي أنتجت النتيجة. | "geolocation_1" |
status | نص | لا | راجع تعداد الحالة. | "Declined" |
outcome | نص | نعم | ما حدث أثناء المحاولة: verified، low_accuracy، accuracy_undetermined، stale، approximate، denied، restricted، unavailable، timeout، mock_detected، outside_geofence، in_blocked_area، anonymizer_detected، skipped، replay_rejected أو unsupported_client. | "outside_geofence" |
permission | نص | نعم | الإذن الذي منحه النظام: granted_precise، granted_approximate، denied، restricted، unavailable، timeout، dismissed أو not_requested. | "granted_precise" |
latitude، longitude | عدد عشري | نعم | الموقع وفق WGS84. يكون null عند عدم وجود موقع. | 48.8566 |
accuracy_m | عدد عشري | نعم | نصف قطر عدم اليقين بالأمتار. | 35.0 |
accuracy_confidence | نص | نعم | p95، p68 أو unspecified. | "p95" |
measured_at، age_seconds | تاريخ ووقت، عدد صحيح | نعم | وقت التقاط الجهاز للموقع، والثواني التي انقضت حتى استلمه Didit. | 2 |
source، platform، sdk_version | نص | نعم | مصدر الموقع، والعميل الذي أنتجه، وإصدار SDK الخاص به. | "browser" |
is_mock، produced_by_accessory | منطقي | نعم | أدلة الانتحال التي تبلغ عنها المنصة. تعني null أن المنصة لا تبلغ عنها. | null |
integrity | نص | لا | attested، not_attested، failed، unsupported (ويب) أو not_determined. | "unsupported" |
country_code، region_code، city | نص | نعم | المكان الذي يشير إليه الموقع. | "FR" |
geofence، inside_geofence، geofence_basis، inside_areas، blocked_areas | كائن، منطقي، نص، مصفوفات | نعم | نتيجة الدولة والمنطقة. | { "enabled": true, "result": "outside" } |
position_source، anonymizers | نص، كائن | نعم | مصدر الموقع الذي تأخذه الخطوة، وإشارات VPN والوكيل وTor والانتحال والمحاكيات. | "device_and_ip" |
ip_distance_km، ip_distance_uncertainty_km، ip_consistent، document_distance_km، travel_excused، consecutive_mismatches | عدد، منطقي، عدد صحيح | نعم | المقارنات مع موقع عنوان IP والعنوان المسجل. | 12.4 |
attempts | عدد صحيح | لا | رقم المحاولة ضمن الخطوة. | 3 |
consent | كائن | نعم | accepted_at وversion وlocale للإشعار الذي قبله الشخص. | |
warnings | مصفوفة من كائنات التحذير | لا | تحذيرات LOCATION_* الخاصة بالخطوة. لا يظهر هذا الحقل في geolocation_attempts[] التي تضيف received_at وcreated_at. | [] |
إثبات العنوان
يُعاد لكل مستند عنوان مقدَّم. يظهر بوصفهpoa_verifications[] في GET /v3/session/{sessionId}/decision/. المصدر: poa/serializers/poa.py:212-227 (POAV3Serializer، يمتد من POAV2Serializer في poa/serializers/poa.py:173-209).
| الحقل | النوع | قابل لـ null | الوصف | المثال |
|---|---|---|---|---|
status | نص | لا | راجع تعداد الحالة. | "Approved" |
issuing_state | نص (ISO 3166-1 alpha-3) | نعم | رمز دولة جهة إصدار المستند. | "ESP" |
document_type | نص | لا | النوع العام من PoaDocumentTypeChoices (common/config/choices.py:868-873): UTILITY_BILL، BANK_STATEMENT، GOVERNMENT_ISSUED_DOCUMENT، OTHER_POA_DOCUMENT. يرجع إلى UNKNOWN ولا يكون أبداً null. | "UTILITY_BILL" |
document_subtype | نص | لا | رمز النوع الفرعي من PoaDocumentSubtypeChoices (مثل ELECTRICITY_BILL وWATER_BILL وACCOUNT_STATEMENT). يرجع إلى UNKNOWN ولا يكون أبداً null. | "ELECTRICITY_BILL" |
issuer | نص | نعم | اسم الجهة المُصدِرة. | "Iberdrola" |
issue_date | نص (YYYY-MM-DD) | نعم | تاريخ إصدار المستند. | "2026-04-15" |
expiration_date | نص (YYYY-MM-DD) | نعم | تاريخ الانتهاء المطبوع على المستند، عند وجوده. | null |
poa_address | نص | نعم | العنوان الخام المستخرج عبر OCR. | "Calle Mayor 1, 28001 Madrid" |
poa_formatted_address | نص | نعم | العنوان المحدَّد جغرافياً والمنسَّق. | "Calle Mayor 1, 28001 Madrid, Spain" |
poa_parsed_address | كائن | نعم | العنوان المهيكل (street_1، street_2، city، region، postal_code، country (alpha-2)، address_type، document_location، …). | { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" } |
document_file | نص (URL) | نعم | عنوان URL موقَّع مسبقاً للمستند المرفوع. | "https://<media-host>/.../poa.pdf?..." |
document_language | نص | نعم | لغة المستند المكتشفة (ISO 639-1). | "es" |
document_metadata | كائن | نعم | بيانات وصفية مصفّاة: file_size، content_type، creation_date، modified_date، creator، producer، software، encryption، is_signed، is_tampered، signature_info، exif_original_date، exif_digitized_date، processed_by_known_editor، has_different_creation_mod_date، overlay_manipulation. | { "file_size": 184221, "content_type": "application/pdf", "is_tampered": false } |
extra_fields | كائن | لا | حقول الحساب البنكي (bank_account_number، bank_iban، bank_sort_code، bank_routing_number، bank_swift_bic، bank_branch_name، bank_branch_address)، وdocument_phone_number، وadditional_names، بالإضافة إلى أي مفاتيح مخصصة محفوظة في السجل. | { "bank_iban": null, "additional_names": [] } |
name_on_document | نص | نعم | الاسم كما يظهر في إثبات العنوان. | "María García López" |
expected_details_address | نص | نعم | العنوان الذي كتبه العميل أثناء التسجيل حرفياً. | "Calle Mayor 1, Madrid" |
expected_details_formatted_address | نص | نعم | العنوان المتوقع المحدَّد جغرافياً. | "Calle Mayor 1, 28001 Madrid, Spain" |
expected_details_parsed_address | كائن | نعم | العنوان المتوقع المهيكل. | { "city": "Madrid", "postal_code": "28001" } |
name_match_score_expected_details | عدد عشري (0-100) | نعم | مطابقة تقريبية بين name_on_document والاسم المُدخل عند إنشاء الجلسة. | 94.0 |
name_match_score_id_verification | عدد عشري (0-100) | نعم | مطابقة تقريبية بين name_on_document وfull_name للهوية المتحقق منها. | 100.0 |
extra_files | مصفوفة من النصوص (URL) | لا | روابط موقّعة مسبقاً للملفات الإضافية المرفوعة. | [] |
detected_codes | مصفوفة من الكائنات | لا | رموز QR والباركود المكتشفة في كل صفحة من صفحات المستند التي عولجت: type، وpage_number (يبدأ من 1)، وposition (مضلع)، وx/y/width/height (الإطار المحيط)، وpage_width/page_height، وraw_payload (base64)، وparsed_payload (القيمة بعد فك الترميز، وتكون null عندما يُعثر على الرمز ولكن يتعذر فك ترميزه). تكون المصفوفة فارغة عندما لا يعثر الاكتشاف على شيء. | [{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }] |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_poa" |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
{
"status": "Approved",
"issuing_state": "ESP",
"document_type": "UTILITY_BILL",
"document_subtype": "ELECTRICITY_BILL",
"issuer": "Iberdrola",
"issue_date": "2026-04-15",
"expiration_date": null,
"poa_address": "Calle Mayor 1, 28001 Madrid",
"poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
"poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" },
"document_file": "https://<media-host>/.../poa.pdf?signature=...",
"document_language": "es",
"document_metadata": {
"file_size": 184221,
"content_type": "application/pdf",
"creation_date": "2026-04-15T08:11:32Z",
"modified_date": "2026-04-15T08:11:32Z",
"creator": "Iberdrola Billing",
"producer": "Adobe PDF Library 15.0",
"software": null,
"encryption": null,
"is_signed": true,
"is_tampered": false,
"signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" },
"exif_original_date": null,
"exif_digitized_date": null,
"processed_by_known_editor": false,
"has_different_creation_mod_date": false,
"overlay_manipulation": null
},
"extra_fields": {
"bank_account_number": null,
"bank_iban": null,
"bank_sort_code": null,
"bank_routing_number": null,
"bank_swift_bic": null,
"bank_branch_name": null,
"bank_branch_address": null,
"document_phone_number": null,
"additional_names": []
},
"name_on_document": "María García López",
"expected_details_address": "Calle Mayor 1, Madrid",
"expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
"expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" },
"name_match_score_expected_details": 94.0,
"name_match_score_id_verification": 100.0,
"extra_files": [],
"detected_codes": [
{
"type": "QR_CODE",
"page_number": 1,
"position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
"x": 820,
"y": 1120,
"width": 182,
"height": 182,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx",
"parsed_payload": "https://iberdrola.es/factura/9981"
},
{
"type": "CODE_128",
"page_number": 1,
"position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
"x": 112,
"y": 1480,
"width": 448,
"height": 60,
"page_width": 1190,
"page_height": 1684,
"raw_payload": "MDA5OTgxMDAwNDI=",
"parsed_payload": "0099810042"
}
],
"node_id": "first_poa",
"warnings": []
}
التحقق من رقم الهاتف
يُعاد لكل محاولة تحقق من رقم الهاتف. يظهر كـphone_verifications[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وKYB على حد سواء. المصدر: phone/serializers/phone.py:251-266 (PhoneV3Serializer، ويمتد من PhoneV2Serializer في phone/serializers/phone.py:103-248).
| الحقل | النوع | يقبل قيمة فارغة | الوصف | المثال |
|---|---|---|---|---|
status | string | لا | راجع تعداد الحالة. | "Approved" |
phone_number_prefix | string | لا | بادئة الدولة وفق E.164 (مع +). | "+34" |
phone_number | string | لا | رقم المشترك دون البادئة. | "612345678" |
full_number | string | لا | الرقم الكامل وفق E.164 (phone_number_prefix + phone_number). | "+34612345678" |
country_code | string (ISO 3166-1 alpha-2) | نعم | دولة الرقم. | "ES" |
country_name | string | نعم | اسم الدولة المترجَم إلى اللغة المحلية. | "Spain" |
carrier | object | لا | { name, type } حيث تكون type قيمة من LineTypeChoices (common/config/choices.py:648-667): mobile، وfixed_line، وvoip، وisp، وvpn، وtoll_free، وpremium_rate، وsatellite، وpager، وpayphone، وvoice_mail، وunknown، وفئات خطوط أخرى. | { "name": "Movistar", "type": "mobile" } |
is_disposable | boolean | لا | تكون true عندما يصنّف المشغّل الرقم على أنه مؤقت أو قابل للتخلّص منه. | false |
is_virtual | boolean | لا | تكون true عندما تكون carrier.type إحدى القيم voip أو isp أو vpn. | false |
verification_method | string | لا | القناة المستخدمة لتسليم رمز OTP (whatsapp، وsms، …). تُقرأ من actual_channel لآخر محاولة إرسال (وإن لم تتوفر فمن channel المطلوب، ثم sms). | "whatsapp" |
verification_attempts | integer | لا | إجمالي محاولات إرسال رمز OTP (الإرسال الأولي مع إعادات الإرسال). | 1 |
verified_at | string (ISO 8601) | نعم | الطابع الزمني لإدخال رمز OTP بنجاح. | "2026-05-17T10:14:02Z" |
lifecycle | مصفوفة من الكائنات | لا | أحداث مرتبة زمنياً: محاولات الإرسال، وإشعارات التسليم، وفحوصات الرموز، وحدث الحالة النهائية. كل حدث هو { type, timestamp, details, fee }. تأتي أنواع الأحداث من PhoneEventChoices. | […] |
matches | مصفوفة من الكائنات | لا | تطابقات أرقام الهاتف عبر الجلسات. كل عنصر: { session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }. تكون قيمة source إما session أو list_entry. | [] |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_phone" |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
phone_intelligence | object | نعم | إشارات ذكاء الهاتف. تظهر فقط عندما تُشغَّل إضافة الذكاء على الرقم. | |
phone_social | object | نعم | البصمة الاجتماعية للرقم. تظهر فقط عندما تُشغَّل إضافة البصمة الاجتماعية. |
{
"status": "Approved",
"phone_number_prefix": "+34",
"phone_number": "612345678",
"full_number": "+34612345678",
"country_code": "ES",
"country_name": "Spain",
"carrier": { "name": "Movistar", "type": "mobile" },
"is_disposable": false,
"is_virtual": false,
"verification_method": "whatsapp",
"verification_attempts": 1,
"verified_at": "2026-05-17T10:14:02Z",
"lifecycle": [
{
"type": "PHONE_VERIFICATION_MESSAGE_SENT",
"timestamp": "2026-05-17T10:13:51Z",
"details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
"fee": 0.02
},
{
"type": "PHONE_DELIVERY_DELIVERED",
"timestamp": "2026-05-17T10:13:52Z",
"details": { "channel": "whatsapp", "status": "delivered" },
"fee": 0
},
{
"type": "VALID_CODE_ENTERED",
"timestamp": "2026-05-17T10:14:02Z",
"details": { "code_tried": "482917", "status": "Approved" },
"fee": 0
},
{
"type": "PHONE_VERIFICATION_APPROVED",
"timestamp": "2026-05-17T10:14:02Z",
"details": null,
"fee": 0
}
],
"matches": [],
"node_id": "first_phone",
"warnings": []
}
التحقق من البريد الإلكتروني
يُعاد لكل محاولة تحقق من البريد الإلكتروني. يظهر كـemail_verifications[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وKYB على حد سواء. المصدر: email_verification/serializers/email.py:149-164 (EmailV3Serializer، ويمتد من EmailV2Serializer في email_verification/serializers/email.py:38-146).
| الحقل | النوع | يقبل قيمة فارغة | الوصف | المثال |
|---|---|---|---|---|
status | string | لا | راجع تعداد الحالة. | "Approved" |
email | string | لا | عنوان البريد الإلكتروني المُقدَّم. | "maria.garcia@example.com" |
is_breached | boolean | لا | تكون true عندما يظهر البريد الإلكتروني في تسريب بيانات معروف. | false |
breaches | مصفوفة من الكائنات | لا | تفاصيل كل تسريب عندما تكون is_breached قيمتها true: { name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }. | [] |
is_disposable | boolean | لا | تكون true عندما ينتمي البريد الإلكتروني إلى مزوّد بريد مؤقت. | false |
is_undeliverable | boolean | لا | تكون true عندما يُظهر فحص التسليم عبر SMTP أن صندوق الوارد لا يقبل الرسائل. | false |
verification_attempts | integer | لا | إجمالي محاولات فحص رمز OTP. | 1 |
verified_at | string (ISO 8601) | نعم | الطابع الزمني لإدخال رمز OTP بنجاح. | "2026-05-17T10:15:22Z" |
lifecycle | مصفوفة من الكائنات | لا | أحداث مرتبة زمنياً: محاولات الإرسال، وفحوصات الرموز، وحدث الحالة النهائية. كل حدث هو { type, timestamp, details, fee }. تأتي أنواع الأحداث من EmailEventChoices. | […] |
matches | مصفوفة من الكائنات | لا | تطابقات البريد الإلكتروني عبر الجلسات. كل عنصر: { session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }. تكون قيمة source إما session أو list_entry. | [] |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_email" |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
email_intelligence | object | نعم | إشارات ذكاء البريد الإلكتروني. تظهر فقط عندما تُشغَّل إضافة الذكاء على العنوان. | |
email_social | object | نعم | البصمة الاجتماعية للعنوان. تظهر فقط عندما تُشغَّل إضافة البصمة الاجتماعية. |
{
"status": "Approved",
"email": "maria.garcia@example.com",
"is_breached": false,
"breaches": [],
"is_disposable": false,
"is_undeliverable": false,
"verification_attempts": 1,
"verified_at": "2026-05-17T10:15:22Z",
"lifecycle": [
{
"type": "EMAIL_VERIFICATION_MESSAGE_SENT",
"timestamp": "2026-05-17T10:15:11Z",
"details": { "status": "Success", "reason": null },
"fee": 0.02
},
{
"type": "VALID_CODE_ENTERED",
"timestamp": "2026-05-17T10:15:22Z",
"details": { "code_tried": "739204", "status": "Approved" },
"fee": 0
},
{
"type": "EMAIL_VERIFICATION_APPROVED",
"timestamp": "2026-05-17T10:15:22Z",
"details": null,
"fee": 0
}
],
"matches": [],
"node_id": "first_email",
"warnings": []
}
التحقق من قواعد البيانات
يُعاد لكل عملية بحث في قاعدة البيانات تُجرى على البيانات التي قدّمها المستخدم. يظهر كـdatabase_validations[] في GET /v3/session/{sessionId}/decision/. المصدر: database_validation/serializers/database_validation.py:21-142 (DatabaseValidationV3Serializer، ويمتد من DatabaseValidationV2Serializer).
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
issuing_state | string (ISO 3166-1 alpha-3) | نعم | الدولة التي تم الاستعلام عن سجلها. | "ESP" |
validation_type | string (enum) | لا | كيفية تأكيد النتيجة: one_by_one (نتيجة خدمة واحدة)، أو two_by_two (خدمتان مختلفتان أو أكثر طابقتا رقم الهوية مطابقة كاملة وبشكل مستقل)، أو not_enabled (تم تخطي المدقّق أو لم يستجب أي مزوّد. ولا تزال no_match النهائية تُعيد one_by_one). لا تكون أبداً null. المصدر: DatabaseValidationChoices (common/config/choices.py:1097-1100). | "one_by_one" |
screened_data | object | لا | البيانات المُرسلة إلى السجل. تُنشأ لحقول الملفات (selfie، cnh_qr_code_image، document_image) روابط موقّعة مسبقاً عند القراءة. | { "document_number": "99999999R", "date_of_birth": "1990-05-12" } |
validations | array of objects | لا | إدخال واحد لكل خدمة في الكتالوج أنتجت تطابقاً. يمكن أن يتضمن كل إدخال service_id وservice_name وvalidation (كائن حكم المزوّد) وoutcome_code وoutcome_detail وsource_data (الملف الشخصي للمواطن بعد التنظيف: full_name وgender وdate_of_birth وphoto (رابط موقّع مسبقاً) وsignature (رابط موقّع مسبقاً)، …). | […] |
errors | array of objects | نعم | أخطاء لكل خدمة عند فشل استعلام، ويُحذف المفتاح بالكامل عندما يكون فارغاً. كل إدخال هو كائن الخطأ الخاص بالخدمة المصدر، مضافاً إليه service_id الخاص بالخدمة التي أبلغت عن الخطأ. | [] |
match_type | string (enum) | نعم | حكم التطابق الإجمالي عبر الخدمات المستعلَم عنها: full_match أو partial_match أو no_match (DatabaseValidationMatchTypeChoices، common/config/choices.py:1103-1106). تكون null حتى يتم التقييم. | "full_match" |
status | string | لا | راجع تعداد الحالة. | "Approved" |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_db_validation" |
warnings | array | لا | راجع كائن التحذير. | [] |
{
"issuing_state": "ESP",
"validation_type": "one_by_one",
"screened_data": {
"document_number": "99999999R",
"date_of_birth": "1990-05-12",
"first_name": "María",
"last_name": "García López"
},
"validations": [
{
"service_id": "esp_dni",
"service_name": "Spain - DNI/NIE verification",
"validation": { "is_valid": true, "match_score": 100 },
"outcome_code": "MATCH",
"outcome_detail": "All identifiers match the registry record.",
"source_data": {
"full_name": "María García López",
"gender": "F",
"date_of_birth": "1990-05-12",
"photo": "https://<media-host>/.../registry_photo.jpg?signature=...",
"signature": null
}
}
],
"match_type": "full_match",
"status": "Approved",
"node_id": "first_db_validation",
"warnings": []
}
استجابة الاستبيان
تُعاد لكل إرسال استبيان. تظهر كـquestionnaire_responses[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وKYB على حد سواء. المصدر: questionnaires/serializers/questionnaire.py:591-597 (QuestionnaireResponseV3Serializer، ويمتد من QuestionnaireResponseSerializer في questionnaires/serializers/questionnaire.py:520-588).
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
questionnaire_id | string (UUID) | لا | معرّف إصدار الاستبيان الذي تمت الإجابة عنه. | "6a0f1c2c-…" |
title | string | لا | اسم الاستبيان، كما هو مضبوط في Console. | "Customer risk profile" |
description | string | نعم | وصف الاستبيان. | "Short risk-profile questions." |
languages | array of strings | لا | رموز اللغات التي نُشر بها الاستبيان. | ["en", "es"] |
default_language | string | لا | رمز اللغة الاحتياطية. | "en" |
is_active | boolean | لا | ما إذا كان إصدار الاستبيان هذا هو الإصدار النشط. | true |
is_simple_questionnaire | boolean | لا | true عندما لا يحتوي الاستبيان على تفرّع (قائمة مسطحة). | true |
questionnaire_group_id | string (UUID) | لا | معرّف مشترك بين إصدارات الاستبيان نفسه. | "a7c2c2c2-…" |
version | integer | لا | رقم إصدار القالب النشط. | 3 |
status | string | لا | واحدة من Approved أو In Review أو Not Finished (تُحوَّل حالة الرفض على مستوى الاستبيان إلى In Review). | "Approved" |
published_at | string (ISO 8601) | نعم | وقت نشر القالب. | "2026-01-12T11:00:00Z" |
sections | array of objects | لا | الأقسام مرتبةً بعد تطبيق اجتياز المخطط وتصفية الظهور. كل قسم هو { title, description, items[] } (يأتي العنوان والوصف من SECTION_HEADER الافتتاحي، وهما مترجمان مسبقاً). كل عنصر هو عنصر نموذج (uuid وvalue (معرّف العقدة) وelement_type وis_required وtitle وdescription وplaceholder وchoices وmax_files وrequired_if وrepeatable_config)، بالإضافة إلى حقل answer، وهو null عند عدم الإجابة، ويُحذف في عناصر التخطيط HEADING وPARAGRAPH وSEPARATOR. تحتوي إجابات الملفات على { files: [<presigned URL>, …] }. | […] |
node_id | string | null | نعم | معرّف عقدة سير العمل (V3). | "first_questionnaire" |
{
"questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9",
"title": "Customer risk profile",
"description": "Short risk-profile questions.",
"languages": ["en", "es"],
"default_language": "en",
"is_active": true,
"is_simple_questionnaire": true,
"questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9",
"version": 3,
"status": "Approved",
"published_at": "2026-01-12T11:00:00Z",
"sections": [
{
"title": "Source of funds",
"description": null,
"items": [
{
"uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9",
"value": "q_source_of_funds",
"element_type": "SINGLE_CHOICE",
"is_required": true,
"title": "What is your main source of funds?",
"description": null,
"placeholder": null,
"choices": [
{ "label": "Salary", "value": "salary" },
{ "label": "Business income", "value": "business" },
{ "label": "Investments", "value": "investments" }
],
"max_files": 1,
"required_if": null,
"repeatable_config": null,
"answer": { "value": "salary" }
}
]
}
],
"node_id": "first_questionnaire"
}
التوقيع الإلكتروني
تُعاد لكل موقّع في خطوة التوقيع الإلكتروني. تظهر كـsignatures[] في GET /v3/session/{sessionId}/decision/ لجلسات KYC وKYB على حد سواء، وذلك فقط عندما يتضمن سير العمل هذه الخطوة. على عكس كائنات التقارير الأخرى، فإن status فيها هو مرحلة التوقيع، ونتيجته موجودة في verdict، وعناصر warnings[] فيها هي { code, node_id } وليست كائنات التحذير.
| الحقل | النوع | يقبل null | الوصف | مثال |
|---|---|---|---|---|
id | string (UUID) | لا | معرّف توقيع الموقّع. استخدمه كـ signature_id في مسارات الأدلة والتحقق. | "0e6c2a8e-…" |
node_id | string | لا | معرّف عقدة سير العمل. | "feature_signature" |
status | string | لا | مرحلة التوقيع: intro أو review أو code أو signing أو signed أو declined. الحالة signed وحدها تعني أن المستندات موقّعة. | "signed" |
verdict | string | لا | Not Finished أو Approved أو In Review أو Declined. | "Approved" |
level | string | لا | simple (الافتراضي) أو aes. qes إضافة غير متاحة بعد. | "aes" |
format | string | لا | pdf للتوقيع البسيط، وpades للتوقيع المتقدم (AES). | "pades" |
profile | string | نعم | PAdES-B-LT بعد إتمام توقيع متقدم (AES)، وإلا فهو null. | "PAdES-B-LT" |
signer | object | لا | { name, capacity, company, role, roles, identity_session_id }. تكون capacity القيمة self (KYC) أو company (KYB). | { "name": "Jane Doe", "capacity": "self", … } |
identity_used | object | لا | { session_id, kyc_id, verified, expected_name }: الهوية الموثّقة التي يعتمد عليها التوقيع. تكون فارغة للتوقيع البسيط الذي لا توجد فيه هوية موثّقة. | { "verified": true, … } |
certificate | object | نعم | { issuer, issued_to, serial, valid_from, valid_until }. تكون null حتى يتم التوقيع، وتكون null دائماً للتوقيع البسيط. | { "serial": "5A3F9C21", … } |
confirmation | object | لا | { channel, destination, confirmed_at, attempts }. يكون destination مُقنَّعًا، ويحسب attempts الرموز التي أُدخلت، بما فيها الرمز الصحيح. لا يتضمن التوقيع البسيط رمزًا، لذلك تكون قيمتا channel وdestination هما null. | { "channel": "email", … } |
timestamp | object | نعم | { time, qualified, valid }. تكون قيمة qualified دائمًا false بالنسبة إلى AES. تكون القيمة null إلى أن يُوقَّع المستند، وتكون دائمًا null في حالة التوقيع البسيط. | { "qualified": false, … } |
documents | array of objects | لا | { id, uuid, title, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }. تكون قيمة status إما signed أو declined أو not_signed أو not_reached. تكون قيمة mode إما fields أو read_and_agree. تكون قيمة source_format إما pdf أو docx، ويصف conversion ملف Word الأصلي، أو يكون null في حالة ملف PDF. | […] |
documents[].fields | array of objects | لا | { key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason } لكل حقل في المستند. تكون قيمة value نصًا، أو قيمة منطقية لمربع الاختيار، أو true للتوقيع أو الأحرف الأولى المطبّقة. تكون فارغة في المستند الذي لا يحتوي على حقول. | […] |
adopted_signature | object | نعم | { method, font, adopted_at }: التوقيع والأحرف الأولى التي اعتمدها الموقِّع. تكون قيمة method إما typed أو drawn، ويمثل font نمط الكتابة اليدوية للتوقيع المكتوب. تكون القيمة null إلى أن يُعتمَد التوقيع. | { "method": "drawn", … } |
electronic_signature_consent_at | string (ISO 8601) | نعم | الوقت الذي وافق فيه الموقِّع على توقيع المستندات إلكترونيًا. يُضبط عندما يحتوي أي مستند على حقول. | "2026-11-03T10:41:40Z" |
evidence_file | string | نعم | مسار ملف PDF الخاص بالأدلة، بعد التوقيع. | "/v3/session/…/evidence/?signature_id=…" |
warnings | array of objects | لا | { code, node_id }، وتكون قيمة code واحدة من: SIGNATURE_DECLINED، وSIGNATURE_OTP_FAILED، وSIGNATURE_NAME_MISMATCH، وSIGNATURE_IDENTITY_NOT_VERIFIED، وSIGNATURE_DOCUMENT_CHANGED. | [] |
validation | object | نعم | { valid, checked_at, documents[] }: آخر فحص تشفيري للمستندات الموقّعة. تكون القيمة null إلى أن يُوقَّع المستند. تكون { valid: null, reason: "signature_provider_outcome_unknown", checked_at } عندما يتعذر تأكيد نتيجة التوقيع. | { "valid": true, … } |
declined_at | string (ISO 8601) | نعم | الوقت الذي رفض فيه الموقِّع التوقيع. | null |
declined_action | string | لا | القيمة signature_declined_action الخاصة بالخطوة. | "REVIEW" |
signed_at | string (ISO 8601) | نعم | الوقت الذي وُقّعت فيه المستندات. | "2026-11-03T10:42:24Z" |
expires_at | string (ISO 8601) | لا | الوقت الذي يتوقف فيه رابط التوقيع عن العمل. | "2026-11-10T10:30:00Z" |
email_sent_at | string (ISO 8601) | نعم | الوقت الذي أُرسلت فيه نسخة موقّعة إلى بريد الموقِّع الإلكتروني. | "2026-11-03T10:42:30Z" |
email_unavailable_reason | string | نعم | سبب عدم إرسال نسخة بالبريد الإلكتروني، عند طلبها. | null |
ip_address | string | نعم | عنوان IP الخاص بالموقِّع عندما طلب رمز التحقق الخاص به. | "203.0.113.10" |
place | string | نعم | لا يتم جمعه: تكون القيمة دائمًا null. | null |
place_unavailable_reason | string | نعم | not_collected. | "not_collected" |
تقدير العمر
تُرجَع من واجهة برمجة التطبيقات المستقلة لتقدير العمر (POST /v3/age-estimation/). تتضمن الاستجابة جزءًا من بنية Liveness check ضمن الغلاف age_estimation، وهو يشمل status وmethod وscore وage_estimation وwarnings، إضافةً إلى كتلة user_image الخاصة باكتشاف الوجه والمتاحة في الواجهة المستقلة فقط. ولا تتضمن أيًا من reference_image أو video_url أو matches أو face_quality أو face_luminance. أما في جلسات سير العمل فلا توجد مصفوفة منفصلة، إذ يظهر العمر المقدَّر على أنه liveness_checks[].age_estimation في GET /v3/session/{sessionId}/decision/. المصدر: apis/serializers/age_estimation.py:50-55 (AgeEstimationResponseSerializer)، ويُجمَّع الغلاف في apis/views/age_estimation.py:138-174.
| الحقل | النوع | قابل للقيمة الفارغة | الوصف | مثال |
|---|---|---|---|---|
request_id | string (UUID) | لا | معرّف الجلسة المحفوظ عندما تكون save_api_request=true (وهي القيمة الافتراضية)، وإلا فهو UUID مؤقت للربط. | "3b1f1e2c-…" |
age_estimation | object | لا | غلاف النتيجة: status (Approved / Declined)، وmethod (دائمًا PASSIVE)، وscore (الحيوية من 0 إلى 100، وقد تكون null)، وage_estimation (العمر المتوقع بالسنوات للوجه الأكبر، وقد يكون null)، وuser_image (entities[] مع age وbbox بالصيغة [x_min, y_min, x_max, y_max] وconfidence وgender لكل وجه، إضافةً إلى best_angle)، وwarnings[]. | { … } |
vendor_data | string | نعم | قيمة vendor_data المُعادة كما وردت في الطلب. | null |
metadata | object | نعم | قيمة metadata المُعادة كما وردت في الطلب. | null |
created_at | string (ISO 8601) | لا | الطابع الزمني للطلب من جهة الخادم. | "2026-05-17T10:22:13.512941+00:00" |
{
"request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
"age_estimation": {
"status": "Approved",
"method": "PASSIVE",
"score": 94.10,
"age_estimation": 28.7,
"user_image": {
"entities": [
{ "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
],
"best_angle": 0
},
"warnings": []
},
"vendor_data": null,
"metadata": null,
"created_at": "2026-05-17T10:22:13.512941+00:00"
}
المصادقة البيومترية
تعمل المصادقة البيومترية بمسار كشف الحيوية + مطابقة الوجه نفسه المستخدم في KYC القياسي، لكنها مُعدّة لمقارنة الوجه الملتقط بصورة المرجع الموجودة للمستخدم، بدلًا من صورة الوجه من المستند التي تُستخرج حديثًا بتقنية OCR. لا يوجد مُسلسِل مخصص لها، إذ يُرجعGET /v3/session/{sessionId}/decision/ كائنات Liveness check وFace match القياسية ضمن liveness_checks[] وface_matches[]. ويُضبط سير عمل الجلسة بالقيمة workflow_type = "biometric_authentication" (WorkflowTypeChoices، common/config/choices.py:636).
| الحقل | النوع | قابل للقيمة الفارغة | الوصف | مثال |
|---|---|---|---|---|
liveness_checks | array of Liveness check | لا | نتيجة الحيوية لمحاولة المصادقة. | [ { "status": "Approved", … } ] |
face_matches | array of Face match | لا | نتيجة المطابقة مقابل المرجع المسجَّل. تُضبط source_image_session_id على session_id الخاص بالجلسة نفسها: يُسجَّل وجه المرجع (وهو portrait_image المُرسلة، أو الوجه المخزَّن الذي يُعاد استخدامه عبر vendor_data عند عدم توفير portrait_image) ضمن جلسة المصادقة نفسها (face/views/face.py:656-659). | [ { "status": "Approved", "source_image_session_id": "…", … } ] |
status | string | لا | الحالة العامة للجلسة على المستوى الأعلى (راجع تعداد الحالات). | "Approved" |
{
"session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
"status": "Approved",
"liveness_checks": [
{
"status": "Approved",
"method": "PASSIVE",
"score": 95.10,
"reference_image": "https://<media-host>/.../reference.jpg?signature=...",
"video_url": null,
"age_estimation": null,
"matches": [],
"face_quality": 91.20,
"face_luminance": 53.10,
"node_id": "biometric_auth_liveness",
"warnings": []
}
],
"face_matches": [
{
"status": "Approved",
"score": 98.42,
"source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
"source_image": "https://<media-host>/.../source.jpg?signature=...",
"target_image": "https://<media-host>/.../target.jpg?signature=...",
"node_id": "biometric_auth_face_match",
"warnings": []
}
]
}
سجل KYB
يُرجَع لكل شركة مؤكَّدة من السجل في سير عمل KYB. يظهر كعنصرregistry_checks[] في GET /v3/session/{sessionId}/decision/ لجلسات الشركات. المصدر: kyb/serializers/kyb.py:939-964 (RegistryCheckV3Serializer).
| الحقل | النوع | قابل للقيم الفارغة | الوصف | مثال |
|---|---|---|---|---|
status | string | لا | راجع تعداد الحالات. | "Approved" |
node_id | string | null | نعم | معرّف عقدة سير العمل (الإصدار V3). | "first_registry" |
data_resolved | boolean | لا | true عندما يكتمل جلب بيانات السجل (أو عندما تكون قيمة is_from_registry هي false، أي أن البيانات أُدخلت يدوياً). | true |
company | object | لا | الحمولة الكاملة للشركة، راجع كائن الشركة أدناه. | { … } |
ownership_structure | object | نعم | جدول الملكية الذي أثبته السجل: shareholders[] وbeneficial_owners[]، ولكل مالك هويته في السجل ونسبة حصته وshareholding القياسية. | { "shareholders": [...], "beneficial_owners": [] } |
warnings | array | لا | راجع كائن التحذير. | [] |
كائن الشركة
منkyb/serializers/kyb.py:220-321 (KYBCompanyResponseSerializer).
| الحقل | النوع | قابل للقيم الفارغة | الوصف |
|---|---|---|---|
uuid | string (UUID) | لا | معرّف الشركة الداخلي. |
node_id | string | null | نعم | معرّف عقدة سير العمل. |
status | string | لا | حالة الميزة (FeatureStatusChoices). |
registry_status | string | نعم | حالة الشركة في السجل (active، dissolved، …). |
data_resolved | boolean | لا | التعريف نفسه المستخدم في الكائن الأب. |
company_name | string | نعم | الاسم المسجّل للشركة. |
registration_number | string | نعم | معرّف السجل. |
country_code | string (ISO 3166-1 alpha-2) | نعم | الدولة التي تأسست فيها الشركة. |
region | string | نعم | التقسيم الإداري وفق ISO 3166-2 عند الانطباق (مثلاً US-CA). |
company_type | string | نعم | الشكل القانوني (LLC، SL، …). |
incorporation_date | string (YYYY-MM-DD) | نعم | تاريخ التأسيس. |
registered_address | string | نعم | العنوان القانوني المسجّل. |
tax_number | string | نعم | الرقم الضريبي أو رقم ضريبة القيمة المضافة. |
risk_level | string | نعم | تصنيف المخاطر الذي يوفره المزوّد. |
verification_status | string | نعم | قيمة تعداد حالة التحقق الداخلية. |
is_from_registry | boolean | لا | true عندما تأتي البيانات من السجل، في مقابل الإدخال اليدوي. |
fetch_status | string | نعم | pending، resolved، failed. |
alternative_names | string | نعم | أسماء تجارية بديلة مفصولة بفواصل. |
nature_of_business | string | نعم | وصف نصي حر لنشاط الشركة. |
registered_capital | string | نعم | رأس المال المسجّل كنص مقروء. |
registered_capital_amount | string (decimal) | نعم | قيمة رأس المال المسجّل بعد تحليلها. |
registered_capital_currency | string (ISO 4217) | نعم | رمز العملة. |
website | string (URL) | نعم | الموقع الإلكتروني للشركة. |
email | string | نعم | البريد الإلكتروني العام للتواصل. |
phone | string | نعم | رقم الهاتف العام للتواصل. |
legal_entity_identifier | string | نعم | معرّف الكيان القانوني (LEI) عند توفره. |
location_of_registration | string | نعم | مكتب السجل أو المنطقة. |
vat_number | string | نعم | رقم ضريبة القيمة المضافة المقدَّم للشركة. |
vat_validation_status | string | لا | نتيجة التحقق من رقم ضريبة القيمة المضافة، أو من tax_number عند عدم وجوده: valid، invalid، format_valid، invalid_format، could_not_validate، أو not_applicable. راجع التحقق من ضريبة القيمة المضافة والمعرّف الضريبي. |
vat_validated_number | string | نعم | الرقم الذي جرى التحقق منه كما هو معروف للمصدر. |
vat_validation_source | string | نعم | الجهة التي حدّدت الحالة: eu_vies، pl_vat_white_list، no_brreg، ch_uid_register، br_receita_federal، co_rues، cr_hacienda، ec_sri، py_dnit، أو format_rules. |
vat_validated_name | string | نعم | الاسم المسجّل لدى المصدر (فارغ عندما لا يكشف عنه). |
vat_validated_address | string | نعم | العنوان المسجّل لدى المصدر (فارغ عندما لا يُكشف). |
vat_checked_at | string (ISO 8601) | نعم | الطابع الزمني للفحص؛ null عندما لا يُجرى أي فحص. |
financial_summary | object | نعم | لقطة لأبرز المؤشرات المالية الأخيرة عند توفيرها من السجل. |
officers | array of objects | لا | قائمة المسؤولين الآمنة لنموذج B2C: { uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }. |
beneficial_owners | array of objects | لا | قائمة المستفيدين الحقيقيين (UBO) الآمنة لنموذج B2C: { uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }. |
addresses | array of objects | نعم | تفاصيل كل عنوان من السجل. |
industries | array of objects | نعم | تصنيفات بنمط SIC/NAICS. |
accounts | array of objects | نعم | بيانات وصفية عن الحسابات المودَعة. |
registry_data | object | نعم | التفاصيل المُطبَّعة للسجل من Didit (نتيجة الملكية، والتصحيحات المُدخلة في وحدة التحكم، وحقائق السجل التي لا يوجد لها حقل خاص). ليس عقداً ثابتاً. |
user_provided_data | object | نعم | لقطة للحقول التي عدّلها المستخدم. |
confirmed_by_user_at | string (ISO 8601) | نعم | الطابع الزمني لتأكيد المستخدم للبيانات المستخرجة. |
last_console_edit_at | string (ISO 8601) | نعم | الطابع الزمني لآخر تعديل في وحدة التحكم. |
is_editable | boolean | لا | true طالما يستطيع المستخدم النهائي تعديل البيانات المأخوذة من السجل. |
{
"status": "Approved",
"node_id": "first_registry",
"data_resolved": true,
"company": {
"uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
"node_id": "first_registry",
"status": "Approved",
"registry_status": "active",
"data_resolved": true,
"company_name": "Sante Clinics SL",
"registration_number": "B12345678",
"country_code": "ES",
"region": null,
"company_type": "SL",
"incorporation_date": "2018-03-22",
"registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
"tax_number": "B12345678",
"risk_level": "low",
"verification_status": "verified",
"is_from_registry": true,
"fetch_status": "resolved",
"alternative_names": "Sante Clinics",
"nature_of_business": "Medical clinic operations",
"registered_capital": "EUR 50,000",
"registered_capital_amount": "50000.00",
"registered_capital_currency": "EUR",
"website": "https://santeclinics.com",
"email": "info@santeclinics.com",
"phone": "+34911223344",
"legal_entity_identifier": null,
"location_of_registration": "Registro Mercantil de Madrid",
"vat_number": "ESB12345678",
"vat_validation_status": "valid",
"vat_validated_name": "SANTE CLINICS SL",
"vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
"vat_checked_at": "2026-05-17T10:11:05Z",
"financial_summary": null,
"officers": [
{
"uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
"name": "María García López",
"designation": "Administrador único",
"role": "Director",
"nationality": "ESP",
"is_active": true,
"kyc_status": "Approved",
"kyc_session_url": "https://verify.didit.me/s/…"
}
],
"beneficial_owners": [
{
"uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
"name": "María García López",
"first_name": "María",
"last_name": "García López",
"entity_type": "person",
"roles": ["UBO"],
"ownership_min_shares": "75.00",
"ownership_max_shares": "75.00",
"is_active": true,
"kyc_status": "Approved",
"kyc_session_url": "https://verify.didit.me/s/…",
"effective_ownership_percent": 75.0
}
],
"addresses": [],
"industries": [],
"accounts": [],
"registry_data": {},
"user_provided_data": {},
"confirmed_by_user_at": "2026-05-17T10:11:02Z",
"last_console_edit_at": null,
"is_editable": false
},
"ownership_structure": null,
"warnings": []
}
مستند KYB
يُرجَع لكل عقدة تجمع مستندات دعم KYB. يظهر كعنصرdocument_verifications[] في GET /v3/session/{sessionId}/decision/ لجلسات الشركات، بعنصر واحد لكل node_id، ويسرد items[] كل مستند مرفوع. المصدر: kyb/serializers/kyb.py:1053-1068 (DocumentVerificationV3Serializer)، وكل عنصر يتبع kyb/serializers/kyb.py:811-851 (KYBDocumentResponseSerializer).
| الحقل | النوع | قابل للقيم الفارغة | الوصف | مثال |
|---|---|---|---|---|
status | سلسلة نصية | لا | الحالة الإجمالية لمستندات هذه العقدة: لا تكون Approved إلا عندما تكون كل مستندات خط المعالجة مقبولة؛ وتكون Declined إذا كان أي مستند مرفوضاً؛ وتكون In Review في غير ذلك؛ وتكون Not Finished طالما كانت المستندات معلّقة. راجع تعداد الحالة. | "Approved" |
node_id | سلسلة نصية | null | نعم | معرّف عقدة سير العمل (V3). | "first_kyb_documents" |
items | مصفوفة من كائنات عناصر مستندات KYB | لا | إدخال واحد لكل مستند مرفوع أو مطلوب. | […] |
groups | كائن | لا | أعداد لكل مجموعة مستندات: { <group_name>: { total, approved, pending, declined, in_review, other, missing } }. | { "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } } |
required_groups | مصفوفة من السلاسل النصية | لا | مجموعات المستندات التي يتطلبها إعداد سير العمل. | ["incorporation_certificate", "shareholder_register"] |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
كائن عنصر مستند KYB
| الحقل | النوع | قابل للقيمة الفارغة | الوصف |
|---|---|---|---|
uuid | سلسلة نصية (UUID) | لا | معرّف داخلي للمستند. |
document_type | سلسلة نصية | نعم | مجموعة عامة (incorporation_certificate، shareholder_register، …). |
document_subtype | سلسلة نصية | نعم | نوع فرعي خاص بالمزوّد. |
document_group | سلسلة نصية | نعم | نسخة مطابقة لـ document_type (اسم بديل يُحتفظ به للوضوح). |
file_url | سلسلة نصية (URL) | نعم | عنوان URL موقّع مسبقاً للملف المنقّح. |
original_filename | سلسلة نصية | نعم | اسم الملف كما رُفع. |
file_size | عدد صحيح | نعم | حجم الملف بالبايت. |
status | سلسلة نصية | لا | حالة كل مستند (FeatureStatusChoices). |
created_at | سلسلة نصية (ISO 8601) | لا | الطابع الزمني للرفع. |
cross_check_result | كائن | نعم | نتيجة التحقق المتقاطع مقارنةً بالسجل أو بالمستندات الأخرى. |
document_metadata | كائن | نعم | البنية نفسها المفلترة للبيانات الوصفية كما في document_metadata الخاصة بإثبات العنوان. |
description | سلسلة نصية | نعم | وصف يقدمه المراجِع أو النظام. |
is_requested | قيمة منطقية | لا | true عندما يتوقع سير العمل هذا المستند. |
ocr_data | كائن | نعم | الحقول المستخرجة بتقنية OCR عند توفرها. |
is_console_upload | قيمة منطقية | لا | true عندما يكون المستند قد رفعه مراجِع من وحدة التحكم (ويُستثنى من الحكم الإجمالي). |
is_confirmed | قيمة منطقية | لا | true عندما يكون المراجِع قد أكّد المستند صراحةً. |
{
"status": "Approved",
"node_id": "first_kyb_documents",
"items": [
{
"uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9",
"document_type": "incorporation_certificate",
"document_subtype": "registro_mercantil_extract",
"document_group": "incorporation_certificate",
"file_url": "https://<media-host>/.../incorporation.pdf?signature=...",
"original_filename": "incorporation_certificate.pdf",
"file_size": 256412,
"status": "Approved",
"created_at": "2026-05-17T10:08:00Z",
"cross_check_result": { "matches_registry_name": true, "matches_registration_number": true },
"document_metadata": {
"file_size": 256412,
"content_type": "application/pdf",
"is_signed": true,
"is_tampered": false
},
"description": null,
"is_requested": true,
"ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" },
"is_console_upload": false,
"is_confirmed": true
}
],
"groups": {
"incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
},
"required_groups": ["incorporation_certificate", "shareholder_register"],
"warnings": []
}
شخص رئيسي في KYB
يُعاد لكل عقدة من عقد الأشخاص الرئيسيين في سير عمل KYB. يظهر كـkey_people_checks[] في GET /v3/session/{sessionId}/decision/ لجلسات الشركات. المصدر: kyb/serializers/kyb.py:967-1050 (KeyPeopleCheckV3Serializer).
| الحقل | النوع | قابل للقيمة الفارغة | الوصف | مثال |
|---|---|---|---|---|
status | سلسلة نصية | لا | راجع تعداد الحالة. | "Approved" |
node_id | سلسلة نصية | null | نعم | معرّف عقدة سير العمل (V3). | "first_key_people" |
registry | كائن | لا | { officers[], beneficial_owners[] } مستخرجة من السجل. يتبع المسؤولون KYBPersonResponseSerializer (kyb/serializers/kyb.py:533-645)؛ ويتبع المستفيدون الحقيقيون KYBBeneficialOwnerResponseSerializer (kyb/serializers/kyb.py:648-788، الذي يضيف date_of_birth، country_of_birth، email، company_name، registration_number، entity_type، roles، ownership_min_shares، ownership_max_shares، child_beneficial_owners، effective_ownership_percent). ويتضمن كلاهما إثراء AML وKYC لكل طرف (aml_status، kyc_status، kyc_session_url، kyc_session_id، verification_workflow_type، verification_workflow_id، verification_workflow_label، verification_workflow_features، didit_internal_id، kyc_document_type، kyc_nationality، kyc_liveness_passed، kyc_verified_at، kyc_aml_categories، kyc_notification_sent_at). | { "officers": [...], "beneficial_owners": [...] } |
submitted | كائن | لا | { parties[] } - الإدخالات التي أكّدتها الشركة أو قدّمتها عبر تدفق الأشخاص الرئيسيين (صفوف BusinessParty التي تحمل source=USER). يتبع كل طرف BusinessPartySubmissionResponseSerializer (kyb/serializers/party.py:146-194): uuid، entity_type، source، name، first_name، last_name، company_name، registration_number، email، nationality، phone_number، date_of_birth، position، custom_fields، is_active، is_skipped، requires_verification، roles[] ({ role, ownership_percent, voting_percent })، kyc_session_id، kyc_session_status، kyc_session_url، kyc_session_deleted، kyb_sub_session_id، kyb_sub_session_status، kyb_sub_session_url، kyb_sub_session_deleted، verification_workflow_type، verification_workflow_id، verification_workflow_label، verification_workflow_features، didit_internal_id. تعني kyc_session_deleted / kyb_sub_session_deleted أن الجلسة الفرعية قد حُذفت: تبقى حالتها مجمّدة عند قيمتها الأخيرة، ويعود *_session_url المقابل بقيمة null لأن الرابط لم يعد يُحلّ، ولا يعود الطرف يمنع الجلسة الأم (ويتحول الفحص إلى In Review بدلاً من ذلك). أزِل هذه العلامة باستخدام PATCH /v3/session/{id}/kyb/parties/{party_uuid}/. | { "parties": [...] } |
ubo_kyc_summary | كائن | نعم | أعداد عبر المستفيدين الحقيقيين النشطين المرتبطين بـ KYC: { total, approved, flagged, pending }. تكون القيمة null عندما لا يكون لأي مستفيد حقيقي نشط KYC مرتبط. | { "total": 2, "approved": 2, "flagged": 0, "pending": 0 } |
warnings | مصفوفة | لا | راجع كائن التحذير. | [] |
{
"status": "Approved",
"node_id": "first_key_people",
"registry": {
"officers": [
{
"uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
"name": "María García López",
"designation": "Administrador único",
"role": "Director",
"nationality": "ESP",
"appointment_date": "2018-03-22",
"termination_date": null,
"is_active": true,
"address": "Calle Mayor 1, 28001 Madrid",
"aml_status": "Approved",
"kyc_status": "Approved",
"kyc_session_url": "https://verify.didit.me/s/…",
"kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
"verification_workflow_type": "kyc",
"verification_workflow_id": "11111111-1111-1111-1111-111111111111",
"verification_workflow_label": "KYB officer KYC",
"verification_workflow_features": [
{ "feature": "ID_VERIFICATION", "status": "Approved" },
{ "feature": "LIVENESS", "status": "Approved" },
{ "feature": "FACE_MATCH", "status": "Approved" }
],
"didit_internal_id": "user-12345",
"kyc_document_type": "Passport",
"kyc_nationality": "ESP",
"kyc_liveness_passed": true,
"kyc_verified_at": "2026-05-17T10:10:11Z",
"kyc_aml_categories": [],
"kyc_notification_sent_at": "2026-05-15T08:00:00Z"
}
],
"beneficial_owners": []
},
"submitted": {
"parties": [
{
"uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
"entity_type": "person",
"source": "USER",
"name": "María García López",
"first_name": "María",
"last_name": "García López",
"company_name": null,
"registration_number": null,
"email": "maria.garcia@example.com",
"nationality": "ESP",
"phone_number": null,
"date_of_birth": "1990-05-12",
"position": "Administrador único",
"custom_fields": {},
"is_active": true,
"is_skipped": false,
"requires_verification": true,
"roles": [
{ "role": "UBO", "ownership_percent": 75.0, "voting_percent": null }
],
"kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
"kyc_session_status": "Approved",
"kyc_session_url": "https://verify.didit.me/s/…",
"kyb_sub_session_id": null,
"kyb_sub_session_status": null,
"kyb_sub_session_url": null,
"verification_workflow_type": "kyc",
"verification_workflow_id": "11111111-1111-1111-1111-111111111111",
"verification_workflow_label": "KYB officer KYC",
"verification_workflow_features": [
{ "feature": "ID_VERIFICATION", "status": "Approved" },
{ "feature": "LIVENESS", "status": "Approved" }
],
"didit_internal_id": "user-12345"
}
]
},
"ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 },
"warnings": []
}
الحقول على مستوى القرار
تقع هذه المفاتيح بجوار مصفوفات الميزات فيGET /v3/session/{sessionId}/decision/ وداخل حقل decision في webhook.
| الحقل | النوع | قابل لأن يكون null | الوصف |
|---|---|---|---|
status_override | كائن | نعم | { overridden_at, automatic_status } بعد أن يحدّد المراجِع قيمة status يدوياً؛ وتكون القيمة null عندما تكون الحالة هي الحالة التلقائية. |
decision_trace | كائن | لا | طريقة الوصول إلى الحالة: status، وdecided_by (manual أو automatic أو investigator)، وdecided_at، وautomatic_status، وterminal_node_id، وactor، وwarning_counts وstatus_warnings. |
linked_records | كائن | نعم | ملخصات same_face وearlier_verifications وnetworks؛ وتكون القيمة null عندما لا يوجد ما يُعرض. |
biometric_retention | كائن | لا | { jurisdictions, deletes_at }. يمثل deletes_at التاريخ الذي تُحذف فيه البيانات البيومترية الحية للجلسة، وتكون القيمة null عندما لا يوجد تاريخ منطبق بعد. |
database_validation_not_performed_reason | كائن | نعم | { code, message } يوضح سبب عدم إنتاج التحقق من قواعد البيانات المُكوَّن أي نتيجة. |
assignee، waiting_since، sla_due_at | كائن، تاريخ ووقت | نعم | مراجِع Console الذي يتولى الجلسة، وعدّاد مراجعتها؛ ويكون العدّاد null إلا إذا كانت الجلسة في حالة In Review. |
shared_from_session، shared_from_session_number | UUID، عدد صحيح | نعم | الجلسة المصدر للجلسة المستوردة. |
sandbox_scenario | نص | نعم | السيناريو الذي أُنشئت به جلسة البيئة التجريبية. |
fraud_check | كائن | نعم | نتيجة واجهة Fraud Check API؛ وتكون القيمة null لكل جلسة أخرى. |
full_session_video، full_session_video_recorded_at | URL، تاريخ ووقت | نعم | تسجيل فيديو الجلسة الكامل ووقت تسجيله. يُعاد هذان الحقلان فقط إذا كانت مؤسستك تسجّل فيديو الجلسة الكامل. |
الموافقة البيومترية
يحمل كل قرار تحقق من المستخدمين وكل webhook للجلسة كائنbiometric_consent واحدًا (وليس مصفوفة): ما إذا كانت الجلسة تتطلب موافقة بيومترية صريحة، والسبب، وأدلة الإجابة. يكون null عندما لم تُقيَّم الجلسة قط، مثل سير عمل بلا التقاط للوجه. المصدر: BiometricConsentDecisionSerializer (sessions/serializers/biometric_consent.py). تُشرح الخطوة ومتى تظهر وما تعنيه كل حالة في الموافقة البيومترية.
الحقول التي لا توجد لها قيمة مسجلة تكون null، وليس نصًا فارغًا أبدًا.
| الحقل | النوع | الوصف |
|---|---|---|
required | boolean | ما إذا كان يجب على الجلسة جمع موافقة بيومترية صريحة. لا تعود أبدًا إلى false. |
trigger | string (تعداد) | null | سبب اشتراط الموافقة، أو كيفية تلبيتها: declared_state، ip_state، ip_unknown، document_issuer، forced (وضع التطبيق «دائمًا»)، customer_collected (أرسلتَ biometric_consent عند إنشاء الجلسة). تكون null ما دامت الموافقة غير مطلوبة. |
status | string (تعداد) | not_required، وpending (مطلوبة ولم تُمنح)، وgiven، وdeclined (سُجّل رفض؛ لا تعرض أي شاشة من Didit خيار الرفض حاليًا). |
given_at | string (ISO 8601) | null | وقت منح الموافقة. بالنسبة إلى customer_collected، هو القيمة given_at التي أرسلتها. |
declined_at | string (ISO 8601) | null | وقت تسجيل الرفض. |
text_version | string | null | معرّف إصدار نص الموافقة الذي أجاب عنه الشخص، أو الذي أرسلته. |
text_hash | string | null | قيمة SHA-256 (بالنظام السادس عشر) للنص الدقيق المعروض، باللغة التي عُرض بها. |
locale | string | null | اللغة التي عُرض بها النص. |
policy_url | string | null | سياسة البيانات البيومترية التي ربطتها الخطوة. |
step | string | null | خطوة سير العمل التي كانت عليها الجلسة عندما أجاب الشخص (مثلًا LIVENESS). |
node_id | string | null | عقدة مخطط سير العمل التي كانت عليها الجلسة عندما أجاب الشخص. |
ip_address | string | null | عنوان IP الذي صدرت منه الإجابة. |
ip_country_code | string | null | رمز الدولة وفق ISO 3166-1 alpha-2 لعنوان IP الذي صدرت منه الإجابة. |
ip_state | string | null | رمز التقسيم الإداري وفق ISO 3166-2 لعنوان IP الذي صدرت منه الإجابة (مثلًا US-IL). |
ip_city | string | null | مدينة عنوان IP الذي صدرت منه الإجابة. |
user_agent | string | null | وكيل المستخدم لطلب الإجابة. |
detected_ip_address | string | null | عنوان IP للشخص الذي قُيّم الشرط انطلاقًا منه آخر مرة. قد يختلف عن ip_address إذا أجاب الشخص من جهاز آخر. |
detected_country_code | string | null | رمز الدولة وفق ISO 3166-1 alpha-2 لعنوان IP المكتشف. |
detected_state | string | null | رمز التقسيم الإداري وفق ISO 3166-2 لعنوان IP المكتشف. |
detected_city | string | null | مدينة عنوان IP المكتشف. |
declared_state | string | null | رمز التقسيم الإداري وفق ISO 3166-2 الذي صرّحتَ به: user_state، أو ولاية عنوان أمريكي في expected_details. |
document_state | string | null | رمز التقسيم الإداري وفق ISO 3166-2 الذي أصدر وثيقة الهوية، ويُقرأ عند التقاط الهوية. |
jurisdictions | array of string | الولايات الأمريكية (رموز USPS، مثلًا IL) التي ينطبق قانونها البيومتري على الشخص. تُعاد US عندما تضع الأدلة الشخص في الولايات المتحدة دون معرفة الولاية. تكون فارغة عندما لا ينطبق أي منها. |
retention_months | integer | null | أقصر حد للاحتفاظ بالبيانات البيومترية، بالأشهر، من بين عناصر jurisdictions. تكون null عندما لا ينطبق أي منها. |
reason | string (تعداد) | null | BIOMETRIC_CONSENT_UNSUPPORTED_SDK: كانت الموافقة مطلوبة، وقام SDK أصلي أقل من 4.10.0، أو SDK لم يُبلغ عن إصداره، بالتقاط وجه دون الخطوة؛ تبقى status بقيمة pending، أو تصبح given إذا وافق الشخص لاحقًا في صفحة التحقق المستضافة. BIOMETRIC_CONSENT_DECLINED: سُجّل رفض (ويحل محل سبب SDK). تكون null في غير ذلك، وتكون دائمًا null عندما لم تكن الجلسة تتطلب الموافقة. |
decline_reason | string | null | تكون BIOMETRIC_CONSENT_DECLINED عندما أنهى رفضٌ مسجَّل الجلسة، وإلا فتكون null. |
face_data_deleted_at | string (ISO 8601) | null | وقت حذف صور الوجه ومقاطع الفيديو وقوالب الوجه الخاصة بالجلسة نتيجة الرفض. تكون null ما لم يُسجَّل رفض. |
{
"required": true,
"trigger": "ip_state",
"status": "pending",
"given_at": null,
"declined_at": null,
"text_version": null,
"text_hash": null,
"locale": null,
"policy_url": null,
"step": null,
"node_id": null,
"ip_address": null,
"ip_country_code": null,
"ip_state": null,
"ip_city": null,
"user_agent": null,
"detected_ip_address": "203.0.113.42",
"detected_country_code": "US",
"detected_state": "US-IL",
"detected_city": "Chicago",
"declared_state": null,
"document_state": null,
"jurisdictions": ["IL"],
"retention_months": 36,
"reason": "BIOMETRIC_CONSENT_UNSUPPORTED_SDK",
"decline_reason": null,
"face_data_deleted_at": null
}
{
"required": true,
"trigger": "declared_state",
"status": "given",
"given_at": "2026-10-13T18:31:07.412000Z",
"declined_at": null,
"text_version": "bio-consent-2026-10-12",
"text_hash": "9b2f0c5e4d8a7f61c3e2b4a5d6f7081923a4b5c6d7e8f90a1b2c3d4e5f6a7b8c",
"locale": "en",
"policy_url": "https://didit.me/legal/biometric-data-policy",
"step": "LIVENESS",
"node_id": "feature_liveness_1",
"ip_address": "198.51.100.23",
"ip_country_code": "ES",
"ip_state": "ES-M",
"ip_city": "Madrid",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
"detected_ip_address": "198.51.100.23",
"detected_country_code": "ES",
"detected_state": "ES-M",
"detected_city": "Madrid",
"declared_state": null,
"document_state": null,
"jurisdictions": ["IL"],
"retention_months": 36,
"reason": null,
"decline_reason": null,
"face_data_deleted_at": null
}
مرجع قيم الحالة
تشترك مجموعتا قيم مترابطتان في اسم الحقلstatus. تستخدم كل كائنات التقارير الخاصة بالميزات على هذه الصفحة تعداد مستوى الميزة، بينما يستخدم status ذو المستوى الأعلى للجلسة الأم تعداد الجلسة الأوسع.
حالات مستوى الميزة
تُستخدم في حقلstatus لكل كائن تقرير. المصدر: common/config/choices.py:343-348 (FeatureStatusChoices).
| القيمة | المعنى |
|---|---|
Not Finished | تم توفير الميزة لكن المستخدم لم يُكملها بعد. |
Approved | اجتازت الميزة جميع الفحوصات. |
Declined | أخفقت الميزة في فحص حاسم واحد على الأقل (راجع warnings[] مع log_type: "error"). |
In Review | أطلقت الميزة إشارات فشل ناعم وهي بانتظار المراجعة اليدوية (راجع warnings[] مع log_type: "warning"). |
Resub Requested | طلب مراجِع من المستخدم إعادة تقديم هذه الميزة. |
Expired أيضًا في التحقق من رقم الهاتف والبريد الإلكتروني والهوية عندما تنتهي مهلة خطوتها (PhoneStatusChoices في common/config/choices.py:377-382، وEmailStatusChoices في common/config/choices.py:434-439).
حالات مستوى الجلسة
تُستخدم في حقلstatus ذي المستوى الأعلى للجلسة الأم. المصدر: common/config/choices.py:106-117 (StatusChoices).
| القيمة | المعنى |
|---|---|
Not Started | أُنشئت الجلسة لكن المستخدم لم يبدأها بعد. |
In Progress | بدأ المستخدم المسار، والنتيجة لم تُحسم بعد. |
Approved | اجتازت الجلسة جميع الفحوصات. |
Declined | أخفقت الجلسة في فحص حاسم واحد على الأقل. |
In Review | الجلسة بانتظار المراجعة اليدوية. |
Expired | انتهت صلاحية الجلسة قبل اكتمالها. |
Abandoned | غادر المستخدم المسار دون إكماله. |
Kyc Expired | انقضت فترة صلاحية KYC (وتُستخدم في مسارات إعادة التحقق). |
Resubmitted | أعاد المستخدم التقديم بعد رفض سابق، وحلّت محلّها جلسة أحدث. |
Awaiting User | ينتظر النظام إجراءً من جهة المستخدم (مثل إدخال رمز OTP). |
القيم النهائية للجلسة هي
Approved وDeclined وIn Review وExpired وKyc Expired وAbandoned. يمكن أن تصل الجلسة إلى قرارها الإجمالي بينما تبقى ميزة فردية في حالة In Review.