신한 Open API

1.1. 목적

본 문서는 “신한은행 오픈 API”(이하 “오픈API”)를 이용하는 제휴 업체(이하 “이용기관”)에서 최초 연동 개발 시 참고할 수 있는 연동 구조에 대한 설명 및 개발 참고 가이드를 제공하는 것을 목적으로 한다.

1.2. 주요 내용

신한은행 오픈 API를 이용하기 위해서는 사전에 은행 담당자와 협의하여야 하며 이용절차, 개별 서비스 소개 등은 오픈 API 홈페이지(https://openapi.shinhan.com)를 참고한다
개발(테스트) 서버에서 연동 서비스 개발 후 서비스 점검이 완료되어야 운영(온라인) 서버에서 호출이 가능하다. 운영 오픈 일정은 은행 담당자와 협의 후 오픈 가능하다.
인증은 이용기관 인증(2-legged), 이용자 인증(3-legged)의 2가지로 분류하고, 이에 대해서는 각 가이드 문서에서 상세히 설명한다.
본 문서는 오픈 API 서비스 업무 개발 시 ‘인증’ 부분(접근키 발급 및 갱신)에 초점을 맞춘 가이드로 개별 업무 서비스 관련해서는 홈페이지의 각 서비스별 관련 문서를 참고한다.
본 문서의 인증 가이드가 절대적인 기준은 아니며, 이용하려는 개별 서비스나 관련 감독기관의 규정 변경에 따라 그 내용이 달라질 수 있다. 그러므로 연동 개발 전 세부 항목에 대한 별도 협의 후 진행이 필요하다.

1.3. 용어

본 문서의 용어는 금융보안원에서 제공한 금융권 오픈 API 보안 점검 가이드 내 용어를 따른다.

용어	정의
운영기관	오픈API를 제공하는 오픈API시스템 운영기관(금융회사 등)을 의미. 본 문서에서는 ‘신한은행'
이용기관	오픈API를 이용하여 서비스를 개발 및 제공하는 기관(핀테크 기업 등)을 의미
오픈API 이용서비스	이용기관이 오픈API를 이용하여 제공하는 서비스 (예: 계좌잔액 조회, 거래내역분석, 송금 등)
사용자	오픈API 이용서비스를 제공하는 이용기관의 업무 관계자
이용자	이용기관의 오픈API 이용서비스를 이용하는 고객
오픈API 접근서버	오픈API에 접근하는 이용기관 서버
오픈API 이용 애플리케이션	오픈API를 이용하여 이용자에게 서비스를 제공하는 이용기관 애플리케이션(모바일 APP/Web 애플리케이션 등)
오픈API 인증키	오픈API 이용서비스가 운영기관 오픈API시스템에 등록된 정당한 서비스임을 인증하는데 사용되는 운영기관으로부터 발급받은 특정 값 또는 파일
오픈API 접근키	오픈API에 자원을 요청할 수 있는 권한이 부여된 특정 값 또는 파일(예를 들어 OAuth 구조의 access token이 이에 해당)
오픈API 관련 중요정보	이용기관이 오픈API 이용서비스를 제공하는데 사용되는 보호가 필요한 중요정보 - 이용자 개인‧신용정보 및 인증정보, 오픈API 이용 관련 인증정보 (오픈API 인증키, 오픈API 접근키 등), 암호키 등
오픈API 관련 정보자산	이용기관이 오픈API 이용서비스를 제공하는데 사용되는 이용기관 보유 정보자산 - 서버, 네트워크장비, 정보보호시스템, DBMS, 단말기, 응용프로그램, 소프트웨어, 저장매체, 문서 등

인증 연동 개발에 앞서 사전에 알아두어야 할 공통 사항에 대해 설명한다. 공통 사항은 개발 뿐만 아니라 서비스 기획 전에 고려해야 할 내용을 포함하고 있으므로, 사전에 검토하여 협의가 필요한 부분이 있으면 협의 후 진행한다.

2.1. client id, client secret

client id는 이용기관별로 발급되는 기관 식별키이고, client secret은 기관 인증, 거래 무결성 검증 등의 중요 용도로 사용되는, 절대 외부에 노출되어서는 안되는 중요정보이다. 접근키 발급 거래에서는 client secret으로 특정 키워드를 HMAC SHA256 Hash 한 값을 사용한다. client id, client secret은 신한은행 오픈 API 홈페이지에서 서비스 이용 신청이 승인되면 확인할 수 있다.
사전준비사항 : client id / client secret 코드
(개발(테스트) 시스템은 은행에서 별도 발급하여 제공)
(개발/운영 상이함)

2.2. IP White list 관리

이용기관의 IP를 등록하여 등록된 IP에서만 거래가 가능하다. IP는 신한은행 오픈 API 홈페이지에서 이용기관이 직접 등록한다..
사전준비사항 : 연동 서버 IP 등록
(개발(테스트) 시스템은 은행에서 별도 발급하여 제공)
(개발/운영 상이함)

3.1. 설명

이용자가 은행 고객이 아닌 불특정 다수를 대상으로 하는 서비스인 경우, 이용자의 이용 동의가 불필요한 경우 또는 사전에 어떠한 방식으로든 이용 동의가 이뤄진 경우에 사용하는 방식. 은행에서 이용기관만을 검증하여 접근키를 발급하고 거래가 이뤄진다.
ex) 지점 찾기, 환율 조회 등

