API 가이드(구버전)

https://rest-api.argoskyc.com/v2/submission

아르고스 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}’로 포함되어야 합니다.

curl -H "x-api-key: {yourAPIKey}" "https://rest-api.argoskyc.com/..."

오류

일반 HTTP 응답 코드로 응답합니다. 성공하면 2xx 코드로 표시됩니다. 4xx는 클라이언트에서 전송된 정보에 오류가 있을 때 발생하며, 5xx는 Argos 서버에서 오류가 있을 때 발생합니다.

오류코드

3. GET /submission

제출 목록을 가져옵니다.

• KYC/AML 상태는 GET 요청으로 확인할 수 있습니다.

• 특정 제출의 KYC 상태를 확인하거나 GET 요청과 함께 KYC 제출 목록을 얻을 수 있습니다.

• 매개 변수가 제공되지 않으면 모든 제출 목록이 반환됩니다.

• 매개 변수가 제공된 경우 지정된 매개 변수를 기준으로 목록을 필터링합니다.

• 특정 제출의 제출 데이터를 가져오려면 제출 ID를 매개 변수로 제공해야 합니다.

요청 URL

curl -X GET "https://rest-api.argoskyc.com/v2/submission?submission_id={submission_id}"\
-H "x-api-key: {yourAPIKey}"

Input 데이터

Output 데이터

샘플 응답 1. 단건조회

{	
Items: [	
{	
data: {	
name: "홍길동",	
gender: "male",	
nationality: "KOR",	
date_of_birth: "1998-11-12",	
cf1: "test",	
ip_address: "*.*.*.*",	
idcard_issuingCountry: "KOR",	
idcard_issueDate: "2016-08-16",	
idType: "government_id",	
identityNumber: "981112-1******"	
},	
email: "[e-mail]",	
submission_id: "gt7rcxx9l1o*****",	
created_at: "2022-04-07T00:30:35.919Z",	
userid: "test1",	
kyc: {	
result: "rejected",	
comment: [	
Too many retry 	
],	
	commentCode: [
too_many_retry	
],	
attempts: [	
{	
attemptCnt: 1,	
livenessScore: 91,	
faceSimilarityScore: 99,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-15",	
identityNumber: "981112-1******"	
},	
verificationResult: "fail",	
retryMsg: "1. Identity verification failed: 입력하신 발급일자는 등록된 발급일자와 일치하지 않습니다. 궁금하신 사항은 가까운 읍면동에 문의하시기 바랍니다"	
},	
{	
attemptCnt: 2,	
livenessScore: 98,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-16",	
identityNumber: "981112-1******"	
},	
verificationResult: "success",	
retryMsg: "1. Face compare failed: no matching face"	
},	
{	
attemptCnt: 3,	
faceSimilarityScore: 99,	
verificationParams: {	
fullName: "홍길동",	
idType: "government_id",	
issueDate: "2016-08-16",	
identityNumber: "981112-1******"	
},	
verificationResult: "success",	
retryMsg: "1. Liveness check failed: Absolute face size is too small"	
}	
],	
}	
}	
]	
}	

샘플 응답 2. 목록조회

