KIS Developers : 한국투자증권 오픈API 개발자센터

인가코드요청

운영 : https://openapi.koreainvestment.com:9443
개발 : http://210.107.75.78:9443
개발(웹소켓) : ws://210.107.75.79:21000
가급적 개발 서버로 셋팅을 완료하고 운영으로 오픈하는 것을 권장드립니다.

인가코드요청

POST /oauth2/code-newaccount

서비스 서버 KIS Developers로 인가코드요청을 보내는 API입니다.

Request Body (* 필수입력값)

**Request Body (* 필수입력값) 목록** Name, Type, Description 정보
Name	Type	Description
appkey 필수입력	String	제휴사의 앱키 제휴 등록 후 발급받은 제휴사의 앱
redirect_uri 필수입력	String	리다이렉션 URI 제휴 등록 시 제출한 리다이렉션 URI
response_type 필수입력	String	응답구분 "code" : Authorazation 방식
service 필수입력	String	서비스구분 "2" : 기존계좌연결
corpno 필수입력	String	제휴사번호 제휴 등록된 제휴사 고유번호 5자리
partner_user 필수입력	String	고객ID 제휴사가 관리하는 고객ID
personalname 필수입력	String	고객명 제휴사가 관리하는 고객이름
personalphone 필수입력	String	고객 휴대폰번호 제휴사가 관리하는 고객 핸드폰번호
roption 필수입력	String	Return옵션 "P" : JSON
corp_name 필수입력	String	제휴사명 약관에 들어갈 제휴사명 ※ corp_name 에 한글이 포함된 경우 UriEncoding(UTF-8)으로 세팅한 후 입력
state 필수입력	String	정해진 형식 없이, 인증 과정 중 동일한 값을 유지하여 CSRF 보안위협에 대응하기 위해 임의 설정 하는 값 (일반적으로 서비스 서버 및 앱 간 세션값으로 설정)
contract_type 필수입력	String	계약종류 "0":해투부-일임계약 "1":해투부-자문계약 "2":연금RA사 "3":토러스 "4":일반
mini_yn	String	미니스탁계좌여부 Y: 고객이 계좌선택시, 미니스탁계좌만 선택가능 N: 고객이 계좌선택시, 미니스탁계좌는 선택불가가능
isa_yn 필수입력	String	ISA계좌여부 Y: 고객이 계좌선택시, ISA계좌만 선택가능 N: 고객이 계좌선택시, ISA계좌는 선택불가
reregist_yn 필수입력	String	계좌지정여부 * 아래 2가지 목적인 경우에만 필수 입력(Y) 1.재신청인 경우 반드시 "y" (소문자)로 입력 호출하여 자문계약 불가요건에 상관없이 API 재신청(=갱신토큰 재발급) 진행가능 2.고객웹뷰에 띄워지는 고객 계좌를 특정계좌로 지정하고자 할 경우 "y" 입력 * 단, 계좌지정은 웹뷰 인입한 자문사로의 자문계약등록상태가 등록, 해지, 기간만료 인 경우만 지정 가능 → acctno(10자리) 필수입력 → thco_ivst_etrs_bzep_cd(6자리) 필수입력 n or 공백: 고객의 모든 계좌 노출 ex) "y"
acctno 필수입력	String	* 아래 3가지 목적인 경우에 필수 입력 1.재신청인 경우 반드시 재신청하는 계좌번호 입력 호출하여 자문계약 불가요건에 상관없이 API 재신청(=갱신토큰 재발급) 진행가능 2.API신청 계좌가 타사자문계약등록 계좌일 경우 API신청이 불가능하게끔 설정 목적 → thco_i vst_etrs_bzep_cd(투자자문사상품코드)로 입력되지 않은 타사 자문계약 등록된 계좌로 API신청 웹뷰 인입 시, 웹뷰에 "타자문사 계약된 계좌입니다." 에러메시지 발생하면서 API신청 불가능 고객웹뷰에 띄워지는 고객 계좌를 특정계좌로 지정하고자 할 경우자문사상품코드 6자리 입력 * 단, 계좌지정은 웹뷰 인입한 자문사로의 자문계약등록상태가 등록, 해지, 기간만료 인 경우만 지정 가능 ex) "000123"

