KYC API Docs

KYC Service REST API ドキュメント

`workspace/service/service/kycService` 内の実際の REST コントローラーを基に整理し、ユーザー導入、活体検知、管理審査 API をまとめています。

AML ページへ戻る導入相談
ベースパス/api/web/kycService
レスポンス形式ApiResponse { code, message, data }
アップロード形式multipart/form-data
管理名前空間/admin/kyc
Scanned Source

実際のコントローラーに基づく接続概要

このページは `ApiKycController`、`ApiKycLivenessController`、`AdminKycController` の実ルートから整理したもので、汎用的な紹介文ではありません。

01

KYC プロファイル作成

最初に `/submit` を呼び出して `profileId` を取得します。以後の証憑、活体、状態照会はこの ID を使用します。

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` という管理系ミラー API も存在し、正式な管理名前空間は `/admin/kyc` です。

Envelope

共通レスポンス構造

スキャンしたすべてのコントローラーは `ApiResponse` を返し、実際の業務データは `data` に格納されます。

フィールド型例
codenumber0 は成功、0 以外は失敗または業務例外
messagestringsuccess、query success、Document uploaded successfully などのメッセージ
dataobjectprofileId、status、detail、list などの業務ペイロード
Core Web API

ユーザー向け 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
コールバック

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

活体検知 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

管理審査 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

プライバシーポリシー ‧ クッキーポリシー