API 가이드(구버전)
아르고스 API를 이용하여 고객의 KYC 폼 데이터를 제출하고 KYC 진행 상황을 확인할 수 있습니다.
아르고스 API는 RESTful Endpoints와 기본인 HTTP Method를 사용합니다.
응답 데이터에는 요청 상태와 발생 가능한 오류 코드가 포함됩니다.
모든 응답 데이터는 JSON 형식으로 제공됩니다.
토큰 인증을 사용합니다.
모든 요청은 HTTPS에서 수행해야 합니다. HTTP 요청은 실패 됩니다.
1. 시작하기
API를 이용하기 위해서는 유효한 API 키가 필요합니다. API 키는 서비스 시작 전 전달되며, 찾을 수 없는 경우 헬프데스크로 문의 부탁 드립니다.
2. 인증
API는 토큰에 기반한 인증을 이용합니다. API를 이용하기 위해서는 반드시 아르고스에서 제공한 API만 이용해야 합니다.
HTTP 헤더로 인증하기
쿼리와 함께 API 키를 HTTP 헤더로 보낼 수 있습니다.
API 키는 메소드 요청 헤더에 'x-api-key: {yourAPIKey}’로 포함되어야 합니다.
오류
일반 HTTP 응답 코드로 응답합니다. 성공하면 2xx 코드로 표시됩니다. 4xx는 클라이언트에서 전송된 정보에 오류가 있을 때 발생하며, 5xx는 Argos 서버에서 오류가 있을 때 발생합니다.
오류코드
HTTP Code | Message | 설명 |
---|---|---|
400 | Invalid Query String parameters | 클라이언트 에러 (예. 잘못된 형식의 요청 구문, 잘못된 요청 메시지 프레임) |
403 | Forbidden | API 키에 문제가 있습니다. |
413 | Request Entity Too Large | 요청이 서버가 의도하거나 수행할 수 있는 것보다 큽니다. |
500 | Internal Server Error | 아르고스 서버의 에러일 수 있습니다. 아르고스 팀에 문의하세요. |
502 | Bad Gateway | 서버가 업스트림 서버로부터 잘못된 응답을 받았습니다. |
3. GET /submission
제출 목록을 가져옵니다.
KYC/AML 상태는 GET 요청으로 확인할 수 있습니다.
특정 제출의 KYC 상태를 확인하거나 GET 요청과 함께 KYC 제출 목록을 얻을 수 있습니다.
매개 변수가 제공되지 않으면 모든 제출 목록이 반환됩니다.
매개 변수가 제공된 경우 지정된 매개 변수를 기준으로 목록을 필터링합니다.
특정 제출의 제출 데이터를 가져오려면 제출 ID를 매개 변수로 제공해야 합니다.
요청 URL
Input 데이터
파라미터 | 필수여부 | 설명 |
---|---|---|
Submission_id | 선택사항 | 하나의 제출된 데이터에 일치하는 Submission ID가 반환됩니다. |
Userid | 선택사항 | 사용자 ID와 일치하는 목록이 반환됩니다. userid는 submission을 post 할 때 선택적으로 추가되는 변수입니다. |
선택사항 | 이메일 주소와 일치하는 제출 목록이 반환됩니다. | |
count | 선택사항 | 리스트 출력 요청시 전달 받을 데이터 건수 (최대 2,000개). count parameter 없이 리스트 요청 시 default로 최대 2000개까지 출력 됩니다. |
nextpage_id | 선택사항 | 리스트 출력 요청 시 응답에 nextpageKey가 리턴되는 경우, 다음 페이지가 있음을 의미합니다. 요청 parameter에 nextpage_id(nextpageKey.id)와 nextpage_date(nextpageKey.created_at)를 함께 포함하여 요청하면 다음 페이지가 호출됩니다. |
nextpage_date | 선택사항 | 리스트 출력 요청 시 응답에 nextpageKey가 리턴되는 경우, 다음 페이지가 있음을 의미합니다. 요청 parameter에 nextpage_id(nextpageKey.id)와 nextpage_date(nextpageKey.created_at)를 함께 포함하여 요청하면 다음 페이지가 호출됩니다. |
Output 데이터
Response | 설명 |
---|---|
data | KYC 제출자 데이터 |
data.name | 이름 |
data.gender | <male, female> |
data.nationality | 3글자 형식의 국가코드 (ISO alpha3 형식) |
data.date_of_birth | YYYY-MM-DD의 날짜 형식 |
data.idType | 신분증 종류<passport, government_id, drivers_license> |
data.idcard_issuingCountry | 신분증 발급 국가의 ISO alpha 3 형식의 코드 |
data.idcard_issueDate | YYYY-MM-DD 형식의 신분증 발급일자 |
data.idcard_expireDate | YYYY-MM-DD 형식의 신분증 만료일자 |
data.identityNumber | 주민등록번호 |
data.documentNumber | 신분증 번호 |
data.address_city | 도시 |
data.address_country | 국가 |
data.address_state | 주 |
data.address_street | 도로 |
data.address_zipcode | 우편번호 |
data.address_globalCode | 전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP) |
data.address_compoundCode | 국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea) |
data.address_formatted | 상세 코드를 변환한 주소 |
data.address_input | 사용자 입력 주소 값 |
data.address_detail | 사용자 입력 상세주소 값 |
data.cf1 | submission을 제출할 때 선택적으로 추가되는 값 1 |
data.cf2 | submission을 제출할 때 선택적으로 추가되는 값 2 |
data.cf3 | submission을 제출할 때 선택적으로 추가되는 값 3 |
이메일 주소 | |
submission_id | 각 submission에 부여된 고유 식별 ID |
applicant_id | 승인된 제출자에 부여된 고유 식별 ID |
created_at | KYC가 제출된 날짜와 시간 |
userid | submission을 생성할 때 선택적으로 추가되는 파라미터 |
kyc | KYC 데이터 오브젝트 |
kyc.result | <Incomplete, pending, approved, rejected> incomplete: KYC 제출이 불완전합니다. 신분증을 제출하였으나 셀가 제출되지 않았을 때 발생하는 오류입니다. pending: 제출된 파일은 수동 검수중 입니다. approved: 제출된 파일이 승인되었습니다. rejected: 제출된 파일이 거절되었습니다. 거절 사유는 kyc.comment에서 확인할 수 있습니다. |
kyc.comment | KYC 거절 사유는 KYC 결과가 ‘rejected’ 되었을 때 반환됩니다. |
kyc.commentCode | KYC 거절 사유(kyc.comment)에 대한 코드 값 |
kyc.attempts | Liveness, Detect face, Face compare, 신분증 진위확인의 실행건에 대한 오브젝트 |
kyc.attempts[i].error | Liveness, Detect face, Face compare, 신분증 진위확인 실행 시 발생되는 예외 오류 메세지 |
kyc.attempts[i].retryMsg | Liveness, Detect face, Face compare, 신분증 진위확인 실행 시 발생되는 실패 원인 메세지 |
kyc.attempts[i].livenessScore | i번째 실행되는 liveness 점수 값 |
kyc.attempts[i].faceSimilarityScore | i번째 실행되는 face compare 비교 값 |
kyc.attempts[i].verificationParams | i번째 실행되는 신분증 진위확인 실행 입력 값 |
kyc.attempts[i].verificationResult | i번째 실행된 신분증 진위확인 결과 값 <success, fail> |
aml | aml 스크리닝 결과 데이터 오브젝트 |
aml.risk_level_summary | <Not Screened, High, Medium, Low> |
aml.currentstatus | <Not Screened, Red Flag> |
aml.matches | 상세 AML 스크리닝 결과. aml.currentstatus가 ‘Red Flag’일때만 이용 가능합니다. |
aml.matches[i].resource_id | AML 보고서를 조회하기 위한 리소스 고유 ID |
nextpageKey | 추가로 출력될 다음 페이지가 있을 경우에 전달되는 키 값 오브젝트 |
nextpageKey.id | 다음 페이지 호출시 필요한 가장 마지막으로 조회되었던 submission의 id 값 |
nextpageKey.created_at | 다음 페이지 호출시 필요한 가장 마지막으로 조회되었던 submission의 created_at 값 |
샘플 응답 1. 단건조회
샘플 응답 2. 목록조회
3-1. GET /submission/applicant
동일 인물이 제출한 승인된 submission 목록을 가져옵니다.
이름, 생년월일, 국적, 성별, 얼굴이 같은 사람의 submission이 다수 있을 경우 중복 제출로 판단하며, 중복 제출된 submission들을 확인 할 수 있습니다.
중복으로 제출하지 않은 일반적인 제출자의 경우 승인된 단일 submission만 가져옵니다.
applicant_id를 기준으로 조회하기때문에, submission 정보에서 applicant_id를 획득해야 합니다.
Request URL
Input 데이터
Parameter | requirement | Description |
---|---|---|
applicant_id | required | submission 정보에서 획득한 제출자의 고유 applicant_id로 조회합니다. |
Output 데이터
Response | Description |
---|---|
submission_id | 중복제출로 확인된 submission의 고유 값 |
중복 제출로 확인된 submission에 기록된 이메일 주소 |
4. POST /submission/step1
요청 URL
Input 데이터
파라미터 | 포맷 | 필수여부 | 설명 |
---|---|---|---|
issuingCountry | string (ISO3) | 필수 | ISO alpha 3 형식의 신분증이 발행된 국가 |
string | 필수 | KYC 제출자의 이메일 주소 | |
idType | string | 필수 | <passport, government_id, drivers_license> |
idImage | file | 필수 | Jpg, jpeg, png 파일 형식의 신분증 사진 (파일 크기 제한: 3mb) |
userid | string | 옵션 | 사용자의 사용자 지정 고유 식별자 |
cf1 | string | 옵션 | 사용자 정의 옵션 필드 |
cf2 | string | 옵션 | 사용자 정의 옵션 필드 |
cf3 | string | 옵션 | 사용자 정의 옵션 필드 |
Output 데이터
Response | 설명 |
---|---|
Submissionid | submission의 ID. 해당 ID는 step 2에서 필요합니다. |
reviewOCRData | 신분증 정보를 포함하는 OCR 오브젝트입니다. 만약 OCR 인식에 실패하면 이 파라미터는 반환되지 않습니다 |
reviewOCRData.ocr_birthDate | YYYY-MM-DD 형식의 생년월일 |
reviewOCRData.ocr_issueDate | 발급 일자 (이용 가능할 때) |
reviewOCRData.ocr_expireDate | 만료 일자 (이용 가능할 때) |
reviewOCRData.ocr_lastName | 성 (이용 가능할 때) |
reviewOCRData.ocr_firstName | 이름 (이용 가능할 때) |
reviewOCRData.ocr_name | 전체 이름 (이용 가능할 때) |
reviewOCRData.ocr_gender | 성별 (이용 가능할 때) |
reviewOCRData.ocr_nationality | ISO3 코드 형식의 국가코드 (이용 가능할 때) |
reviewOCRData.ocr_identityNumber | 사용자 고유의 식별번호(한국 주민등록번호에만 적용) |
reviewOCRData.ocr_licenseNumber | 운전면허번호 (한국 운전면허증에만 적용) |
file_upload | 신분증 사진이 성공적으로 받아졌으면 “true”, 그렇지 않을 때는 “fail” |
샘플 응답
5. POST /submission/step2
요청 URL
Input 데이터
파라미터 | 포맷 | 필수여부 | 설명 |
---|---|---|---|
submissionId | string | 필수 | step 1으로 받은 제출된 고유 ID |
faceImage | file | 필수 | 하나의 얼굴을 보여주는 셀피 사진. 여러 명의 얼굴이 감지될 경우, 재시도로 응답됩니다. (파일 크기 제한: 3mb) |
name | string | 필수 | 이름 형식은 ”성, 이름, 중간 이름” (예시: “Trump, Donald John”)으로 나타낼 수 있습니다. 이 형식은 각 제출자들의 성들을 정확히 알고 있을 때 선호됩니다. 제출자의 성을 정확히 모를 땐 ”이름, 중간 이름, 성” (예시: “Donald John Trump”) 형식을 쓰게 됩니다. 알고리즘이 두 가지 방식 중 하나를 자동으로 선택할 것입니다. |
date_of_birth | string | 필수 | YYYY-MM-DD |
gender | string | 옵션 | <남성, 여성> |
nationality | string | 옵션 | ISO alpha 3 형식의 국가코드. 반드시 신분증이 발급된 국가일 필요는 없습니다. |
identity_number | string | 옵션 | (한국 주민등록증) 한국 주민등록번호 |
license_number | string | 옵션 | (한국 운전면허증) 진위확인을 위한 운전면허번호 |
serial_number | string | 옵션 | (한국 운전면허증) 한국 운전면허증의 고유한 6자리 일련번호 |
date_of_issue | string | 옵션 | YYYY-MM-DD 형식의 사진 신분증 발급일자 |
addressImage | file | 옵션 | 주소 정보 증명을 위한 주소 문서 사진 파일 (파일 크기 제한: 3mb) |
address_street | string | 옵션 | 주소 |
address_city | string | 옵션 | 도시 |
address_state | string | 옵션 | 주 |
address_country | string | 옵션 | ISO 3 형식의 국가코드 |
address_zipcode | string | 옵션 | 우편번호 |
globalCode | string | 옵션 | 전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP) |
compoundCode | string | 옵션 | 국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea) |
formatted_address | string | 옵션 | 상세 코드를 변환한 주소 |
address_input | string | 옵션 | 사용자 입력 주소 값 |
address_detail | string | 옵션 | 사용자 입력 상세주소 값 |
Output 데이터
응답 | 설명 |
---|---|
kycStatus | <pending, approved, rejected, incomplete> ‘pending’인 경우에는 kyc 제출이 끝났으나 수동 검수를 통해 제출된 파일이 승인될지 거절될지를 결정하기 위해 검토 중입니다. ‘incomplete’인 경우에는 잘못된 kyc 데이터로 인해 승인이 이루어지지 않았습니다. kycStatus가 ‘pending’, ‘approved’나 ‘rejected’ 상태로 변할 때까지 step 2의 재시도를 하길 추천드립니다. |
faceSimilarityScore | 신분증의 사진과 셀피 사진의 얼굴 유사도 점수입니다. 점수는 0부터 100까지이며 100에 가까울수록 두 얼굴이 일치할 확률이 큽니다. |
livenessScore | 라이브니스 점수는 셀피 이미지 속 얼굴이 실제 인물인지를 평가합니다. 점수는 0점부터 100점까지이며 점수가 100에 가까울수록 이미지는 (영상이나 이미지의 이미지가 아닌) 실제 인물 사진일 가능성이 높습니다. |
verificationResult | <success, fail> |
retryCount | Step 2의 재시도 횟수. Step 2 재시도가 3번을 넘을 경우 KYC는 거절됩니다. |
message | KycStatus가 ‘incomplete”인 경우에, KYC submission이 생성되지 않은 사유를 보여줍니다. |
kycStatus는 "incomplete"일 때 다음과 같은 경우 retryCount가 증가합니다.
얼굴 이미지에서 감지된 얼굴이 없는 경우
얼굴 이미지에서 세 개 이상의 얼굴이 감지된 경우
얼굴 비교 점수가 85 미만인 경우
라이브니스(Liveness) 점수가 50 미만인 경우
(한국신분증만 해당) ID 확인 실패
샘플 응답
{
"verificationResult":"success",
"faceSimilarityScore":99,
"livenessScore":91,
"kycStatus":"pending",
"retryCount":0
}
5-1. POST /address_code
주소지를 '수집'하는경우에만 사용해주세요.
요청 URL
요청 샘플 1
요청 샘플 2
샘플 응답
Input Data
파라미터 | 포맷 | 필수 여부 | 설명 |
---|---|---|---|
address | string | 필수 | 다음 항목 중 하나를 입력하여 조회할 수 있습니다.
|
language | string | 옵션 | 결과 리턴값에 대한 언어 선택
( |
Output Data
응답 파라미터 | 설명 |
---|---|
formatted_address | 상세 코드를 변환한 주소 |
compound_code | 국가 및 도시와 상세주소 코드 값 (Ex. HXPG+MP Seoul, South Korea) |
global_code | 전체 주소에 대한 상세코드 값 (Ex. 8Q98HXPG+MP) |
6. DELETE /submission
단일 제출 데이터를 삭제합니다.
제출 데이터와 제출과 관련된 이미지 파일이 완전히 삭제됩니다.
주의!!! 삭제된 제출 기록은 복원할 수 없습니다.
샘플 요청
Input 데이터
파라미터 | 설명 |
---|---|
submission_id | Submission ID. 각각의 제출건에 대한 고유 ID |
샘플 응답
7. GET /report/aml
AML 스크리닝 결과와 pdf 보고서를 반환합니다.
'resourceId'별로 AML 보고서가 제공됩니다. AML 보고서를 다운로드하려면 'resourceId'가 필요합니다.
요청 URL
Input Data
파라미터 | 설명 |
---|---|
resourceId | 리소스 아이디는 AML 검사 결과로 선별된 사람의 고유값입니다. 리소스 아이디는 제출된 파일이 AML Red Flag로 스크린 되었을 때 생성됩니다. 각 AML 선별 결과마다 고유의 리소스 아이디가 있습니다. 하나의 제출된 파일에도 여러 개의 일치 항목이 있을 수 있으므로 해당의 경우에는 여러 개의 리소스 아이디가 있습니다. |
Output 데이터
응답으로 파일이 다운로드 됩니다.
8. GET /image
요청 URL
Input 데이터
파라미터 | 필수여부 | 설명 |
---|---|---|
submission_id | 필수 | 고유의 제출 ID |
type | 필수 | <idImage, selfieImage, addressImage> idImage: 신분증 사진을 다운로드합니다. selfieImage: 셀피의 이미지를 다운로드합니다. addressImage: 제출된 파일에 주소 문서가 있을 경우 다운로드합니다. |
Output 데이터
응답으로 파일이 다운로드 됩니다.
Last updated