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

개인정보처리방침 ‧ 쿠키 정책