CLOVA eKYC ARS API
- 인쇄
- PDF
CLOVA eKYC ARS API
- 인쇄
- PDF
기사 요약
이 요약이 도움이 되었나요?
의견을 보내 주셔서 감사합니다.
버전
| 날짜 | 변경사항 |
|---|---|
| 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인증 내부 모듈에서 발생하는 메시지 |
이 문서가 도움이 되었습니까?