KYC API Docs

توثيق KYC Service REST API

تم تجميعه من وحدات REST controller الفعلية داخل `workspace/service/service/kycService` ويغطي واجهات المستخدم وفحص الحيوية وواجهات المراجعة الخلفية.

العودة إلى صفحة AMLالتواصل للدمج
المسار الأساسي/api/web/kycService
غلاف الاستجابةApiResponse { code, message, data }
صيغة الرفعmultipart/form-data
نطاق الإدارة/admin/kyc
Scanned Source

نظرة تكامل مستندة إلى المتحكمات الفعلية

هذه الصفحة مبنية من المسارات الحقيقية في `ApiKycController` و `ApiKycLivenessController` و `AdminKycController` وليست وصفاً تسويقياً عاماً.

01

إنشاء ملف KYC

ابدأ باستدعاء `/submit` للحصول على `profileId` الذي سيستخدم لاحقاً في المستندات وفحص الحيوية والاستعلام عن الحالة.

02

إرسال بيانات المستند

إذا كان لديك نظام استضافة ملفات جاهز يمكنك استخدام `/document`، أما المسار الموصى به فهو `/document/upload` لرفع الصور وتشغيل OCR معاً.

03

التأكيد ثم الإرسال للمراجعة

استخدم `/document/confirm` ليتحقق المستخدم من البيانات المستخرجة ثم `/document/submit` لتحويلها إلى اعتماد تلقائي أو مراجعة يدوية.

04

فحص الحيوية والحالة النهائية

يتكون تدفق الحيوية من `/liveness/start` و `/liveness/verify` بينما ترجع الحالة النهائية عبر `/status/`.

مصدر الفحص: /workspace/service/service/kycService/src/main/java/com/sargia/finger/kycService/rest

توجد أيضاً واجهات مرآة داخل الخدمة على `/api/web/kycService/list` و `/detail/` و `/status/update` بينما يظل نطاق الإدارة المخصص هو `/admin/kyc`.

Envelope

هيكل الاستجابة الموحد

كل المتحكمات التي تم فحصها تعيد `ApiResponse` وتوضع البيانات الفعلية داخل `data`.

الحقلالنوعمثال
codenumberالقيمة 0 للنجاح، وغير ذلك للفشل أو الاستثناءات المنطقية
messagestringرسائل مثل success و query success و Document uploaded successfully
dataobjectالحمولة الفعلية مثل profileId أو status أو detail أو list
Core Web API

واجهات المستخدم

مرتبطة بـ `ApiKycController` وتشمل إنشاء الملف ورفع المستندات وتأكيد الحقول والإرسال والاستعلام عن الحالة.

POST
عامموصى به

Create profile

/api/web/kycService/submit

Create a KYC profile and return the profileId used by all downstream calls. 建立 KYC 档案并返回后续接口共用的 profileId。

الحقلالنوعمطلوبالموضعمثال
userIdstringنعمbodyuser_10001
countrystringنعمbodySG

أهم الحقول الراجعة

profileId

ملاحظات

  • Returns `ApiResponse.ok().data("profileId", profileId)` on success.
POST
عام

Upload document metadata

/api/web/kycService/document

Submit document metadata with image URLs or base64 references. 提交证件元数据，适合已有文件托管链路的接入方。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمbodyprofile_123456
docTypestringنعمbodyPASSPORT
docNumberstringلاbodyE12345678
frontImageUrlstringنعمbodyhttps://cdn.example/front.jpg
backImageUrlstringلاbodyhttps://cdn.example/back.jpg
expiryDatedateلاbody2030-12-31
issueCountrystringلاbodySG

أهم الحقول الراجعة

codemessage

ملاحظات

  • The controller stores document metadata through `kycService.uploadDocument(...)`.
POST
عامموصى به

Upload and verify document

/api/web/kycService/document/upload

Upload front/back images, run OCR and quality checks, and return extracted identity fields. 上传证件图片并同步返回 OCR 与质量校验结果。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمmultipartprofile_123456
docTypestringنعمmultipartID_CARD
countrystringنعمmultipartSG
frontImagefileنعمmultipartid-front.jpg
backImagefileلاmultipartid-back.jpg

أهم الحقول الراجعة

documentIdverifiednameidNumberbirthDateexpiryDatefrontQualityScorebackQualityScoreerrors

ملاحظات

  • When OCR succeeds, the response includes extracted identity fields for user confirmation.
  • When verification fails, the controller returns `errorCode`, quality scores, and `errors`.
POST
عام

Confirm extracted fields

/api/web/kycService/document/confirm

Let the user confirm or edit OCR results before the final review step. 用户确认或修正 OCR 字段，必要时触发人工审核。

الحقلالنوعمطلوبالموضعمثال
documentIdnumberنعمquery123456789
namestringلاbodyAlex Tan
idNumberstringلاbodyS1234567A
birthDatedateلاbody1990-01-01
expiryDatedateلاbody2030-12-31
issuerstringلاbodyICA Singapore
nationalitystringلاbodySGP
userModifiedbooleanلاbodytrue

أهم الحقول الراجعة

documentIdstatusverifiedextractedInfo

ملاحظات

  • If `userModified` is true, the service message indicates the record will enter manual review.
POST
عام

Submit document for review

/api/web/kycService/document/submit

Finalize the document step after user confirmation. 完成用户确认后，正式提交证件审核并返回最终状态。

الحقلالنوعمطلوبالموضعمثال
documentIdnumberنعمquery123456789

أهم الحقول الراجعة

documentIdstatusverifiederrors

ملاحظات

  • The controller maps status 1/2/3 to auto-approved, manual review, and user-modified review.
GET
عامموصى به

Get verification status

/api/web/kycService/status/{profileId}