Response Body/Header (인가코드요청)

Response Body

아래는 인가코드요청 API 정상 호출 시 받으실 수 있는 Response Body입니다.

세션키(session_key)의 유효시간은 1시간입니다. 1시간 내 인가코드 요청을 마쳐주세요.

**Request Body (* 필수입력값) 목록** Name, Type, Description 정보
Name	Type	Description
session_key_expired	long	session key 유효 시간 EX) 1554611873
session_key	String	session key (유효시간 1시간) EX) "1234567f-12f5-123d-a12f1-4b12345bb123"
cache_type	String	cache_type EX) "session"
client_id	String	client id EX) "BS123nAB7Pkdl6EYvkKuSma9PFjLyK88ZoJ"

# Response Body
{
"session_key_expired": 1713763013,
"session_key": "440...57",
"cache_type": "session",
"client_id": "BS...F"
}

Response Header

아래는 Response Header입니다. Header에 있는 location의 url값을 redirect하여 계속해서 인증을 진행하실 수 있습니다.

**Response Header 목록** Name, Type, Description 정보
Name	Type	Description
Date	String	EX) Fri, 14 Oct 2022 00:44:33 GMT
X-Content-Type-Options	String	EX) nosniff
Location	String	Redirect URL 값 EX)https://210.107.75.95/mobile/nfaccount/nfaccount.jsp?cmd=MNF01010&response_type=code&...
Content-Length	String	EX) 161
X-ORACLE-DMS-ECID	String	EX) 001uaBhvabcK0kkkR06zzEiXqE0jYYz10007y1
X-ORACLE-DMS-RID	String	EX) 0:1
X-XSS-Protection	String	EX) 1; mode=block
Keep-Alive	String	EX) timeout=5, max=100
Connection	String	EX) Keep-Alive
Content-Type	String	EX) application/json