3.2. 인증 흐름도

3.3. 2-legged 인증의 키 사용

이용기관 인증의 경우 오픈API 서비스를 이용하기 위해 1개의 키가 사용된다-접근키. 접근키는 OAuth 개념상의 access token에 해당되고, 위 그림의 ①에서 이용기관 인증이 끝나면 접근키가 발급된다.
오픈API 사용 중 접근키가 만료되었다는 에러코드를 받는 경우, 접근키를 신규로 발급하여 사용하면 되고, 접근키는 이용기관별로 멀티로 사용 가능하다. (접근키의 유효시간 : 10분, 멀티 사용 가능-멀티 사용 관련은 변경될 수 있음.)

4.1. 요청 정보

Method	POST
URL	개발(테스트) : https://dev-shbapi.shinhan.com:6443/v1/oauth/partner/token 운영(온라인) : https://shbapi.shinhan.com:6443/v1/oauth/partner/token
데이터 타입	Request : x-www-form-urlencoded Response : JSON

4.2. 요청 메시지 명세

HTTP	항목	값	필수	설명
Header	Content-Type	application/x-www-form-urlencoded; charset=UTF-8	Y
BODY	client_id		Y	사전 준비 참고
	Scope	“oob”	Y
	grant_type	“client_credentials”	Y
	timestamp		Y	client_hash 를 만들 때 사용한 unix timestamp 값
	client_hash		Y	client secret 을 가지고, “unix timestamp+’\|’+client id” 를 HMAC SHA256 처리 후 Base64 Encoding 한 값

접근키 발급 Postman 거래 샘플

4.3. 응답 메시지 명세 (정상 응답 케이스)

HTTP	항목1	항목2	값	필수	설명
Header
BODY (json)	dataHeader
	dataBody	access_token		Y
		token_type	“Bearer”	Y
		expires_in		Y	유효시간(초)
		scope	“oob”	Y

응답샘플

HTTP BODY	{ "dataHeader": {}, "dataBody": { "access_token": "abbc2930-01a7-4dfa-92eb-6c7345bf4d74", "token_type": "Bearer", "expires_in": 86400, "scope": "oob" } }

4.4. 응답 메시지 명세 (에러 응답 케이스)

HTTP	항목1	항목2	값	설명
Header
BODY (json)	dataHeader	category	“G/W”
		successCode	"1"
		resultCode		아래 에러코드 참고
		resultMessage		아래 에러코드 참고
	dataBody

응답샘플

HTTP BODY	{ "dataHeader": { "category": "G/W", "successCode": "1", "resultCode": "400", "resultMessage": "필수 parameter가 누락되었습니다." }, "dataBody": {} }

[참고] 인증 거래시 에러코드

resultCode	resultMessage
89	Access token has expired (접근키 재발급 필요)
400	필수 parameter가 누락되었습니다.
400	Invalid API Key
400	Not allowed IP address
400	access_token empty or OAuth Request Check (Authorization Bearer Check)
400	Access token does not exist (expired, revoked, replaced, unknown, ...).
400	Access token was not granted for required scope
400	Access token is disabled
401	호출이 허가되지 않은 IP 입니다.
403	client_id 검증에 실패했습니다.
403	client_hash 검증에 실패했습니다.
403	유효한 grant_type이 아닙니다.
403	OTK 사용자인증에 실패했습니다.
403	데이터 비교 실패
412	auth_key 검증에 실패했습니다.
415	charset 파싱에 실패했습니다.
500	access_token 생성에 실패했습니다.
500	access_token 갱신에 실패했습니다.
500	API plan limit exceeded.
503	auth_key 인증서버 연동에 실패했습니다.
503	API Server Connection Refused
	인증 실패

※ 주요 에러코드만 정리함.

4.5. 접근키 발급 샘플 (curl)

curl -H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" -d "client_id=클라이언트ID&scope=oob&grant_type=client_credentials&client_hash=(unix time stamp+’|’+client_id) hash 값×tamp=unix time stamp(client_hash 만들 때 사용했던 값)" https://dev-shbapi.shinhan.com:6443/v1/oauth/partner/token

4.6. 접근키 발급 샘플 코드 (java)

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.URL;
import java.net.URLEncoder;
import java.security.SecureRandom;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import javax.net.ssl.HttpsURLConnection;
import javax.net.ssl.SSLContext;

import org.apache.commons.codec.binary.Base64;

