CLOVA eKYC ARS API

Prev Next

버전

날짜 변경사항
2023-05-25 최초 작성
2023-07-06 ARS 도메인 제공

개요

ARS인증 API 가이드입니다. API 는 인증(verify)과 확인(confirm) 2단계로 나뉘어 있으며, 이용 이력 및 통계는 인증에서만 발생합니다.

인증 API

인증요청

메서드 요청 URI
POST - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출
- 각 도메인마다 고유의 호출 URL이 생성됨

API 요청 예시

curl -X POST "{invokeUrl}/verify" \
-H "X-EKYC-SECRET: {secret}" \
-H "Content-Type: application/json" \
-d "{\"retry\": {retry}, \"caller\": \"{caller}\", \"message\": \"{message}\", \"phone\": \"{phone}\", \"requestId\": \"{requestId}\", \"verifyValue\": \"{verifyValue}\"}"

요청헤더

이름 설명
X-EKYC-SECRET API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret}
Content-Type application/json

요청바디

필드이름 필수여부 데이터유형 설명 제약사항
requestId Yes string API 요청ID 임의값으로 호출합니다. Confirm API 호출시에 재사용합니다.
동일한 requestId 는 10분간 재사용 불가능합니다.
caller Yes string 발신자번호 미등록번호 발신 등 부정이용시 통신사에 의해 이용이 제한될 수 있습니다.
8~11자리
phone Yes string 수신자번호 존재하지 않는 번호라도, API는 성공합니다. Confrim API 로 결과를 확인할 수 있습니다.
최대 11자
message Yes string 인사멘트 , : | \n 는 허용하지 않습니다.
최대150자
verifyValue Yes string 인증값 최대 6자
retry No boolean 재시도여부. true 인 경우 인증값을 잘못 입력하거나 대기 시간을 초과하는 경우 인사멘트를 다시 출력합니다. 기본값: false

인증응답

응답바디

필드명 데이터유형 설명
requestId string API 요청ID
timestamp integer API 응답 Timestamp 값
uid string API 응답 UUID
inferType string 유형 : ARS
inferDetailType string 상세유형 : ARS
result string "SUCCESS" : 호출 성공
"FAILURE" : 호출 실패(과금)
"ERROR" : 호출 오류(과금 미발생)
code string 4자리 에러코드
message string 호출 결과 메시지

예시

{
    "requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
    "uid": "62cpj68p34d9n3ae9mclh68dj6",
    "timestamp": 1684918779286,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "message": "Success"
}

확인 API

확인요청

메서드 요청 URI
POST - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출
- 각 도메인마다 고유의 호출 URL이 생성됨

API 요청 예시

curl -X POST "{invokeUrl}/confirm" \
-H "X-EKYC-SECRET: {secret}" \
-H "Content-Type: application/json" \
-d "{\"requestId\": \"{requestId}\"}"

요청헤더

이름 설명
X-EKYC-SECRET API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret}
Content-Type application/json

요청바디

필드이름 필수여부 데이터유형 설명 제약사항
requestId Yes string API 요청ID Verfiy API 에서 사용했던 requestId 를 사용

확인응답

응답바디

필드명 데이터유형 설명
requestId string API 요청ID
timestamp integer API 응답 Timestamp 값
uid string API 응답 UUID
inferType string 유형 : ARS
inferDetailType string 상세유형 : ARS
result string "SUCCESS" : 호출 성공
"FAILURE" : 호출 실패(과금)
"ERROR" : 호출 오류(과금 미발생)
code string 4자리 에러코드
message string 호출 결과 메시지

예시

{
    "requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
    "uid": "66cj4copjac1m6ae1pcgq6cdpn",
    "timestamp": 1684918877987,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "SUCCESS",
    "message": "Success"
}

{
    "requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
    "uid": "30e1i61ijccj162d9g60ojce1i",
    "timestamp": 1684919067919,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "FAILURE",
    "code": "3012",
    "message": "인증번호불일치 1회"
}

{
    "requestId": "abb3fcb0-2566-44f4-badd-202be9621c15",
    "uid": "30e1gc9gjgpb33cc9hcdh66cj3",
    "timestamp": 1684919099498,
    "inferType": "ARS",
    "inferDetailType": "ARS",
    "result": "ERROR",
    "code": "3902",
    "message": "ARS 처리중입니다. 잠시후에 다시 조회하여 주십시오."
}

에러코드

HTTP 상태 설명
200 요청에 성공했으나, 내부적으로 오류가 있는 경우
400 요청 에러
401 권한 에러
500 내부 서버 에러

에러응답:

{
  "code": "0011",
  "message": "Request body invalid.",
  "path": "{request API path}",
  "timestamp": 1570776853475
}
에러코드 HTTP 상태 메시지 설명
0001 400 URL is invalid. URL 오류
0002 401 Secret key validate failed. Secret 검증 오류
0011 400 Request body invalid. 요청값 오류
0012 400 RequestId is duplicated. 요청ID가 중복된 경우
0022 400 Request domain invalid. 도메인 조회가 불가능한 경우
0024 400 Data is duplicated. 요청데이터 중복 오류
0025 400 Calls to this api have exceeded the rate limit. 일시적으로 API 호출 허용량을 초과한 경우 (도메인별)
0027 400 The system is busy. 일시적으로 API 호출 허용량을 초과한 경우
0500 500 Unknown service error. 알 수 없는 오류
3001 200 인증실패 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3007 200 전화를 받지 않음 ARS인증 내부 모듈에서 발생하는 메시지
3008 200 수신자가 전화를 받은 후 끊음 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3009 200 인증번호입력 타임아웃1회 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3010 200 인증번호입력 타임아웃2회 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3012 200 인증번호불일치 1회 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3013 200 인증번호불일치 2회 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3016 200 인증거절 ARS인증 내부 모듈에서 발생하는 메시지 (FAILURE)
3021 200 고객에게 전화콜이 나가기 전에 동일한 수신자번호로 인증요청 ARS인증 내부 모듈에서 발생하는 메시지
3022 200 고객에게 벨소리가 울리는 상태일 때 동일한 수신자번호로 인증요청 ARS인증 내부 모듈에서 발생하는 메시지
3023 200 고객이 통화중일 때 동일한 수신자번호로 인증요청 ARS인증 내부 모듈에서 발생하는 메시지
3902 200 ARS 처리중입니다. 잠시후에 다시 조회하여 주십시오. ARS인증 내부 모듈에서 발생하는 메시지
3999 200 ARS 서비스 오류 ARS인증 내부 모듈에서 발생하는 메시지