Fetch the current KYC status, liveness result, and face-match information by profileId. 查询整个 KYC 档案的当前状态。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمpathprofile_123456

أهم الحقول الراجعة

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

ملاحظات

  • Returns `data.status` as a `KycStatusDto` object rather than a flat primitive field.
POST
Callback

Liveness callback

/api/web/kycService/callback/liveness

Server-to-server callback used to persist liveness results. 这是服务侧回调入口，不是前端页面直接调用的接口。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمbodyprofile_123456
sessionIdstringلاbody550e8400-e29b-41d4-a716-446655440000
confidencenumberلاbody96.2
resultstringلاbodysuccess
errorMessagestringلاbodytimeout

أهم الحقول الراجعة

codemessage

ملاحظات

  • `LivenessCallback.toEntity()` is currently a placeholder conversion in the scanned service code.
Liveness API

واجهات فحص الحيوية

مرتبطة بـ `ApiKycLivenessController` وتشمل إنشاء الجلسة والتحقق من الفيديو والاستعلام عن الجلسة.

POST
عامموصى به

Start liveness session

/api/web/kycService/liveness/start

Create a five-minute session and return three randomized challenge actions. 创建 5 分钟有效的活体动作会话。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمqueryprofile_123456

أهم الحقول الراجعة

sessionIdactionsexpireTimetimeout

ملاحظات

  • The controller shuffles `LivenessActionEnum` values and returns exactly three actions.
POST
عامموصى به

Verify liveness videos

/api/web/kycService/liveness/verify

Upload three challenge videos and return the aggregated liveness result. 上传三个动作视频并返回活体验证结果。

الحقلالنوعمطلوبالموضعمثال
sessionIdstringنعمmultipart550e8400-e29b-41d4-a716-446655440000
profileIdstringنعمmultipartprofile_123456
video1fileنعمmultipartblink.mp4
video2fileنعمmultipartsmile.mp4
video3fileنعمmultipartturn-left.mp4

أهم الحقول الراجعة

verifiedconfidencecompletedActionsfailedActionsmessage

ملاحظات

  • Failure uses `ApiResponse.error().code(20001)` with the liveness result still returned in `data.list`.
GET
عام

Get liveness session

/api/web/kycService/liveness/session/{sessionId}

Read the current liveness session from cache and inspect its status. 查询缓存中的活体会话状态。

الحقلالنوعمطلوبالموضعمثال
sessionIdstringنعمpath550e8400-e29b-41d4-a716-446655440000

أهم الحقول الراجعة

sessionIdprofileIdactionsexpireTimestatuscreateTime

ملاحظات

  • If the session is missing or expired, the controller returns an error message instead of null data.
Admin Review API

واجهات المراجعة الخلفية

مرتبطة بـ `AdminKycController` وتشمل القائمة والتفاصيل وتحديث حالة المراجعة.

POST
إدارة

List KYC records

/admin/kyc/list

Query paginated KYC records for operations teams. 后台分页查询 KYC 档案列表并支持按 profileIds 过滤。

الحقلالنوعمطلوبالموضعمثال
profileIdsarray<string>لاbody["profile_123","profile_456"]
pagenumberلاbody1
limitnumberلاbody20

أهم الحقول الراجعة

totalpagescurrentsizerecords

ملاحظات

  • The same list capability is also mirrored in `ApiKycController` at `/api/web/kycService/list`.
GET
إدارة

Get KYC detail

/admin/kyc/detail/{profileId}

Fetch the full review payload for one profile, including document, liveness, and face-match data. 获取单个 KYC 档案的完整审核详情。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمpathprofile_123456

أهم الحقول الراجعة

detail

ملاحظات

  • A mirrored detail endpoint also exists at `/api/web/kycService/detail/{profileId}`.
POST
إدارة

Update review status

/admin/kyc/update-status

Approve, reject, or reset the KYC review state from the admin namespace. 在后台审核链路中更新 KYC 状态。

الحقلالنوعمطلوبالموضعمثال
profileIdstringنعمbodyprofile_123456
statusstringنعمbody2
remarkstringلاbodyManual review passed

أهم الحقول الراجعة

codemessage

ملاحظات

  • Allowed status values in the DTO are `-1`, `0`, and `2`.
  • The web-controller mirror path is `/api/web/kycService/status/update`.

تنصل:

Finger Trader هي منصة برمجيات بنية تحتية مصممة للمؤسسات، توفر قدرات الدعم التقني على مستوى النظام والبيانات، ولا تنطوي على خدمات مالية أو مشورة استثمارية أو أعمال وساطة أو تنفيذ صفقات.

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

قبل اتخاذ أي قرارات استثمارية بناءً على هذه المعلومات، يجب عليك طلب المشورة من المتخصصين المؤهلين والمعتمدين في الأوراق المالية وإجراء العناية الواجبة الشاملة.

لا ينبغي اعتبار أي معلومات تقدمها Finger Trader بمثابة نصيحة استثمارية، أو التماس للشراء أو البيع، أو عرض، ولا كتوصية أو تأييد أو رعاية لأي ضمان أو شركة أو صندوق.

لا تتحمل شركة Finger Trader أي مسؤولية عن أي قرارات استثمارية تتخذها بناءً على هذه المعلومات.

جميع قرارات الاستثمار والأبحاث ذات الصلة هي مسؤوليتك وحدك.

Finger شركة تطوير تقني ولا تقدم أي شكل من أشكال الاستثمار أو خدمات الوساطة.

© 2026 Sargia Inc.

All rights reserved.

Address: 〒560-0011 Osaka, Toyonaka, Uenonishi, 3-chōme−2−50

Post code: 560-0011

سياسة الخصوصية ‧ سياسة ملفات تعريف الارتباط