CLOVA eKYC Verify API
- 인쇄
- PDF
CLOVA eKYC Verify API
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
버전
| 날짜 | 변경사항 |
|---|---|
| 2021-12-21 | 최초 작성 |
| 2022-02-17 | |
| 2023-02-23 | response.code 필드 추가 |
| 2023-07-20 | 외국인등록증 serialNum 필드 추가 |
| 2023-11-23 | 외국인등록증 serialNum 필수값 해제 |
| 2024-09-26 | 운전면허증의 암호일련번호 검증 제외옵션 추가, 검증제외시 면허정보 확인만가능(진위검증 불가) |
개요
Document API 응답 결과로 신분증/사업자등록증에 대한 진위검증을 합니다.
요청
| 메서드 | 요청 URI |
|---|---|
| POST |
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 | |
| data | Yes | array | 검증요청데이터 |
- 주민등록증 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| 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자) | |
| skipCodeCheck | No | boolean | 암호일련번호(code) 검증제외여부. 기본값은 false, true 일 경우 code 값과 관계없이 면허정보만 검증합니다. |
- 여권 검증요청데이터 상세 설명
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| 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 | 검증결과 |
| 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": "조회하신 사업자등록번호는 현재 등록되어 있지 않습니다."
}
이 문서가 도움이 되었습니까?