CLOVA eKYC Verify API
- 인쇄
- PDF
CLOVA eKYC Verify API
- 인쇄
- PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
버전
| 날짜 | 변경사항 |
|---|---|
| 2021-12-21 | 최초 작성 |
| 2022-02-17 | - 운전면허증 요청값(주민등록증) 가이드 추가 - inferDetailType 요청값 제거 |
| 2023-02-23 | response.code 필드 추가 |
| 2023-07-20 | 외국인등록증 serialNum 필드 추가 |
| 2023-11-23 | 외국인등록증 serialNum 필수값 해제 |
개요
Document API 응답 결과로 신분증/사업자등록증에 대한 진위검증을 합니다.
요청
| 메서드 | 요청 URI |
|---|---|
| POST | - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출 - 각 도메인마다 고유의 호출 URL이 생성됨 - Document API 의 응답에서 inferDetailTypeResource 를 verify api 호출에 사용 |
API URL 예시
- {invokeURL}/verify/{inferDetailTypeResource}
- https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/{inferType}/verify/{inferDetailTypeResource}
- 주민등록증 {invokeUrl}/verify/ic
- 운전면허증 {invokeUrl}/verify/dl
- 여권 {invokeUrl}/verify/pp
- 외국인등록증 {invokeUrl}/verify/ac
- 사업자등록증(법인) {invokeUrl}/verify/bl-corp
검증상세타입
| 분류 | inferDetailTypeResource | Path |
|---|---|---|
| 주민등록증 | ic | /verify/ic |
| 운전면허증 | dl | /verify/dl |
| 여권 | pp | /verify/pp |
| 외국인등록증 | ac | /verify/ac |
| 사업자등록증(법인) | bl-corp | /verify/bl-corp |
| 사업자등록증(개인) | bl-sole | /verify/bl-sole |
| 사업자등록증명(법인) | bl-cert-corp | /verify/bl-cert-corp |
| 사업자등록증명(개인) | bl-cert-sole | /verify/bl-cert-sole |
요청헤더
| 이름 | 설명 |
|---|---|
| X-EKYC-SECRET | API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret} |
| Content-Type | application/json : request use json body. |
요청바디
Content-Type : application/json
- 검증 요청 공통
| 분류 | JSON 모델 |
|---|---|
| 공통 | { "requestId": "string", "data": [] } |
검증 요청 필드 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| requestId | Yes | string | API 호출 ID | - Document API 요청 시 사용했던 requestId 로 10분간 호출가능합니다. |
| data | Yes | array | 검증요청데이터 | - 검증상세 타입별로 상이함 - 기본적으로 문서의 OCR 결과를 API 에서 파싱하여 검증에 사용함 - 현재 1개의 data만 처리 가능 (추후 개선 예정) - 요청값은 Document API 응답 과 동일한 필드명을 사용함. 예를 들어 주민등록증을 인식하는 경우 응답에서 "personalNum" 필드의 값을 Verify API에서도 사용함 |
- 주민등록증 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| name | Yes | string | 이름 | |
| personalNum | Yes | string | 주민등록번호 | |
| issueDate | Yes | string | 발급일자 |
- 운전면허증 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| name | Yes | string | 이름 | |
| personalNum | Yes | string | 생년월일(주민등록번호 앞 6자리) | |
| num | Yes | string | 운전면허번호 | |
| code | Yes | string | 암호일련번호 : 위조방지를 위한 숫자, 6자리 번호(숫자와 영문 혼합) 또는 6자리 번호(숫자4자리 + 영문2자) |
- 여권 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| fullNameKor | Yes | string | 한글이름 | 영문 이름 검증은 현재 지원하지 않음 |
| num | Yes | string | 여권번호 | |
| birthDate | Yes | string | 생년월일 | |
| issueDate | Yes | string | 발급일자 | |
| expireDate | Yes | string | 만료일자 |
- 외국인등록증 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| alienRegNum | Yes | string | 외국인등록번호 | |
| issueDate | Yes | string | 발급일자 | |
| serialNum | Yes | string | 일련번호 | 신분증 후면에 별도 기재되어 인식 불가 |
- 사업자등록증(공통) 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| registerNumber | Yes | string | 사업자등록번호, 사업자의 진위 검증은 사업자등록번호로만 진행 |
응답
응답바디
검증 응답
| 분류 | JSON 모델 |
|---|---|
| 공통 | { "requestId": "string", "timestamp": integer, "uid": "string", "result": "string", "code": "string" "message": "string", "inferType": "string", "inferDetailType": "string" } |
검증 응답 필드 상세 설명
| 필드명 | 데이터유형 | 설명 |
|---|---|---|
| requestId | string | API 호출 ID |
| timestamp | integer | API 호출 Timestamp 값 |
| uid | string | 내부 UUID |
| result | string | 검증결과 - "SUCCESS": 정상적인 신분증/사업자등록증 - “FAILURE”: 비정상적인 신분증/사업자등록증 |
| code | string | 검증결과가 실패(FAILURE) 인 경우 유형을 구분하기 위한 코드 |
| message | string | 결과메시지: Success 혹은 진위검증 기관의 에러메시지 |
예시
주민등록증 검증 요청 예시
{
"data": [
{
"issueDate": "2022. 2. 1.",
"name": "홍길동",
"personalNum": "123456-1234567"
}
],
"requestId": "5b9de1f9765448eca574efc1a4231bbe"
}
운전면허증 검증 요청 예시
{
"data": [
{
"code": "W9UN5X",
"name": "홍길동",
"num": "16-17-001750-40",
"personalNum": "123456-1234567"
}
],
"requestId": "5b9de1f9765448eca574efc1a4231bbe"
}
여권 검증 요청 예시
{
"data": [
{
"birthDate": "01 FEB 2022",
"expireDate": "11 NOV 2031",
"fullNameKor": "홍길동",
"issueDate": "11 NOV 2021",
"num": "M64795068"
}
],
"requestId": "5b9de1f9765448eca574efc1a4231bbe"
}
외국인등록증 검증 요청 예시
{
"data": [
{
"alienRegNum": "123456-1234567",
"issueDate": "2021.11.11"
"serialNum": "01234567890"
}
],
"requestId": "5b9de1f9765448eca574efc1a4231bbe"
}
사업자등록증(공통) 검증 요청 예시
{
"data": [
{
"registerNumber": "1234567890"
}
],
"requestId": "5b9de1f9765448eca574efc1a4231bbe"
}
검증 응답 예시
{
"requestId": "5b9de1f9765448eca574efc1a4231bbe",
"uid": "28594b31dbca47d6b4ef31b4cf1973ad",
"timestamp": 1636687429703,
"inferType": "BIZ_LICENSE",
"inferDetailType": "BL_CORP",
"result": "FAILURE",
"code": "0590",
"message": "조회하신 사업자등록번호는 현재 등록되어 있지 않습니다."
}
이 문서가 도움이 되었습니까?