KYC API Docs

KYC Service REST API 文檔

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

返回 OCR 驗證聯絡接入

主路徑/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/{profileId}` 拉取。

掃描來源： /workspace/service/service/kycService/src/main/java/com/sargia/finger/kycService/rest

控制器中同時存在一組 `/api/web/kycService/list`、`/detail/{profileId}`、`/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`，覆蓋建立檔案、證件上傳、欄位確認、送審與狀態查詢。

7 個已整理接口

POST/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

當前接口

提交證件元資料

提交證件元資料與圖片 URL 或 base64 引用，適合已有文件托管鏈路的接入方。

前台

字段	類型	必填	位置	示例
`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}

當前接口

查詢驗證狀態

根據 `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`，負責建立動作會話、提交視頻驗證與會話查詢。

3 個已整理接口

POST/api/web/kycService/liveness/start

當前接口

建立活體會話

建立一個 5 分鐘有效的活體動作會話，並返回 3 個隨機挑戰動作。

前台推薦

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

返回重點

sessionIdactionsexpireTimetimeout

補充說明

控制器會打亂 `LivenessActionEnum` 並固定返回 3 個動作。

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

補充說明

若會話缺失或過期，控制器會返回錯誤訊息，而不是空數據。

Admin Review API

後台審核接口

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

3 個已整理接口

POST/admin/kyc/list

當前接口

查詢 KYC 列表

供運營團隊分頁查詢 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/admin/kyc/detail/{profileId}

當前接口

查詢 KYC 詳情

獲取單個 `profileId` 的完整審核詳情，包含證件、活體與人臉比對資料。

後台

字段	類型	必填	位置	示例
`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`。

POST/api/web/kycService/submit

建立檔案

建立 KYC 檔案並返回後續接口共用的 `profileId`。

請求示例

curl -X POST "https://api.fingerkyc.com/api/web/kycService/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FINGER_KYC_TOKEN" \
  -d '{
  "userId": "user_10001",
  "country": "SG"
}'

返回重點

profileId