public class GetTokenSample {
	public static void main(String[] args) {
	// access token 발급 위해 필요한 기본 정보 
	final String API_KEY = "업체별 client id";
	final String SECRET_KEY = "업체별 client secret";
	final String DEV_TOKEN_URL = "https://dev-shbapi.shinhan.com:6443/v1/oauth/partner/token"; // 개발시스템 access token 발급 url (2-legged)
	String scope = "oob";
	String grant_type = "client_credentials";
	long timestamp = 0;
	
	OutputStream os = null;
	BufferedReader reader = null;
	
	String client_hash = ""; // client hash
	
	try {
		//SSL Context 생성
		SSLContext sslContext = SSLContext.getInstance("TLS");
		sslContext.init(null, null, new SecureRandom());
		HttpsURLConnection.setDefaultSSLSocketFactory(sslContext.getSocketFactory());

		// SSL 연결
		URL url = new URL(DEV_TOKEN_URL);
		HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
	
		// client hash 생성 
		// "unix time stamp+'|'+client id" 를 client secret 으로 Hmac SHA256 후 Base64 encoding & URL encoding
		Mac mac = Mac.getInstance("HmacSHA256");
		SecretKeySpec secretKey = new SecretKeySpec(SECRET_KEY.getBytes(), "HmacSHA256");
		mac.init(secretKey);
		timestamp = (System.currentTimeMillis()/1000);
		client_hash = Base64.encodeBase64String(mac.doFinal((timestamp + "|" +API_KEY).getBytes("UTF-8")));
		client_hash = client_hash.replaceAll(System.getProperty("line.separator"), "");
		client_hash = URLEncoder.encode(client_hash, "UTF-8");

		// http header 세팅
		conn.setDoInput(true);
		conn.setDoOutput(true);
		conn.setRequestMethod("POST");
		conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded; charset=UTF-8");
		
		// http body 세팅
		String httpBody = "client_id=" + API_KEY;

※ 샘플코드는 접근키 만료시 갱신 내용은 담고 있지 않음.

접근키 발급 후 실제 거래 API 이용시 메시지 형식에 대해 설명한다. 데이터부 항목은 이용하는 API 거래별로 상이하므로 공통 부분, 전체 데이터 형식에 대해 참고한다.

5.1. 요청 정보 샘플

Method	POST
URL	개발(테스트) : https://dev-shbapi.shinhan.com:6443/v1/sample
데이터 타입	Request : JSON Response : JSON

5.2. 요청 메시지 명세

HTTP	항목1	항목2	값	필수	설명
Header	Content-Type		application/json; charset=UTF-8	Y
	Accept		application/json; charset=UTF-8	N
	reqKey			N	클라이언트 요청 키 (서버측에서 별도 처리 없이 리턴하는 값)
	apiKey			Y	client id (2.1 참고)
	Authorization			Y	“Bearer”+” “+access token 값 (4.3 참고)
	hsKey			Y	client secret 을 가지고 BODY 데이터 HMAC SHA256 한 값 (아래 샘플코드 참고)
	clientIp			Y	클라이언트 IP
BODY (json)	dataHeader	subChannel		Y	이용기관별 구분 값 (별도 부여)
		성별	“M” or “F”	N	M:남성, F:여성 (실제 API 이용 대상 고객이 있을 경우 성별)
		연령대	ex) “10”	N	0~19 : “10” 20~29 : “20” … 60세 이상 : “60” (실제 API 이용 대상 고객이 있을 경우 연령대)
	dataBody	입력항목1			서비스 별 입력 항목
	dataBody	입력항목2			서비스 별 입력 항목

※ 파란색 부분이 공통 영역

요청 메시지 예시

HTTP Header	Content-Type : “application/json;charset=UTF-8” Accept : “application/json;charset=UTF-8” reqKey : 요청 기관 거래 키 (서버 별도 처리 없이 리턴) apiKey : 발급받은 client id Authorization : “Bearer “+발급받은 접근키 hsKey : 발급받은 client secret 으로 아래 BODY 데이터를 HMAC SHA256 한 값 clientIp : 클라이언트 IP
HTTP BODY	{ "dataHeader": { "subChannel": 별도 발급받은 채널 값, "성별": "M", "연령대": "30" }, "dataBody": { "입력항목1": “데이터1”, "입력항목2": "데이터2" } }

5.3. 응답 메시지 명세

HTTP	항목1	항목2	값	필수	설명
Header	Content-Type		application/json; charset=UTF-8	Y
Header	reqKey			N	클라이언트 요청 키 (서버측에서 별도 처리 없이 리턴하는 값)
BODY (json)	dataHeader	successCode	“0” or “1”	Y	0 : 정상, 1 : 오류
		resultCode		Y	successCode가 오류인 경우 출력되는 코드 값
		resultMessage			결과 메시지 successCode 가 ‘1’(오류)인 경우 에러 메시지 출력 (이 경우 아래 dataBody 항목은 빈 값으로 내려감)
	dataBody	출력항목1			서비스 별 출력 항목
	dataBody	출력항목1			서비스 별 출력 항목