{ 
Items: [ 
{ 
data: { 
name: "John Smith", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "[e-mail]", 
submission_id: "whkksdfyi1on0e", 
created_at: "2022-01-17T02:05:02.309Z", 
userid: "John Smith", 
kyc: { 
result: "approved" 
} 
}, 
{ 
data: { 
name: "Smith John", 
gender: "male", 
nationality: "USA", 
date_of_birth: "1965-08-29", 
cf1: "test", 
ip_address: "XX.XX.XXX.XXX" 
}, 
email: "[e-mail]", 
submission_id: "whksdkyi1i76x", 
created_at: "2022-01-17T02:00:02.808Z", 
userid: "John ", 
kyc: { result: "incomplete" 
} 
}

3-1. GET /submission/applicant

동일 인물이 제출한 승인된 submission 목록을 가져옵니다.

• 이름, 생년월일, 국적, 성별, 얼굴이 같은 사람의 submission이 다수 있을 경우 중복 제출로 판단하며, 중복 제출된 submission들을 확인 할 수 있습니다.

• 중복으로 제출하지 않은 일반적인 제출자의 경우 승인된 단일 submission만 가져옵니다.

• applicant_id를 기준으로 조회하기때문에, submission 정보에서 applicant_id를 획득해야 합니다.

Request URL

curl -X GET "<https://rest-api.argoskyc.com/v2/submission/applicant?applicant_id={applicant_id}>"\\
-H "x-api-key: {yourAPIKey}"

Input 데이터

Output 데이터

4. POST /submission/step1

요청 URL

curl -X POST "https://rest-api.argoskyc.com/v2/submission/step1" \
-H "x-api-key: {yourAPIKey}" \
-d ...

Input 데이터

Output 데이터

샘플 응답

{"reviewOCRData":
	{
	 	"ocr_issueDate":"2020-02-25",
		"ocr_gender":"male",
	 	"ocr_nationality":"USA",
	 	"ocr_birthDate":"1975-08-25",
		"ocr_name":"John Smith"
	},
	 "file_upload":true,
	 "submissionId":"1cz94l9ksfi1bokk"
	}

5. POST /submission/step2

요청 URL

curl -X POST "https://rest-api.argoskyc.com/v2/submission/step2" \
-H "x-api-key: {yourAPIKey}" \
-d ...

Input 데이터

Output 데이터

kycStatus는 "incomplete"일 때 다음과 같은 경우 retryCount가 증가합니다.

1. 얼굴 이미지에서 감지된 얼굴이 없는 경우

2. 얼굴 이미지에서 세 개 이상의 얼굴이 감지된 경우

3. 얼굴 비교 점수가 85 미만인 경우

4. 라이브니스(Liveness) 점수가 50 미만인 경우

5. (한국신분증만 해당) ID 확인 실패

샘플 응답

pending

{

"verificationResult":"success",

"faceSimilarityScore":99,

"livenessScore":91,

"kycStatus":"pending",

"retryCount":0

}

retry

{

"message": "no match face or 2 face detected",

"kycStatus": "incomplete",

"retryCount": 1

}

5-1. POST /address_code

주소지를 '수집'하는경우에만 사용해주세요.

요청 URL

curl -X POST "https://rest-api.argoskyc.com/v2/address_code" \
-H "x-api-key: {yourAPIKey}" \

요청 샘플 1

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://rest-api.argoskyc.com/v2/address_code',
  'headers': {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  form: {
    'address': '1 Sejongno, Jongno-gu, Seoul, South Korea'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

요청 샘플 2

curl --location --request POST 'https://rest-api.argoskyc.com/v2/address_code' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'language=en' \
--data-urlencode 'address=1 Sejongno, Jongno-gu, Seoul, South Korea'

샘플 응답

{
    "formatted_address": "1 Sejongno, Jongno-gu, Seoul, South Korea",
    "compound_code": "HXPG+MP Seoul, South Korea",
    "global_code": "8Q98HXPG+MP"
}

Input Data

Output Data

6. DELETE /submission

단일 제출 데이터를 삭제합니다.

제출 데이터와 제출과 관련된 이미지 파일이 완전히 삭제됩니다.

주의!!! 삭제된 제출 기록은 복원할 수 없습니다.

샘플 요청

curl -X DELETE "https://rest-api.argoskyc.com/v2/submission?submission_id={submission_id}"

Input 데이터

샘플 응답

{
	"message": "success",
	"content": "Submission #{submissionID} deleted successfully."
}

7. GET /report/aml

AML 스크리닝 결과와 pdf 보고서를 반환합니다.

'resourceId'별로 AML 보고서가 제공됩니다. AML 보고서를 다운로드하려면 'resourceId'가 필요합니다.

요청 URL

curl -X GET "https://rest-api.argoskyc.com/v2/report/aml?resourceId={resourceId}"

Input Data

Output 데이터

응답으로 파일이 다운로드 됩니다.

8. GET /image

요청 URL

curl -X GET "https://rest-api.argoskyc.com/v2/image?submission_id={submission_id}&type={type}"

Input 데이터

Output 데이터

응답으로 파일이 다운로드 됩니다.