KYC API Docs

KYC Service REST API ドキュメント

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

OCR 認証へ戻る導入相談

ベースパス/api/web/kycService

レスポンス形式ApiResponse { code, message, data }

アップロード形式multipart/form-data

管理名前空間/admin/kyc

Scanned Source

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

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

KYC プロファイル作成

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

証憑データ送信

既存のファイル保管基盤があれば `/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` という管理系ミラー API も存在し、正式な管理名前空間は `/admin/kyc` です。

Envelope

共通レスポンス構造

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

フィールド	型	例
`code`	number	0 は成功、0 以外は失敗または業務例外
`message`	string	success、query success、Document uploaded successfully などのメッセージ
`data`	object	profileId、status、detail、list などの業務ペイロード

Core Web API

ユーザー向け API

`ApiKycController` に対応し、プロファイル作成、証憑アップロード、確認、送審、状態照会を含みます。

7 件の documented endpoint

POST/api/web/kycService/submit

選択中のエンドポイント

KYC プロファイル作成

KYC プロファイルを作成し、後続 API で共通利用する `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

補足

コントローラーは status 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

活体検知 API

`ApiKycLivenessController` に対応し、セッション作成、動画検証、セッション照会を含みます。

3 件の documented endpoint

POST/api/web/kycService/liveness/start

選択中のエンドポイント

活体セッション開始

5 分間有効なセッションを作成し、ランダム化された 3 つのチャレンジ動作を返します。

公開推奨

フィールド	型	必須	位置	例
`profileId`	string	はい	query	profile_123456

主なレスポンス

sessionIdactionsexpireTimetimeout

補足

コントローラーは `LivenessActionEnum` をシャッフルし、必ず 3 つの動作を返します。

POST/api/web/kycService/liveness/verify

選択中のエンドポイント

活体動画検証

3 本のチャレンジ動画をアップロードし、集約された活体結果を返します。

公開推奨

フィールド	型	必須	位置	例
`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

管理審査 API

`AdminKycController` に対応し、一覧、詳細、審査状態更新を提供します。

3 件の documented endpoint

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 詳細取得

証憑、活体、顔照合を含む 1 件のレビュー詳細ペイロードを取得します。

管理

フィールド	型	必須	位置	例
`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 プロファイル作成

KYC プロファイルを作成し、後続 API で共通利用する `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