# Response Header > Location
'''
https://210.107.75.95/mobile/tradingApi/tradingApiRegist.jsp?response_type=code
&appkey=BS...qF&redirect_uri=https://...ount.jsp?cmd=TEST
&session_key=44...657&service=2&corpno=12345&partner_user=ab1234
&personalname=1w...%3D&personalphone=OA...3D&roption=P
&corp_name=ABcompany&contract_type=0&mini_yn=null&isa_yn=null
&reregist_yn=y&acctno=1234567801&thco_ivst_etrs_bzep_cd=000123
&state=thisissample

Redirect URL

URL값에는 아래와 같은 인자들이 포함되어 있습니다. 예시 URL 값은 다음과 같습니다.

https://210.107.75.95/mobile/tradingApi/tradingApiRegist.jsp?response_type=code
&appkey=BS...qF&redirect_uri=https://...ount.jsp?cmd=TEST
&session_key=44...657&service=2&corpno=12345&partner_user=ab1234
&personalname=1w...%3D&personalphone=OA...3D&roption=P
&corp_name=ABcompany&contract_type=0&mini_yn=null&isa_yn=null
&reregist_yn=Y&acctno=1234567801&thco_ivst_etrs_bzep_cd=000123
&state=thisissample

**Redirect URL 목록** Name, Type, Description 정보
Name	Type	Len	Description
response_type	String	10	"Code" : Authorazation_code 방식 EX) "code"
appkey	String	36	포탈에서 발급된 고객의 APPKey EX)"ABC5pFKriXyXaKLavYaBCu9KDLSkdlskjfkj..."
redirect_uri	String	500	포탈에서 등록된 고객의 Redirect URI EX)https://openapi.koreainvstment.com:8090/api
session_key	String	26	G/W 에서 발급하는 UUID 를 세션키로 사용 (유효시간 1시간) EX)"1234567f-12f5-123d-a12f1-4b12345bb123"
corpno	String	5	제휴사번호 EX)"12345"
partner_user	String	256	제휴사회원번호 EX)"pUser01"
personalname	String		고객명 EX)"홍길동"
personalphone	String	256	휴대폰번호 EX)"01000000000"
roption	String	1	요청 Option P - post(json body방식) EX)"P"
corp_name	String	60	제휴사명 EX)"한국투자증권" ※ corp_name 에 한글이 포함된 경우 UriEncoding(UTF-8)으로 세팅한 후 입력
prdt_type_cd	String	2	상품유형 01(주식) 22(연금저축) 03(국내파생) 08(해외파생) EX) "01"
overseas_yn	String	1	해외주식신청여부(1=신청 0=미신청) EX) "1" or "0"
api_yn	String	1	API신청여부(1=신청 0=미신청) EX) "1" or "0"
ad_dis_prdt_cd	String	6	당사에서 부여한 자문일임코드(6자리) EX) "123123"
ivac_id	String	16	제휴사에서 부여한 자문일임회원ID(16자리), 당사와 자문제휴인 경우 필수 EX) "AB20220908000021"
mini_yn	String	1	미니스탁계좌여부(Y=신청 N=미신청) EX) "Y" or "N" or null
isa_yn	String	1	ISA계좌여부(Y=신청 N=미신청) EX) "Y" or "N" or null
reregist_yn	String	1	계좌지정여부 EX) "Y" or null
acctno	String	10	계좌지정계좌번호(10자리) EX) "1234567801" or null
thco_ivst_etrs_bzep_cd	String	6	당사 투자자문사상품코드(6자리) EX) "000123" or null

제휴사명(corp_name) 인자에 한글이 포함된 경우 문자열이 깨질 수 있습니다. 해당 경우 encodeURIComponent 등의 메소드를 사용하여 UriEncoding(UTF-8)으로 세팅한 후 전달해주시면 됩니다.

Header에 있는 location의 url값을 redirect하시면 아래와 같은 화면이 나타나 계속해서 인증을 진행하실 수 있습니다.

위와 같이 계좌개설 화면이 뜨면, 발급받으신 테스트 계좌 정보를 사용하셔서 일련의 과정(서비스 이용, 휴대폰 인증, 연동 계좌 선택 등)을 거쳐서 계좌 인증 완료하시면 됩니다.

계좌 인증 완료되면 KIS Developers는 등록된 Redirect URI로 인가코드를 전달합니다.

Redirect URI가 http로 등록및 입력되면 데이터 전송이 불가합니다. redirect uri는 반드시 https으로 등록되어야 합니다.

기존계좌 API신청 종료단계 가이드

기존계좌 API신청 종료단계에서 유의하셔야 할 사항들을 안내드립니다.

Response Body (계좌인증완료)

인증이 완료되었을 경우 Redirect URL에서 확인 가능한 Response Body입니다.

인가코드(authorization_code)의 유효시간은 5분입니다. 5분 내 접근토큰 발급을 마쳐주세요.

인증 완료 후 redirect uri 에서 받은 body 값들은 UriEncoding(UTF-8) 되어 있습니다. 따라서 decodeURIComponent, json 등의 메소드를 사용하여 디코딩해서 사용하셔야 합니다.

**Response Body (계좌인증완료) 목록** Name, Type, Description 정보
Name	Type	Description
authorization_code	String	인가코드(유효시간 5분) EX) "b8eab638-775a-4d6f-b56c-bebaa882c266"
acctno	String	계좌번호 EX) "12345678"
acct_prdt_cd	String	상품유형 01(주식) 22(연금저축) 03(국내파생) 08(해외파생) EX) "01"
partner_user	String	제휴사회원번호 제휴사가 관리하는 회원ID = 자문일임계약ID 제휴사가 관리하는 회원ID = 자문일임계약ID
personalseckey	String	고객식별키 EX) "cad38v5aa4d6fbzccd6czbebaa8….............."
bankcode	String	은행코드 EX) "00010"
virtualacctno	String	외화가상계좌번호 EX) "001231108721"
state	String	정해진 형식 없이, 인증 과정 중 동일한 값을 유지하여 CSRF 보안위협에 대응하기 위해 임의 설정 하는 값 (일반적으로 서비스 서버 및 앱 간 세션값으로 설정)
roption	String	요청 Option P - post(json body방식)
corp_name	String	제휴사명 EX) "%ED%95%9C..." UriEncoding(UTF-8) 된 상태
cust_name	String	cust_name EX) "%EB%B0%95..." UriEncoding(UTF-8) 된 상태

접근토큰발급

운영 : https://openapi.koreainvestment.com:9443
개발 : http://210.107.75.78:9443
개발(웹소켓) : ws://210.107.75.79:21000
가급적 개발 서버로 셋팅을 완료하고 운영으로 오픈하는 것을 권장드립니다.

접근토큰발급 API

POST /oauth2/tokenP

서비스 서버가 Redirect URI를 통해 전달받은 인가코드로 접근토큰발급을 요청합니다.

Request Body

**Request Body (* 필수입력값) 목록** Name, Type, Description 정보
Name	Type	Description
appkey 필수입력	String	제휴사의 앱키 제휴 등록 후 발급받은 제휴사의 앱키
grant_type 필수입력	String	권한부여 타입 "authorization_code" : 법인 권한 부여
appsecret 필수입력	String	제휴사의 비밀키 제휴 등록 후 발급받은 제휴사의 비키
personalseckey 필수입력	String	고객식별키 트레이딩 API 에서 활용
code 필수입력	String	인가코드 Redirect URI로 받은 인가코드
corpname 필수입력	String	제휴사코드 or 제휴사명 가급적 제휴사코드로 입력 EX) "12345" or "한국투자증권"

Response Body

접근토큰발급 API 호출 시, KIS Developers는 인가코드를 확인하여 접근토큰(access_token), 갱신토큰(refresh_token)을 발급해 서비스 서버에 전달합니다.

**Request Body 목록** Name, Type, Len, Description 정보
Name	Type	Len	Description
access_token	String	350	고객 접근토큰 EX) "eyJ9eXAiOi...."
expires_in	Long		접근토큰 유효시간(초)(90일) EX) 7776000
access_token_token_expired	String		접근토큰 유효기간(일시표시) EX) "2024-07-14 14:04:07"
refresh_token	String	350	고객 리프레쉬 토큰 EX) "eyJ9eXBiXi...."
refresh_token_expires_in	Long		리프레쉬 토큰 유효시간(초)(약1년 6개월) EX) 48000000
refresh_token_token_expired	String		리프레쉬 토큰 유효기간(일시표시) EX) "2025-10-23 03:24:07"
token_type	String	20	토큰 유형 EX) "Bearer"

 {
    "access_token": "eyJ...qsg",
    "refresh_token_expires_in": 48000000,
    "refresh_token": "eyJ...2nA",
    "access_token_token_expired": "2024-07-14 14:04:07",
    "token_type": "Bearer",
    "refresh_token_token_expired": "2025-10-23 03:24:07",
    "expires_in": 7776000
    }

접근토큰과 갱신토큰의 유효시간은 각각 아래와 같습니다.

**접근토큰과 갱신토큰의 유효시간 목록** 토큰명, 내용, 유효시간(초) 정보
토큰명	내용	유효시간(초)
접근토큰(access_token)	유저 엑세스 토큰 값	7,776,000초 (90일)
갱신토큰(refresh_token)	유저 리프레시 토큰	48,000,000초 (약 1년 6개월)

접근토큰갱신

운영 : https://openapi.koreainvestment.com:9443
개발 : http://210.107.75.78:9443
개발(웹소켓) : ws://210.107.75.79:21000
가급적 개발 서버로 셋팅을 완료하고 운영으로 오픈하는 것을 권장드립니다.

접근토큰발급 API

POST /oauth2/tokenP

접근토큰(access_token) 만료 시, 갱신토큰(refresh_token)으로 접근토큰갱신을 요청합니다.

Request Body

**Request Body (* 필수입력값) 목록** Name, Type, Description 정보
Name	Type	Description
appkey 필수입력	String	제휴사의 앱키 제휴 등록 후 발급받은 제휴사의 앱키
grant_type 필수입력	String	권한부여 타입 "refresh_token" : 갱신 권한 부여
appsecret 필수입력	String	제휴사의 비밀키 제휴 등록 후 발급받은 제휴사의 비밀키
refresh_token 필수입력	String	고객 리프레쉬 토큰

Response Body

KIS Developers는 갱신토큰(refresh_token)을 확인하여 접근토큰(token; access_token)을 갱신해 서비스 서버에 전달합니다.

**Request Body 목록** Name, Type, Len, Description 정보
Name	Type	Len	Description
access_token	String	350	고객 접근토큰 EX) "eyJ9eXAiOi...."
expires_in	Long		접근토큰 유효시간(초)(90일) EX) 7776000
access_token_token_expired	String		접근토큰 유효기간(일시표시) EX) "2024-07-14 14:04:07"
refresh_token	String	350	고객 리프레쉬 토큰 EX) "eyJ9eXBiXi...."
refresh_token_expires_in	Long		리프레쉬 토큰 유효시간(초)(약1년 6개월) EX) 48000000
refresh_token_token_expired	String		리프레쉬 토큰 유효기간(일시표시) EX) "2025-10-23 03:24:07"
token_type	String	20	토큰 유형 EX) "Bearer"

{
    "access_token": "eyJ...qsg",
    "refresh_token_expires_in": 48000000,
    "refresh_token": "eyJ...2nA",
    "access_token_token_expired": "2024-07-14 14:04:07",
    "token_type": "Bearer",
    "refresh_token_token_expired": "2025-10-23 03:24:07",
    "expires_in": 7776000
    }

접근토큰폐기

아래 > 을 눌러 확인해주세요. * 는 필수값입니다.

운영 : https://openapi.koreainvestment.com:9443
개발 : http://210.107.75.78:9443
개발(웹소켓) : ws://210.107.75.79:21000
가급적 개발 서버로 셋팅을 완료하고 운영으로 오픈하는 것을 권장드립니다.

접근토큰폐기 API

POST /oauth2/revokeP

접근토큰 폐기 시, 사용 중인 접근토큰(token; access_token)으로 접근토큰갱신을 요청합니다.

Request Body

**Request Body 목록** Name, Type, Description 정보
Name	Type	Description
appkey 필수입력	String	제휴사의 앱키 제휴 등록 후 발급받은 제휴사의 앱키
token 필수입력	String	고객 접근토큰
appsecret 필수입력	String	제휴사의 비밀키 제휴 등록 후 발급받은 제휴사의 비밀키

Response Body

KIS Developers는 접근토큰(token; access_token)을 확인하여 폐기 후 아래와 같은 메시지를 서비스 서버에 전달합니다.

**Request Body (* 필수입력값) 목록** Name, Type, Description 정보
Name	Type	Description
code	String	HTTP 상태
message	String	응답메세지 "접근토큰 폐기에 성공하였습니다."

{
        "code": 200,
        "message":"접근토큰 폐기에 성공하였습니다."
    }

true friend 한국투자 Open API

true friend 한국투자 Open API

사이트맵

기존계좌 API 신청

인가코드요청

인가코드요청

Request Body (* 필수입력값)

Response Body/Header (인가코드요청)

Response Body

Response Header

Redirect URL

기존계좌 API신청 종료단계 가이드

Response Body (계좌인증완료)

접근토큰발급

접근토큰발급 API

Request Body

Response Body

접근토큰갱신

접근토큰발급 API

Request Body

Response Body

접근토큰폐기

접근토큰폐기 API

Request Body

Response Body

사이트맵

기존계좌 API 신청

인가코드요청

인가코드요청

Request Body (* 필수입력값)

Response Body/Header (인가코드요청)

Response Body

200:OK

Response Header

200:OK

Redirect URL

# 예시 URL

기존계좌 API신청 종료단계 가이드

Response Body (계좌인증완료)

접근토큰발급

접근토큰발급 API

Request Body

Response Body

200: OK

접근토큰갱신

접근토큰발급 API

Request Body

Response Body

200: OK

접근토큰폐기

접근토큰폐기 API

Request Body

Response Body

200: OK

CONFIRM

CONFIRM

CONFIRM

시크릿조회

시크릿조회

제목

KIS Developers 이용약관

마지막 로그인

로그인 날짜

로그인 IP