What is Finger Trader?

Finger Trader is a SaaS trading platform for brokers and market makers, offering real-time data, multi-asset trading, community, and referral tools.

Who can use Finger Trader?

Finger Trader is designed for brokers, institutions, market makers, and individual traders seeking a seamless trading ecosystem.

KYC API Docs

KYC Service REST API 文檔

根據 workspace/service 下 kycService 的實際 REST 控制器整理，涵蓋前台接入、活體檢測與後台審核介面。

返回 AML 頁面

主路徑/api/web/kycService

返回封裝ApiResponse { code, message, data }

上傳格式multipart/form-data

後台命名空間/admin/kyc

Scanned Source

基於真實控制器整理的接入概覽

本頁不是手寫宣傳文案，而是從 `ApiKycController`、`ApiKycLivenessController` 與 `AdminKycController` 的實際路由整理出來的站內文檔頁。

建立 KYC 檔案

先呼叫 `/submit` 建立 `profileId`，後續證件、活體與狀態查詢都圍繞這個主鍵進行。

提交證件資料

已有文件系統可走 `/document`，標準接入建議直接使用 `/document/upload` 完成圖片上傳、OCR 與質量校驗。

確認並送審

用 `/document/confirm` 讓使用者核對欄位，再由 `/document/submit` 決定自動通過或轉人工審核。

活體與最終狀態

活體流程由 `/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` 節點內。

欄位	類型	示例
`code`	number	0 代表成功，非 0 代表失敗或業務異常
`message`	string	success、查詢成功、Document uploaded successfully 等訊息
`data`	object	具體業務資料，例如 profileId、status、detail 或 list

Core Web API

前台接入介面

對應 `ApiKycController`，覆蓋建立檔案、證件上傳、欄位確認、送審與狀態查詢。

POST

前台推薦

建立 KYC 檔案

/api/web/kycService/submit

建立 KYC 檔案並返回後續介面共用的 profileId。

欄位	類型	必填	位置	示例
`userId`	string	是	body	user_10001
`country`	string	是	body	SG

返回重點

profileId

補充說明

成功時回傳 `ApiResponse.ok().data("profileId", profileId)`。

POST

前台

上傳證件資料

/api/web/kycService/document

提交證件元數據，適合已有文件托管鏈路的接入方。

欄位	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`docType`	string	是	body	PASSPORT
`docNumber`	string	否	body	E12345678
`frontImageUrl`	string	是	body	https://cdn.example/front.jpg
`backImageUrl`	string	否	body	https://cdn.example/back.jpg
`expiryDate`	date	否	body	2030-12-31
`issueCountry`	string	否	body	SG

返回重點

codemessage

補充說明

控制器透過 `kycService.uploadDocument(...)` 儲存證件資料。

POST

前台推薦

上傳並驗證證件

/api/web/kycService/document/upload

上傳證件圖片並同步回傳 OCR 與質量校驗結果。

欄位	類型	必填	位置	示例
`profileId`	string	是	multipart	profile_123456
`docType`	string	是	multipart	ID_CARD
`country`	string	是	multipart	SG
`frontImage`	file	是	multipart	id-front.jpg
`backImage`	file	否	multipart	id-back.jpg

返回重點

documentIdverifiednameidNumberbirthDateexpiryDatefrontQualityScorebackQualityScoreerrors

補充說明

OCR 成功時，回應會包含提取出的身份欄位，供使用者確認。
驗證失敗時，控制器會回傳 `errorCode`、品質分數及 `errors`。

POST

前台

確認提取欄位

/api/web/kycService/document/confirm

用戶確認或修正 OCR 欄位，必要時觸發人工審核。

欄位	類型	必填	位置	示例
`documentId`	number	是	query	123456789
`name`	string	否	body	Alex Tan
`idNumber`	string	否	body	S1234567A
`birthDate`	date	否	body	1990-01-01
`expiryDate`	date	否	body	2030-12-31
`issuer`	string	否	body	ICA Singapore
`nationality`	string	否	body	SGP
`userModified`	boolean	否	body	true

返回重點

documentIdstatusverifiedextractedInfo

補充說明

若 `userModified` 為 true，服務訊息會指出該筆資料將進入人工審核。

POST

