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 서버에서 오류가 있을 때 발생합니다.
오류코드
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 데이터
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 데이터
applicant_id
required
submission 정보에서 획득한 제출자의 고유 applicant_id로 조회합니다.
Output 데이터
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 데이터
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
필수
다음 항목 중 하나를 입력하여 조회할 수 있습니다.
주소
global code
compound code
위도 및 경도 (콤마 구분으로 입력, ex. “37.557,126.973”)
language
string
옵션
결과 리턴값에 대한 언어 선택
(ISO 3166-2 코드
)
(ex. “ko”)
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