前台

提交證件審核

/api/web/kycService/document/submit

完成用戶確認後，正式提交證件審核並返回最終狀態。

欄位	類型	必填	位置	示例
`documentId`	number	是	query	123456789

返回重點

documentIdstatusverifiederrors

補充說明

控制器會將狀態 1/2/3 對應至自動通過、人工審核及使用者修改後審核。

GET

前台推薦

查詢驗證狀態

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

查詢整個 KYC 檔案的當前狀態。

欄位	類型	必填	位置	示例
`profileId`	string	是	path	profile_123456

返回重點

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

補充說明

`data.status` 會以 `KycStatusDto` 物件回傳，而非單一基本欄位。

POST

回調

活體檢測回調

/api/web/kycService/callback/liveness

這是服務侧回調入口，不是前端页面直接調用的介面。

欄位	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`sessionId`	string	否	body	550e8400-e29b-41d4-a716-446655440000
`confidence`	number	否	body	96.2
`result`	string	否	body	success
`errorMessage`	string	否	body	timeout

返回重點

codemessage

補充說明

目前服務程式碼中的 `LivenessCallback.toEntity()` 僅為佔位轉換。

Liveness API

活體檢測介面

對應 `ApiKycLivenessController`，負責建立動作會話、提交視頻驗證與會話查詢。

POST

前台推薦

創建活體檢測會話

/api/web/kycService/liveness/start

創建 5 分鐘有效的活體動作會話。

欄位	類型	必填	位置	示例
`profileId`	string	是	query	profile_123456

返回重點

sessionIdactionsexpireTimetimeout

補充說明

控制器會隨機排列 `LivenessActionEnum` 值，並回傳三個動作。

POST

前台推薦

驗證活體視頻

/api/web/kycService/liveness/verify

上傳三個動作視頻並返回活體驗證結果。

欄位	類型	必填	位置	示例
`sessionId`	string	是	multipart	550e8400-e29b-41d4-a716-446655440000
`profileId`	string	是	multipart	profile_123456
`video1`	file	是	multipart	blink.mp4
`video2`	file	是	multipart	smile.mp4
`video3`	file	是	multipart	turn-left.mp4

返回重點

verifiedconfidencecompletedActionsfailedActionsmessage

補充說明

失敗時會使用 `ApiResponse.error().code(20001)`，活體檢測結果仍會放在 `data.list` 回傳。

GET

前台

查詢活體會話

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

查詢缓存中的活體會話狀態。

欄位	類型	必填	位置	示例
`sessionId`	string	是	path	550e8400-e29b-41d4-a716-446655440000

返回重點

sessionIdprofileIdactionsexpireTimestatuscreateTime

補充說明

若工作階段不存在或已過期，控制器會回傳錯誤訊息，而非 null 資料。

Admin Review API

後台審核介面

對應 `AdminKycController`，提供後台列表、詳情與審核狀態更新。

POST

後台

查詢 KYC 檔案

/admin/kyc/list

後台分页查詢 KYC 檔案列表並支援按 profileIds 過滤。

欄位	類型	必填	位置	示例
`profileIds`	array<string>	否	body	["profile_123","profile_456"]
`page`	number	否	body	1
`limit`	number	否	body	20

返回重點

totalpagescurrentsizerecords

補充說明

相同的列表功能也可透過 `ApiKycController` 的 `/api/web/kycService/list` 使用。

GET

後台

查詢 KYC 檔案詳情

/admin/kyc/detail/{profileId}

獲取單個 KYC 檔案的完整審核詳情。

欄位	類型	必填	位置	示例
`profileId`	string	是	path	profile_123456

返回重點

detail

補充說明

對應的詳情端點也可透過 `/api/web/kycService/detail/{profileId}` 使用。

POST

後台

更新審核狀態

/admin/kyc/update-status

在後台審核鏈路中更新 KYC 狀態。

欄位	類型	必填	位置	示例
`profileId`	string	是	body	profile_123456
`status`	string	是	body	2
`remark`	string	否	body	Manual review passed

返回重點

codemessage

補充說明

DTO 允許的狀態值為 `-1`、`0` 和 `2`。
Web 控制器的對應路徑為 `/api/web/kycService/status/update`。