REST API Developer Guide - developers.koscom.co.kr · 페이지 5 / 80 계좌기반 조회 자산...

자본시장 공동 핀테크 오픈플랫폼

REST API Developer Guide

Version 0.91(Draft), 2016-07-26

페이지 0 / 80

오픈플랫폼 운영 담당자

코스콤 박재성 팀장

(02)767-7831

[email protected]

김흥재 차장 (02)767-8367

[email protected]

mailto:[email protected]

mailto:[email protected]

페이지 1 / 80

본 문서는 최종 사용자에게 정보를 제공하기 위한 것이며, 코스콤은 언제든지 본 문서를 변경 또는 철회할

수 있습니다. 본 문서는 코스콤의 재산적 정보이며 코스콤의 사전 서면 동의 없이 본 문서의 전체 혹은 일부

를 복사, 전송, 재생, 공개, 수정 또는 복제할 수 없습니다.

코스콤은 본 문서의 사용으로 인해 발생되는 직, 간접 손실이나 손해(수익의 손실, 사업의 중단, 영업권 또는

데이터 손실 포함)에 대해서는 (상기 손실이나 손해에 대해 사전에 명시적으로 통지를 받은 경우라 하더라도)

귀하나 제3자에게 책임을 지지 않습니다.

Copyright © 2016 KOSCOM, All right reserved.

페이지 2 / 80

개정내역

버전 개정일 개정내역 비고

0.91 06.07.26 Request 요청 중 불필요한 필드 삭제

(DN, 실계좌번호 등)

- 관련 Json sample 수정

Sandbox 개발자 센터 안내 추가 (19p)

API 호출 공통사항 추가 (29p)

증권사 제공 API 중 accInfo 블럭 위치변경

(빨간색으로 표시)

0.92 06.07.27 OAuth 인증 Type API 호출 시 header 에

apikey 삽입 정책 삭제 (15p)

페이지 3 / 80

Chapter 1. 자본시장 공동 핀테크 오픈플랫폼 개요

자본시장 공동 핀테크 오픈플랫폼(이하, 오픈플랫폼)은 증권회사를 포함하는 금융투자회사,

유관기관, 기타 정보제공벤더가 제공하는 데이터 및 서비스를 표준화된 프로토콜, 단일

인증방식, 표준 메시지 스펙으로 핀테크 기업과 기타 3rd 파트너에게 API를 제공하는 중계

플랫폼 입니다.

페이지 4 / 80

Chapter 2. 오픈플랫폼 제공 API

제공 API 유형

오픈플랫폼에서 제공하고 있는 API는 크게 금융거래정보를 받기 위한 것과 기타 정보를

전달하기 위한 것으로 나뉩니다. 금융거래정보API는 주로 금융회사의 계좌를 기반으로 하고

있으며, 관련법령에 따라 본인의 동의절차를 거쳐 제3자에게 제공되어야 하기 때문에

추가적인 권한확인 절차가 요구됩니다.

계좌기반 API를 사용하여 개발한 서비스는 요청 메시지의 키가 되는 실계좌번호를

노출시키지 않고, 안전하게 제3자에게 제공하기 위해 서비스 이용자가 금융투자 핀테크

포탈에 가입하여 가상계좌번호를 발급하고, 금융거래정보 제3자제공 동의서를 작성한 후

가상계좌번호를 사용하고자 하는 핀테크 서비스에 연결하는 선행과정이 필요합니다. 그리고

핀테크 서비스가 해당 API를 이용하려고 시도하는 과정에서 서비스 이용자의 확인과정이

개입됩니다.

계좌기반 API를 제외한 나머지 API는 금융투자 핀테크 포탈 가입 여부와 관계없이

오픈플랫폼에 등록이 된 핀테크 기업의 경우 이용자에게 서비스를 제공할 수 있습니다.

API

유형 API명 제공구간 기능(데이터)

제공주체

(속성)

서비스

연동

오픈플랫폼

가입여부 확인

오픈플랫폼

-> 핀테크

핀테크 서비스 이용자가 오픈플랫폼

회원인지 확인하기 위한 API

▶ 가상계좌번호 발급, 정보제공동의서 작성 등

사전절차 안내 필요 여부 확인用

오픈플랫폼

(일반정보)

가상계좌

목록 조회

핀테크 서비스 이용자가 발급받은 가상

계좌번호 목록을 금투사 名과 함께 제공

▶ 금투사名과 가상계좌목록을 핀테크

서비스 App에 출력하여 이용할 계좌를

간편하게 선택할 수 있도록 함

페이지 5 / 80

계좌기반

조회

자산

포트폴리오 조회

금투사

->

오픈플랫폼

->

핀테크

투자자의 자산내역(증권, 파생, 펀드,

기타 금융상품)을 보유비율(구성비)로

제공

▶ 자산 상세내역(투자금액, 보유주식수 등

을 노출시키지 않고, 자산의 구성 비율만 부담

없이 제공할 수 있게 함으로써 투자

성향분석 등 자문의 기초자료로 활

용 가능

금투사

(민감도

낮은

금융정보)

관심종목

조회

투자자가 HTS 등에 등록해 놓은 관심종목 리

스트를 조회할 수 있는 기능

▶ 투자자가 관심을 보이는 종목에 대해

뉴스, 분석정보, 이벤트(급등락, 공시 등)의

정보를 능동적으로 제공할 수 있는 기초

자료로 활용 가능

계좌잔고

조회

투자자의 자산내역을 보유종목, 보유수

량, 손익, 예탁금 등으로 상세하게 제공

▶ 통합자산관리, 자문서비스를 위한 기본

정보, 향후 주문서비스 확대 시 자산변동

실시간 조회용으로 활용

금투사

(민감도

높은

금융정보)

거래내역

조회

금융상품의 매수, 매도, 현금입출금 내역을

지정한 기간별로 조회하기 위한 API

▶ 투자성향 분석, 매수/매도 시점 분석을

통해 거래행태에 대한 자문 가능

페이지 6 / 80

시세조회

유가증권

및

코스닥

시세조회

(6종)

코스콤

->

오픈플랫폼

->

핀테크

▶ 종목리스트 조회 API

▶ 종목마스터 데이터 조회 API

: 종목명, 상하한가, 전일거래량, 기준가 등

▶ 종목별 과거 데이터 조회 API

: 일, 주 및 월별 과거 시세 제공

▶ 투자자별 종가 정보 조회 API

: 투자주체별 매수/매도 거래량, 거래대금

▶ 종목별 호가 정보 조회 API

▶ 종목별 체결 정보 조회 API

: 현재가, 체결량, 누적거래량

코스콤

(일반정보)

선물시세

조회

(6종)

-9월 제공









옵션시세

조회

(6종)

-9월 제공









페이지 7 / 80

정보검색

금융뉴스

검색

(3종)

핀테크-

>오픈플랫폼-

>금투사,

핀테크

▶ 통합 시세조회 서비스 API

▶ 기업정보 조회 API (재무 데이터)

▶ 금융 뉴스검색 API (키워드, 분야별)

핀테크/

위버플

(일반정보)

정보제공

재무정보

제공

(2종)

▶ 종목별 영업이익률 조회 API

▶ 업종별 평균 영업이익률 조회 API

핀테크/

BSMIT

(일반정보)

비재무정보제공

(1종)

▶ 비재무정보(ESG*)기반

▶ 기업가치분석 조회 API

*환경, 소셜, 거버넌스

핀테크/

지속가능

발전소

(일반정보)

API 이용 절차

향후 절차 제공 예정

페이지 8 / 80

Chapter 3. 핀테크 서비스 등록

등록 절차를 현재 관련기관들과 조율 중입니다. 향후 확정되면 알려드리겠습니다. 등록절차

가 마련되기 전까지는 코스콤으로 연락 주시면 개발에 필요한 것들을 준비해드리겠습니다.

페이지 9 / 80

Chapter 4. API 인증 방식

인증방식

사용하고자 하는 API에 따라 지정된 인증방식을 사용해야 하며 크게 분류하면 다음과

같습니다.

API Key Authentication: 계좌기반API를 제외한 일반정보 API를 사용하는 경우

핀테크 서비스를 등록할 때 받은 API Key를 지정된 HTTP헤더에 넣어 전송하고,

이를 오픈플랫폼에서 인증하는 방식

OAuth: 계좌기반API를 사용하는 경우 핀테크 서비스를 등록할 때 받은 API

Key(Client ID)와 Client Secret을 지정된 HTTP헤더에 넣고, 추가로 API를

호출하기 전 이용자로부터 정보접근 동의를 받은 후 오픈플랫폼으로부터 제공받는

Access Token을 헤더에 포함시켜 인증을 받는 방식

API Key Authentication

API Key Authentication만을 사용하는 API는 주로 민감정보가 포함되지 않은 데이터를

요청•응답하는 경우이며, 핀테크 서비스를 등록할 때 받은 API Key만으로 API호출권한을

확인하게 됩니다.

HTTP method(GET, POST)에 따라 API Key를 전달하는 방식이 달라지며, GET일 경우는

API URL의 query parameter로 전달하고, POST방식은 HTTP header의 필드로 전달해야

합니다.

GET 방식: URL query parameter인 apikey에 넣어 전송

curl -X GET -H "Cache-Control: no-cache" -H

"https://sandbox-

apigw.koscom.co.kr/v2/market/stocks/kospi/list?apikey=l7xx230ef2235e34448c982eb192ac98e206"

페이지 10 / 80

POST 방식: HTTP header의 apikey 필드에 API Key를 넣어 전송

curl -X POST -H "apikey: l7xxf234248b6fbd42a1a6844861524b2320" -H "Content-Type: application/json" -H

"Cache-Control: no-cache" -H

-d '{

"partner": {

"comId": "COMPANY-ID",

"srvId": "CLIENT-ID"

},

"commonHeader": {

"reqIdPlatform": "android",

"reqIdConsumer": "tx-001",

"certDn": Ou=KOSCOM,

"ci":

"35SA9SlOxR3vOSQF0aXztoWpwgLmXFZbH074ZcqwbPBCIwt4xo1I0az0lu7qp5nuDRs78QNJxAnZk5SP/XB8Y

w=="

},

"body": {

"korName": "홍길동"

}

}' "https://sandbox-apigw.koscom.co.kr/v1/common/member/register/search"

OAuth

OAuth인증체계를 사용하는 API는 민감정보가 포함된 데이터를 요청•응답하는 경우이며,

API호출 전에 데이터 소유권자(Resource Owner)을 개입시켜 정보접근의 승인을 받는

과정이 포함되어있습니다. 승인과정이 정상적으로 처리되면 오픈플랫폼은 API호출에 필요한

access token을 발급하며, 핀테크 서비스는 API를 호출할 때 access token을 포함시켜

전송하면 됩니다.

오픈플랫폼에서 제공하는 OAuth버전은 2.0이며 핀테크 서비스의 유형과 보안수준에 따라

access token을 발급하는 방법이 구분됩니다. 인증방식에 대한 선택은 오픈플랫폼 관리자와

협의 후 결정하시면 되며, 비즈니스 모델과 보안수준에 따라 결정됩니다.

Authorization Code Grant Type(Server-Side Web Application Flow): 이 방식은

데이터소유자(Resource Owner, 서비스 이용자)에게 데이터 접근에 대한 권한을 위임

받아 access token을 오픈플랫폼으로부터 받아오고, 만기(expiration time)을 갖는

access token을 갱신(refresh token)할 수 있는 권한도 부여 받아 데이터소유자의

승인과정 없이도 API를 통해 데이터에 접근할 수 있는 인증방식입니다. 따라서 주로

서버 사이드의 웹 애플리케이션에서 API를 사용할 경우에 적합하며, 주기적으로

페이지 11 / 80

데이터소유자의 위임을 받아 데이터에 접근할 필요가 있는 비즈니스 모델에

사용됩니다.

Implicit Grant Flow(Client-Side Web Application Flow): 이 방식은 핀테크

서비스의 최종 단말(앱, 브라우저 등)에서 직접 데이터소유자가 데이터접근동의를

하고 access token을 받아 단말 프로그램에서 API를 호출하는 구조에 적합합니다.

따라서 응답으로 온 데이터를 주로 화면에 출력하는 비즈니스 모델에 사용됩니다.

발급된 access token의 유효시간을 연장시키는 refresh token은 지원되지 않으며,

access token의 유효시간이 만료되면 데이터접근동의절차를 다시 수행해야 합니다.

Authorization Code Grant Flow

이 방식을 사용하기 위해서는 각종 token, API를 통해 받은 데이터를 안전하게 보관할

수 있는 보안체계가 마련되어야 하며, 데이터접근권한 위임절차 및 동시에 이용자가

위임했던 데이터접근권한을 무효화시키기 위한 수단이 서비스에 마련되어야 합니다.

또한 서비스단말을 통해 authorization code를 받아오고, 그 응답은 애플리케이션

서버로 redirect되기 때문에 핀테크 서비스 사용자 세션정보, authorization code, access

token, refresh token 간의 매핑정보 관리 체계를 만들고 보안에 유의해야 합니다.

[Authorization Code Grant Flow 절차]

페이지 12 / 80

0~1. 핀테크 서비스 자체 인증 수행

2~6. Authorization Code 요청과 응답

데이터소유자의 동의를 통해 authorization code를 받기 위한 flow를 클라이언트

사이드에서 수행하고, 그 결과를 서버 사이드에 구현된 OAuth callback listener로

redirect하는 과정입니다.

(2) Authorization Code 요청

Method GET

Endpoint > https://sandbox-

apigw.koscom.co.kr/auth/oauth/v2/authorize

>https://apigw.koscom.co.kr/auth/oauth/v2/authorize

Parameters response_type=code&

client_id=클라이언트 ID(API Key)&

redirect_uri=구현된 callback listener 주소&

scope=지정된 scope&

state=돌려받을 opaque value

response

_type

code

client_id 서비스 등록 시 부여 받은 Client ID(API Key)

redirect_

uri

핀테크 기업의 웹 서버에 구현된 OAuth callback listener

주소이며, 이 값은 최초 서비스 등록 시 입력했던 값과 동

일해야 함

scope API가 접근하고자 하는 자원 범위 (현재는 사용안함)

state state 값은 본래 cross-site request forgery(CSRF) 공격에

대응하기 위해 사용하나, 대체로 사용자 세션정보를 넣어

authorization code 요청의 응답이 서버로 redirect되었을

때 어느 사용자의 authorization code인지를 구분하기 위

해 사용하는 것이 보통임. 요청에 전송했던 값이 응답에

그대로 반환됨

Example https://sandbox-

apigw.koscom.co.kr/auth/oauth/v2/authorize?response_t

ype=code&client_id=l7xxf234248b6fbd42a1a6844861524

b2320&redirect_uri=http://localhost:8080/OpenAPITest/

callbacknew&scope=test.kiwoom&state=70e86bd5

페이지 13 / 80

(3, 4) Authorization Code 부여 (데이터접근위임동의)에 대한 승인정보 입력

(2)번을 요청하면 그 응답으로 Authorization Code를 받아오는 것을 승인할 수

있도록 아래와 같은 권한정보입력 창을 응답으로 내려줍니다.

핀테크 서비스 이용자가 금융투자 핀테크 포털 가입 시 사용했던 아이디와

비밀번호(또는 OTP)를 입력하고 로그인 버튼을 누르면, 오픈플랫폼은 이용자가

입력한 정보를 확인하여 정상적인 경우 authorization code를 응답으로 받을 수

있습니다. 비밀번호 또는 OTP가 연속으로 틀린 경우 계정잠김상태로 전환됩니다.

오픈플랫폼 관리자가 비밀번호 초기화 또는 OTP를 초기화할 수 있도록 안내가

필요합니다.

(5, 6) Authorization Code 부여

(3), (4)번 절차가 정상적으로 수행되면 오픈플랫폼은 authorization code를

응답으로 내려주되, 핀테크 서비스 등록과 Authorization Code 요청 시 지정된

redirect_uri로 응답을 전달할 수 있도록 http 헤더의 status code를 302로 설정하여

응답을 전송하며, redirect된 응답은 핀테크 서비스 서버 사이드에 구현된 OAuth

Callback Listener (Servlet 등)로 전달되며, Callback Listener로 유입된 응답

parameter에서 state와 code를 추출하고 누구의 authorization code인지를

확인(state에 설정한 식별정보 이용)하여 다음 절차인 access token을 요청합니다.

에러처리는 에러처리 챕터를 참고하시기 바랍니다.

페이지 14 / 80

7~8. Access Token 요청과 응답

(7) Access Token 요청

실제 API를 호출할 때 필요한 것은 access token입니다. Access token은

authorization code를 이용하여 요청할 수 있습니다.

Method POST


apigw.koscom.co.kr/auth/oauth/v2/token

> https://apigw.koscom.co.kr/auth/oauth/v2/token

Header authorization client_id와 client_secret을 “:”으로 연결하여 base64

로 encoding한 값을 아래 형식으로 설정

Basic Base64(client_id:client_secret)

Content-type Application/x-www-form-urlencoded

Parameters grant_type=authorization_code&

code=할당받은 authorizationcode&

redirect_uri=구현된 callback listener 주소

grant_type authorization_code

code Authorization code 요청을 통해 받은 code

redirect_uri 핀테크 기업의 웹 서버에 구현된 OAuth callback

listener 주소이며, 이 값은 최초 서비스 등록 시 입

력했던 값과 동일해야 함

Example

(8) Access Token 응답

Access Token의 응답은 JSON형태로 제공되며 다음의 항목이 포함되어 있으며,

응답은 정상일 경우 status는 200으로 redirection없이 전송됩니다.

access token API호출시 사용할 access token

refresh token Access token을 갱신하기 위해 사용되는 token

scope Authorization code요청시 지정된 scope

token_type Bearer

expires_in 유효시간 (초)

https://sandbox-apigw.koscom.co.kr/auth/oauth/v2/token


페이지 15 / 80

API 호출

Access Token발급절차를 통해 받은 access token을 HTTP 헤더 내의 지정된 필드에

포함시켜 API를 호출하면 됩니다.

Method POST

Endpoint 호출하고자 하는 각 API의 endpoint

Header Authorization 발급받은 access token을 아래 형식으로 설정

Bearer access_token

curl -X POST -H "Authorization: Bearer 748c46c8-940f-4eb8-a553-4656253dbac6" -H "Content-Type:

application/json" -H "Cache-Control: no-cache" -d '{

"accInfo": {

"vtAccNo": "160657695589800099"

},

"balanceRequestBody": {

"queryType": {

"assetType": "string",

"count": 0,

"page": "string"

}

},

"commonHeader": {

"ci":

"Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rgfgdfgfhpf5vmzjaA==",

"reqIdConsumer": "string"

},

"devInfo": {

"ipAddr": "IP",

"macAddr": "string"

},

"partner": {

"comId": "F0000",

"srvId": "Mock"

}

}' "https://10.10.10.101:8443/v1/cyber/account/balance/search"

페이지 16 / 80

Access Token 갱신 (Refresh Token) 요청,

※ Refresh token 기능 지원여부는 추후 결정될 것이므로 이를 고려한 비즈니스 모

델은 사전 협의 필요

Access token 발급 메시지에는 갱신에 사용되는 refresh token(refresh_token)과

유효시간(expires_in)이 들어있습니다. 필요에 따라 각 access token이 만료되기 전에

갱신을 요청하면 새로운 access token을 발급받을 수 있습니다.

Method POST


apigw.koscom.co.kr/auth/oauth/v2/token

> https://apigw.koscom.co.kr/auth/oauth/v2/token




content-type Application/x-www-form-urlencoded

Parameters grant_type=refresh_token&

refresh_token=발급받은 refresh_token&

scope=지정된 scope

grant_type refresh_token

refresh_token Access token을 발급받을 때 포함되어 있던 refresh

token

scope 지정된 scope으로 선택항목

Example

Access Token 갱신 (Refresh Token) 응답

Access token 요청에 대한 응답과 동일한 형태의 JSON 메시지가 전달됩니다.



페이지 17 / 80

Token Revocation

핀테크 서비스를 구현할 때 반드시 고객이 위임하였던 정보접근권한(access token,

refresh token)을 무효화할 수 있는 기능을 제공 및 사전 안내해야 하며, 이를

OAuth에서는 Token revocation으로 구현할 수 있습니다. Revocation된 후에 다시

API를 통해 서비스를 재 사용하려면 OAuth 인증 flow를 다시 수행하면 됩니다.

Method POST or DELETE


apigw.koscom.co.kr/auth/oauth/v2/token/revoke

>

https://apigw.koscom.co.kr/auth/oauth/v2/token/r

evoke




content-type Application/x-www-form-urlencoded

Parameters token=발급받았던_token&

token_type_hint=access_token또는refresh_token

token rovoke대상이되는 access token

token_type_hi

nt

access_token, refresh_token

Token Revocation 응답

성공일 경우 JSON형식으로 {“result”:”revoked”}로 전송

페이지 18 / 80

Implicit Grant Flow

현재 제공되는 OAuth 인증체계를 사용하는 API 중 implicit grant type을 지원하는

API는 없습니다. 향후 본 인증체계를 사용하게 되는 경우에 상세 내용을 제공하겠습

니다.

페이지 19 / 80

Chapter 5. Sandbox 개발자 센터 이용

API에 대한 개발가이드와 테스트를 하기 위해서는 오픈플랫폼 개발자 센터

(http://developers.koscom.co.kr) 회원에 가입하시고, 이메일로 승인대기 안내 메일이

발송되며, 관리자에 의해 승인 후 로그인이 가능합니다. (공식 오픈 까지는 회원가입 후

오픈플랫폼 관리자에게 메일 또는 전화를 주시면 승인해드리겠습니다.)

Sandbox 개발자 센터는 API 개발에 관련된 가이드와 개발 및 테스트용 핀테크 서비스

응용프로그램(앱 또는 웹 서비스이며, 이하 앱)을 등록하여 개발단계에 이용하실 수 있도록

관련 기능을 제공합니다.

핀테크 서비스 애플리케이션 등록

대시보드 > 어플리케이션 에서 하단에 있는 ‘응용 프로그램 추가’ 버튼을 통해 앱을 생성

합니다.

Application 정보 등록

응용 프로그램 이름

플랫폼 (서비스 플랫폼 유형이며, 참고정보이며 이 값에 따라 제공되는 API 특성이

결정되지는 않습니다.)

설명

‘Application 정보’에 해당 항목을 입력하고, ‘Next Step’ 버튼을 클릭 합니다.

http://developers.koscom.co.kr/

페이지 20 / 80

API 관리 정보 등록

API 추가

-Subscribing 을 원하는 API 를 선택

이용약관 동의

‘API 관리’ 탭에서는 사용할 API 를 선택하고, 그에 해당하는 API ‘이용 약관에 동의’ 하고,

더 이상 사용할 API 가 없으면 ‘Next Step’버튼을 누릅니다.

페이지 21 / 80

인증 정보 등록

Callback URL

Scope

유형

‘인증’ 의 Callback URL, Scope, 유형 항목은 사용할 API 의 인증 방식이 OAuth (현재는

OAuth2.0 만 지원)일 때는 필수로 입력해야 합니다.

유형은 ‘public’ 를 선택 합니다. (현재는 OAuth2.0 Grant Type 중 Authorization Code

방식만 지원함)

‘API 문서 > 서비스’의 Swagger UI 로 OAuth2.0 을 테스트 하시려면, Callback URL 을

‘https://developers.koscom.co.kr/resources/oauthCallback.html’ 와 같이 입력 하세요.

‘저장’ 버튼을 누르고 정상적으로 접수가 되면 앱이 추가 되고, 앱 상태가 ‘승인 보류’가

됩니다.

코스콤 개발자센터 관리자가 해당 앱의 사용을 승인 하면 회원정보에 등록된 이메일로 ‘앱

승인’ 메일을 받으실 수 있습니다.

앱 등록 정책에 맞지 않으면 해당 사유와 함께 거부 될 수도 있습니다.

https://developers.koscom.co.kr/resources/oauthCallback.html

페이지 22 / 80

API 테스트

‘APIs & 플랜’ 메뉴에서 테스트 하려는 API 의 인증 유형을 확인 합니다.

인증방식 - API Key Type

페이지 23 / 80

‘API 문서 > 시세 서비스 > 주식 종목’ 메뉴에서 ‘Select an Application’ 을 눌러서 앱을 선택

합니다.

앱이 보이지 않으시면 해당 API 를 사용하는 앱을 먼저 만드셔야 합니다.

‘Authentication (None)’ 버튼을 누르시고, 인증 방식을 ‘API Key’로 선택 합니다.

해당 API 의 Method 가 ‘GET’ 방식이면, ‘API Key Type’를 Query 로 선택 하시고, ‘POST’

방식이면 Header 방식으로 선택 하세요.

테스트할 API 를 선택 하시고, ‘Try it Out’ 버튼을 누르시면 아래와 같이 Response 결과를

받아 보실 수 있습니다.

페이지 24 / 80

기타 에러 코드는 별도 참조

‘Query’ 버튼을 누르시면 Request 및 다양한 랭귀지의 샘플 데이터를 참고 하실 수

있습니다.

페이지 25 / 80

인증방식 - OAuth

현재는 OAuth2.0 Grant Type 중 Authorization Code 만 지원하며, Implicit Grant Type 등은

보안수준, 비즈니스모델에 따라 협의 후 결정이 필요합니다.

‘APIs & 플랜’ 메뉴에서 ‘OAuth2.0-Authorization Code 를 지원하는 API 를 확인 합니다.

테스트할 앱을 선택하고, ‘OAuth2.0’을 선택 합니다.

Grant Type

Authorization Code’를 선택 합니다.

Client ID

앱의 API Key 값을 입력 합니다. (자동 입력)

페이지 26 / 80

Client Secret

앱의 Secret 값을 입력 합니다. (자동 입력)

Scope

앱에 등록한 Scope 값을 입력 합니다

Authorize Endpoint

‘https://sandbox-apigw.koscom.co.kr/auth/oauth/v2/authorize’ 값을 입력 합니다.

Token Endpoint

‘https://sandbox-apigw.koscom.co.kr/auth/oauth/v2/token’ 값을 입력 합니다.

‘OK’ 버튼을 누르시면, 사용자 로그인창이 오픈 됩니다.

https://sandbox-apigw.koscom.co.kr/auth/oauth/v2/authorize


페이지 27 / 80

아이디 및 비밀번호를 입력하시고, 로그인 합니다. 아이디와 비밀번호(OTP 번호)는 금융투자

핀테크 포털 가입 시 등록한 것이며, 테스트를 위해 별도로 부여될 수 있으니 관리자에게

확인이 필요합니다.

테스트할 API 를 선택 하시고, ‘Try it Out’ 버튼을 누르시면 아래와 같이 Response 결과를

받아 보실 수 있습니다.

페이지 28 / 80

‘Query’ 버튼을 누르시면 Request 및 다양한 개발언어별 샘플 코드를 참고 하실 수

있습니다.

페이지 29 / 80

Chapter 6. 금융투자회사(증권사) 제공 API 이용

현재 증권회사가 오픈플랫폼을 통해 제공하고 있는 API는 모두 계좌를 기반으로 하고

있습니다. 따라서 핀테크 서비스 회원과 증권사 고객정보를 연결시킬 식별자가 필요하며

이를 휴대폰•아이핀 본인확인 서비스를 통해 발급받은 연계정보(CI, Connecting

Information)을 사용하고 있습니다. 또한 증권사의 실제 계좌번호와 1:1로 매핑된

가상계좌번호를 오픈플랫폼 금융투자 핀테크 포탈(http://open.koscom.co.kr)에서 발급하여

연계정보와 함께 API를 통한 요청의 키로 사용합니다.

따라서 핀테크 서비스가 금융투자회사가 제공하는 계좌기반 API와 같이 금융거래정보가

전달되는 API를 사용하여 개발하였다면 핀테크 서비스 이용자는 사전에 `금융투자 핀테크

포탈`에 가입하여 핀테크 서비스에 연결하고자 하는 증권회사의 실계좌번호에 연결된

가상계좌번호를 발급받아야 하며, 사용하고자 하는 핀테크 서비스에 가상계좌번호를

연결하는 과정이 선행되어야 합니다. 자세한 내용은 참고자료에 있습니다.

따라서 계좌기반 API를 사용하는 핀테크 서비스를 이용자가 사용하기 위해서는 사전에

위와 같은 이용조건을 충족했는지를 확인하는 것이 필요합니다. ‘금융투자 핀테크 포탈`에

가입하지 않은 이용자는 포탈가입을 유도해야 하며, 가입이 된 이용자라 하더라도

가상계좌발급을 받았는지 여부와 가상계좌를 핀테크 서비스에 연결하였는지를 확인할 수

있어야 합니다. 오픈플랫폼은 이를 확인하기 위한 API를 제공하고 있습니다.

API 호출 공통 사항

요청 데이터의 값 없음 표기 방법: 필수 필드이나 값이 없는 경우는 “”로 표기

응답 데이터의 값 없음 표기 방법: 필드 또는 블록이 없음(null), 필드 값이 null,

필드 값이 “null”, 필드 값이 “”로 올 수 있으므로 null체크 로직 구현의 주의 필요

숫자 표기에서 0이 9개이상 표기되어야 하는 경우는 JSON 표기법 표준에 따라

Scientific notation 사용

스펙의 required 항목은 “필수”는 값이 반드시 있어야 하거나, 적어도 값이 “”로라도

존재해야 하는 항목이며, “반환”은 요청 시 값이 그대로 응답에 실려 돌아옴을

의미하며, “선택”은 주로 다른 항목의 구분 값에 따라 필수 항목인 경우를 의미

Type의 괄호 안의 숫자는 권장 최대 길이이며, [ ]안의 숫자는 길이가 지정된 항목

페이지 30 / 80

서비스 연동 API

오픈플랫폼과 핀테크 서비스 간에 연동을 위해 금융투자 핀테크 포탈 가입여부 확인 API와

핀테크 서비스에 연결된 가상계좌를 조회할 수 있는 API를 제공합니다. 계좌기반조회 API를

사용하는 핀테크 서비스의 경우 먼저 이용자가 금융투자 핀테크 포탈에 가입했는지를 API를

통해 확인하고, 미 가입자는 금융투자 핀테크 포탈 가입화면으로 유도해야 합니다. 그리고

사용하려는 증권회사의 계좌번호에 대응되는 가상계좌번호를 발급받아 핀테크서비스에

연결(핀테크 서비스 신청)을 수행해야 합니다.

이미 금융투자 핀테크 포탈에 가입한 이용자는 핀테크서비스에 가상계좌를 연결하였는지를

확인하기 위해 핀테크 서비스 연결 여부 확인 및 가상계좌 리스트 조회 API를 이용하여

설정한 가상계좌가 있는지를 확인하고, 이용자가 원하는 계좌가 추가로 필요하다면

가상계좌발급과 연결을 안내해야 합니다.

금융투자 핀테크 포탈 가입 여부 확인 API

핀테크 서비스 이용자가 금융투자 핀테크 포탈에 가입했는지를 확인하기 위한 API

Syntax

URI

https://apigw.koscom.co.kr/v1/common/member/consent/search

https://sandbox-apigw.koscom.co.kr/v1/common/member/consent/search

HTTP methods

POST

Format

JSON <application/json; charset=utf-8>

Content-Type

Application/json



페이지 31 / 80

Authentication

header – apikey: 발급받은 API key

Request Body

Property type Required? Description

partner -

┗ comId String[5] 필수 핀테크 기업 코드

┗ srvId String(20) 필수 핀테크 서비스 코드

commonHeader

┗ reqIdPlatform String 사용안함

┗ reqIdConsumer String(20) 선택 핀테크 기업에서 사용하는 메시지 구분자

┗ ci String[88] 필수 연계정보 88byte

body -

┗ korName String(10) 필수 한글이름

Response Body


result String(12) 필수 요청의 결과로 값은: member, nonMember

Example

Request Body Example

{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"fsfsfshi23", "ci":"Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rgfgdfgfhpf5vmzjaA==" }, "body":{

"korName":"홍길동"

} }

페이지 32 / 80

Response Body Example

{ "result": "member" }

핀테크 서비스 연결 여부 확인 및 가상계좌 리스트 조회 API

핀테크 서비스 이용자가 금융투자 핀테크 포탈에서 사용하려는 핀테크 서비스에 연결한

가상계좌리스트를 조회하기 위한 API (금융거래정보 제3자 제공 동의 계좌)

Syntax

URI



HTTP methods

POST

Format


Content-Type

Application/json

Authentication

header – apikey: 발급받은 API key

Request Body


partner



commonHeader

┗ reqIdPlatform String(20) 사용안함

┗ reqIdConsumer String(20) 선택 핀테크 기업에서 사용하는 메시지 구분자



페이지 33 / 80


body Complex - 요청 메시지 본문

┗ korName String(12) 필수 한글이름

Response Body


vtAccList Array 가상계좌번호 묶음 (배열로 반복)

┗ comId String[5] 필수 금융회사 코드

┗ vtAccNo String[18] 필수 가상계좌번호

┗ vtAccAlias String(20) 필수 가상계좌번호 별칭

Example


{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"fsfsfshi23", "ci":"Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rgfgdfgfhpf5vmzjaA==" }, "body":{

"korName":"홍길동"

} }

페이지 34 / 80


{

"vtAccList":[

{

"comId": " 00002",

"vtAccNo":"160657695589800099",

"vtAccAlias":"주식투자용"

},

{

"comId":" 00002",

"vtAccNo":"160657695589800099",

"vtAccAlias":"펀드투자용"

}

] }

페이지 35 / 80

계좌기반 조회 API

계좌기반 조회 API는 증권사별로 호출 URI가 다르나 큰 틀은 동일하며 단지 증권사구분

이 URI에 포함되어 있는 구조입니다. API는 버전으로 구분되기 때문에 URI에 버전정보가

포함되어 있습니다.

URI구조

전체 URI - https://APIgateway주소/버전정보/증권사단축명/조회서비스구분

Endpoint – https://APIgateway주소/버전정보/증권사단축명/

오픈플랫폼 API gateway 주소

Production – https://apigw.koscom.co.kr

Sandbox – https://sandbox-apigw.koscom.co.kr

조회유의사항

조회는 API에 지정된 가상계좌를 조회범위로 하기 때문에 계좌속성(위탁, 펀드, 파

생상품 등)에 따라 조회조건이 충족되지 않을 수 있으므로 전 상품군을 대상으로 조

회할 경우는 주의가 필요합니다. 예로 보통 증권회사의 종합계좌는 모든 금융상품을

취급할 수 있는 것이지만 경우에 따라 파생상품과 같은 특정 상품군은 별도로 관리

되는 증권회사도 있으며, 종합계좌 개념을 도입하지 않는 증권사도 존재합니다. 따라

서 종합계좌라고 판단되어 KOSPI200 파생상품 잔고를 조회하였을 때 응답에 해당상

품이 반드시 포함될 것이라 판단하고 비즈니스를 설계하면 안됩니다.

예로 자산포트폴리오조회와 계좌잔고조회의 경우 모든 상품군을 조회범위에 포함

하는 ‘ALL’검색조건을 지원하는 증권사의 경우 해당 조건으로 모든 계좌를 조회하면

문제가 없지만, ‘ALL’검색조건을 지원하지 않는 증권사의 경우 각 상품군별로 모든

계좌를 대상으로 조회해야 누락 없이 전 상품군을 조회할 수 있습니다.

https://apigw.koscom.co.kr/

https://sandbox-apigw.koscom.co.kr/

페이지 36 / 80

증권사단축명과 API제공 여부 (’16.08.30일 기준)

증권사명 단축명 코드 API제공여부

교보증권 KYOBO 00001 미제공(미정)

신한금융투자 SHINHAN 00002 제공

한국투자증권 KOREAINVEST 00003 제공(9월중)

대신증권 DAISHIN 00004 제공

대우증권 DAEWOO 00005 미제공(`17년)

신영증권 SHINYOUNG 00006 미제공(미정)

유진투자증권 EUGENE 00008 미제공(미정)

한양증권 HANYANG 00009 제공

메리츠종합금융증권 MERITZ 00010 제공

엔에이치투자증권 NHINVEST 00012 제공

부국증권 BOOKOOK 00013 제공

현대증권 HYUNDAI 00017 제공

한화투자증권 HANWHA 00021 미제공(미정)

에이치엠씨투자증권 HMC 00022 미제공(12월계획)

유화증권 YUWHA 00023 미제공(미정)

유안타증권 YUANTA 00024 제공

SK증권 SK 00025 미제공(9월중)

골든브릿지투자증권 GBRIDGE 00029 미제공(계획중)

삼성증권 SAMSUNG 00030 제공

동부증권 DONGBU 00031 미제공(9월중)

케이비투자증권 KB 00034 미제공(계획중)

미래에셋증권 MIRAEASSET 00049 미제공(`17년)

키움증권 KIWOOM 00050 제공

리딩투자증권 LEADING 00052 미제공(계획중)

하나금융투자 HANA 00056 미제공(12월중)

이베스트투자증권 EBEST 00063 미제공(9월중)

코리아에셋투자증권 KOREAASSET 00064 미제공(계획중)

비엔지증권 BNG 00065 미제공(계획중)

흥국증권 HEUNGKUK 00066 미제공(계획중)

IBK투자증권 IBK 00068 미제공(계획중)

바로투자증권 BAROFN 00069 미제공(계획중)

페이지 37 / 80

토러스투자증권 TAURUS 00070 미제공(계획중)

KTB투자증권 KTB 00071 미제공(계획중)

엘아이지투자증권 LIG 00072 미제공(계획중)

애플투자증권 APPLE 00073 미제공(계획중)

비엔케이투자증권 BNKFN 00086 미제공(계획중)

주) API제공 증권사와 일정, API제공 범위는 증권사의 사정에 따라 변경될 수 있음

페이지 38 / 80

자산 포트폴리오 조회 API

조회대상이 되는 계좌의 실제 잔고 수량, 투자금액 대신 금융투자 상품의 구성비만을 제공

함으로써 개인금융정보의 노출부담을 최소화하면서도 투자자산을 기초로 자산통합관리, 자

문, 정보제공 등을 받을 수 있도록 하기 위한 API

Syntax

URI

/account/portfolio/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication

header – Authorization: Bearer 발급받은 access token

header – apiKey: 발급받은 API Key(Client ID)

Request Body


partner - 핀테크 서비스 정보



commonHeader - 요청 메시지 제어 헤더

┗ reqIdPlatform String(20) 사용안함 플랫폼에서 사용하는 메시지 구분자

┗ reqIdConsumer String(20) 필수 핀테크 기업에서 사용하는 메시지 구분자


devInfo 단말정보

┗ ipAddr String(32) 필수 사용자 단말 IP주소

(dot없이 3자리를 12자리로 채워서 설정

하며, 모바일인 경우 휴대폰번호로 설정

하고 dash없이 10자리로 채워서 설정)

┗ macAddr String(50) 필수 사용자 MAC 주소

(PC의 경우 MAC을 : 없이 붙여 12자리

https://apigw.koscom.co.kr/v1/account/portfolio/search

페이지 39 / 80

로 표현하고, 모바일인 경우 UUID 설정)

accInfo -

┗ vtAccNo String(30) 필수 가상계좌번호

portfolioRequestBody

┗ queryType

┗ assetType String(8) 필수 요청하는 자산유형이며 값은: CASH(현

금), EQTY(주식), FUND(펀드), ETC(기타

자산), ALL(전체)인 경우는 page 처리없

이 대용량 데이터 전송이 가능한 증권사

만 가능

┗ rspType String(8) 필수 응답 유형이며 값은 RAT(잔고구성비율)은

기본으로 제공하며, 증권사에 따라

QTY(실제잔고수량)도 가능하나 본 API의

목적상 사용을 권장하지 않음

┗ count Number 필수 응답 별 최대 응답 건수이며 증권사는 반

드시 이 요청건수에 맞춰 전송할 필요는

없으나, 단일응답에 담기는 데이터는 이

건수를 초과하지 않음

0을 설정하면 증권사 전송 시스템이 판단

한 전송 가능한 적절한 건수로 요청함을

의미함

assetType이 ‘ALL’인 경우는 page없이

일괄전송이므로 본 필드는 의미 없으므로

0으로 설정

┗ page String(24) 필수 다음 page를 지시하는 키로 첫 요청은

“null”로 표기하고, 다음 페이지부터는

response에서 주는 page 값을 넣어 요

청

- queryType의 assetType을 ‘ALL’로 요청 가능한 증권사

NH투자증권, 대신증권, 키움증권, 신한증권

- 주) 보유비중 조회는 현재 일부 증권사의 경우 값이 부정확한 경우가 있고, 비중대신 수량을 제공하는

경우도 있으므로 주의 필요함. 보유비중은 수익기여도 (해당 자산군에서 해당종목이 차지하는 수익기여

도)로 산출한 경우가 대부분이며, 증권사별 산출 기준은 추후 게시예정

페이지 40 / 80

Response Body


commonHeader complex 요청 메시지 제어 헤더


┗ reqIdConsumer String(20) 반환 핀테크 기업에서 사용하는 메시지 구분자

┗ certDn String(256) 사용안함 ""

┗ ci String[88] 반환 연계정보 88byte

accInfo

┗ realAccNo String(40) 사용안함 ""

┗ vtAccNo String(30) 반환 가상계좌번호

portfolioResponseBody Complex

┗ queryType 요청 시 설정했던 값이 그대로 전송

┗ assetType String(8) 반환

┗ rspType String(8) 반환

┗ count Number 반환

┗ page String(24) 반환

┗ queryResult 응답 결과

┗ totalCnt Number 설정 조회 조건의 총 메시지 건수

┗ count Number 설정 현 메시지 내 응답 건수

┗ page String(24) 설정 다음 page 번호, “null”이면 더 이상 없음

portfolioList complex

portfolio

┗ cash CASH

┗ amt Number 설정 전체 자산 중 현금잔고 또는 비중

┗ equityList array EQTY

┗assetType String(8) 설정 상품구분자로 값은: KSP(코스피), KDQ(코스

닥), ETF(ETF), FUT(선물), OPT(옵션),

ELW(ELW), ETC(기타)

┗isinCode String(20) 설정 ISINCODE(12)

┗qty Number 설정 수량 또는 비중(equity 내 비중, 소수점 2

째자리까지)

신용 매수 분 포함하고 대출잔고는 반영안

함

┗earningRate Number 설정 수익률 (소수점 2째자리까지)

┗ fundList Array FUND

┗fundCode String(20) 설정 펀드표준코드

┗fundName String(15) 설정 펀드명 (최대 15자)

┗qty Number 설정 수량 또는 비중(fund 내 비중, 소수점 2째

자리까지)


┗maturity String(12) 설정 만기일 (YYYYMMDD)

┗ etcList Array ETC

페이지 41 / 80

┗assetType String(8) 설정 상품구분자로 값은: BOND(채권), CD, CP,

DLS, ELS, STB(사채), RP(미구분), CRP(약정

식RP), RRP(수시RP), WRT(워런트)

┗assetName String(15) 설정 상품명

┗isinCode String(12) 설정 현재는 지원 안 함 (1.0부터 지원예정)

┗qty Number 설정 수량 또는 비중(etc 내 비중, 소수점 2째자

리까지)

신용 매수 분 포함하고 대출잔고는 반영안

함


resp

┗ respCode String(8) 설정 응답코드 참고

┗ respMsg String(50) 설정 응답메시지 참고

Example


{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"ID000001", "ci":"S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "devInfo":{ "ipAddr":"123451234500", "macAddr":"7054D27EE247" }, "accInfo":{ "vtAccNo":"160678007213500001" }, "portfolioRequestBody":{ "queryType":{ "assetType":"ALL", "rspType":"RAT", "count":0, "page":"null" } } }

페이지 42 / 80


{ "commonHeader":{ "reqIdPlatform":"fs27abe2231", "reqIdConsumer":"ID000001", "certDn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "accInfo":{ "realAccNo":"",

"vtAccNo":"160678007213500001" }, "portfolioResponseBody":{

"queryType":{ "assetType":"ALL", "rspType":"RAT", "count":"0", "page":"null" }, "queryResult":{ "totalCnt":157.0, "count":157.0, "page":"null" } },

"resp":{ "respCode":"200", "respMsg":"OK" }, "portfolioList":{ "portfolio":{ "cash":{ "amt":6976542.0 }, "equityList":[ { "assetType":"KSP", "isinCode":"HK0000050325", "qty":0.0, "earningRate":-12.9 }, { "assetType":"KDQ", "isinCode":"HK0000054723", "qty":0.0, "earningRate":-19.72 }, { "assetType":"KSP", "isinCode":"KR7000020008", "qty":0.0, "earningRate":10.95

페이지 43 / 80

}, { "assetType":"KSP", "isinCode":"KR7000270009", "qty":1.0, "earningRate":-3.97 }, { "assetType":"KSP", "isinCode":"KR7000400002", "qty":0.0, "earningRate":-2.68 } ], "fundList":[ { "fundCode":"KRZ500395135",

"fundName":"삼성중소형FOCUS증권자1호[주식]",

"qty":46.0, "earningRate":-9.58, "maturity":"00000000" }, { "fundCode":"KRZ500395136",

"fundName":"삼성중소형FOCUS증권자1호[주식]",

"qty":5.0, "earningRate":-12.52, "maturity":"00000000" }, { "fundCode":"KRZ501130561",

"fundName":"미래에셋고배당포커스증권자1호(",

"qty":5.0, "earningRate":-6.32, "maturity":"00000000" } ], "etcList":[ { "assetType":"BOND",

"assetName":"국민주택1종11-07",

"qty":2.0, "earningRate":22.73 }, { "assetType":"BOND",

"assetName":"국고03000-2409(14-5)",

"qty":2.0, "earningRate":7.68 }, { "assetType":"BOND",

"assetName":"물가01500-2106(11-4)",

"qty":3.0, "earningRate":4.39

페이지 44 / 80

}, { "assetType":"BOND",

"assetName":"광주지방채11",

"qty":2.0, "earningRate":4.53 }, { "assetType":"DLS",

"assetName":"우리투자증권(DLS)1120",

"qty":14.0, "earningRate":2.61 }, { "assetType":"ELS",

"assetName":"NH투자증권(ELB)759",

"qty":5.0, "earningRate":2.5 }, { "assetType":"CP",

"assetName":"루카스 20131227-89-2",


"assetName":"루카스 20131227-89-6",

"qty":0.0, "earningRate":0.86 },

{ "assetType":"CP",

"assetName":"루카스 20131227-89-14",


"assetName":"루카스 20131227-89-15",

"qty":0.0, "earningRate":0.86 } ]

} }

}

페이지 45 / 80

계좌잔고 조회 API

조회대상이 되는 계좌의 실제 잔고 수량, 손익, 수익률 등을 상세히 조회하기 위한 API

Syntax

URI

/account/balance/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body


partner complex - 핀테크 서비스 정보



commonHeader complex - 요청 메시지 제어 헤더


┗ reqIdConsumer String(20) 필수 핀테크 기업에서 사용하는 메시지 구분자


devInfo


(dot없이 3자리를 12자리로 채워서 설정

하며, 모바일인 경우 휴대폰번호로 설정

하고 dash없이 10자리로 채워서 설정)


(PC의 경우 MAC을 : 없이 붙여 12자리

로 표현하고, 모바일인 경우 UUID 설정)


페이지 46 / 80

accInfo - 요청 메시지 본문


balanceRequestBody

┗ queryType

┗ assetType String(8) 필수 요청하는 자산유형이며 값은: CASH(현

금), EQTY(주식), FUND(펀드), ETC(기타

자산), ALL(전체)인 경우는 page 처리없

이 대용량 데이터 전송이 가능한 증권사

만 가능

┗ count Number 필수 응답 별 최대 응답 건수이며 증권사는 반

드시 이 요청건수에 맞춰 전송할 필요는

없으나, 단일응답에 담기는 데이터는 이

건수를 초과하지 않음

0을 설정하면 증권사 전송 시스템이 판단

한 전송 가능한 적절한 건수로 요청함을

의미함

assetType이 ‘ALL’인 경우는 page없이

일괄전송이므로 본 필드는 의미 없음

┗ page String(24) 필수 다음 page를 지시하는 키로 첫 요청은

null(“null”)로 표기하고, 다음 페이지부터

는 response에서 주는 page 값을 넣어

요청하며, ALL인 경우는 page없이 일괄

전송이므로 본 필드는 의미 없음

- queryType의 assetType을 ‘ALL’로 요청 가능한 증권사

NH투자증권, 대신증권, 키움증권, 신한증권

Response Body

Property type Requried? Description

commonHeader 요청 메시지 제어 헤더

┗ reqIdPlatform String(20) 반환 플랫폼에서 사용하는 메시지 구분자

┗ reqIdConsumer String(20) 반환 핀테크 기업에서 사용하는 메시지 구분자



accInfo - 요청 메시지 본문



balanceResponseBody

┗ queryType

┗ assetType String(8) 반환 요청하는 자산유형이며 값은: SUM(현금),

페이지 47 / 80

EQTY(주식), FUND(펀드), ETC(기타자산),

ALL(전체)

┗ rspType String(8) 반환 -

┗ count Int 반환


┗ queryResult

┗ totalCnt Number 설정 총 메시지 건수

┗ count Number 설정 메시지 내 응답 건수

┗ page String(24) 설정 다음 page 번호, null이면 더 이상 없음

balanceList Complex 잔고 종합

┗ balance

┗ summary Complex 잔고 요약 (SUM)

┗ cashBalance Number 설정 현금잔고

┗ d1 Number 설정 D+1잔고

┗ d2 Number 설정 D+2잔고

┗ substitute Number 설정 대용금

┗ receivable Number 설정 미수/미납금

┗ subsMargin Number 설정 대용증거금

┗ loanCredit Number 설정 대출/신용금

┗ valAtTrade Number 설정 유가증권매수금액

┗ valueAtCur Number 설정 유가증권평가금액

┗ proLoss Number 설정 유가증권평가손익

┗ totalAccVal Number 설정 총평가금액

┗ cashAvWithdraw Number 설정 출금가능액

┗ equityList Complex

array

(EQTY)

┗ assetType String(8) 설정 상품구분자로 값은: KSP(코스피), KDQ(코스

닥), ETF(ETF), FUT(선물), OPT(옵션),

ELW(ELW), ETC(기타)

┗isinCode String(20) 설정 ISINCODE(12)

┗qty Number 설정 잔고수량

┗tradeType String(8) 설정 잔고구분: NRM(일반/현금), CRD(신용),

LOAN(대출), SUM(분류가 불가한 경우 구

분 없이 합산한 경우며 대출잔고는 제외)

┗valAtTrade Number 설정 매수금액

┗valAtCur Number 설정 평가금액

┗proLoss Number 설정 평가손익


┗ fundList Complex

array

(FUND)

┗fundCode String(20) 설정 펀드표준코드

┗fundName Number 설정 펀드이름


페이지 48 / 80

┗valAtCur Number 설정 평가금액

┗proLoss Number 설정 평가손익

┗firstDateBuy String(12) 설정 최초매수일(YYYYMMDD)

┗lastDateBuy String(12) 설정 최종매수일(YYYYMMDD)

┗maturity String(12) 설정 만기일(YYYYMMDD)


┗ etcList Complex

array

(ETC)

┗assetType String(8) 설정 상품구분자로 값은: BOND(채권), CD, CP,

DLS, ELS, STB(사채), RP(미분류), CRP(약정

식RP), RRP(수시RP), WRT(워런트)

┗assetName String(20) 설정 상품명

┗isinCode String(12) 설정 현재는 지원 안 함 (1.0부터 지원예정)

┗qty Number 설정 수량 또는 비중(etc 내 비중, 소수점 2째자

리까지)

┗tradeType String(8) 설정 잔고구분: NRM(일반/현금), CRD(신용),

LOAN(대출), SUM(분류가 불가한 경우 구

분 없이 합산한 경우며 대출잔고는 제외)


┗valueAtCur Number 설정 평가금액


resp



Example


{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"ID00002", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "devInfo":{ "ipAddr":"123451234500", "macAddr":"7054D27EE247" },

페이지 49 / 80

"accInfo":{ "vtAccNo":"160678007213500001" }, "balanceRequestBody":{ "queryType":{ "assetType":"ALL", "count":0, "page":"null" } } }

페이지 50 / 80


{ "commonHeader":{ "reqIdPlatform":"fagbbs22321", "reqIdConsumer":" ID00002", "certDn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "accInfo":{

"realAccNo":"", "vtAccNo":"160678007213500001" }, "balanceResponseBody":{ "queryType":{ "assetType":"ALL", "count":"0", "page":"null" }, "queryResult":{ "totalCnt":157.0, "count":157.0, "page":"null" } }, "balanceList":{ "balance":{ "summary":{ "cashBalance":6976542.0, "d1":6976542.0, "d2":6976542.0, "substitute":9.816358E7, "receivable":0.0, "subsMargin":762635.0, "loanCredit":0.0, "valAtTrade":3.69827563509E11, "valueAtCur":3.89165300498E11, "proLoss":1.9337736989E10, "totalAccVal":3.8917227704E11, "cashAvWithdraw":6976542.0 }, "equityList":[ { "assetType":"KSP", "isinCode":"HK0000050325", "qty":120.0, "tradeType":"SUM", "valAtTrade":281764.0, "valAtCur":245400.0, "proLoss":-36364.0, "earningRate":-12.9 }, { "assetType":"KDQ",

페이지 51 / 80

"isinCode":"HK0000054723", "qty":1186.0, "tradeType":"SUM", "valAtTrade":2326871.0, "valAtCur":1867950.0, "proLoss":-458921.0, "earningRate":-19.72 }, { "assetType":"KSP", "isinCode":"KR7000020008", "qty":19.0, "tradeType":"SUM", "valAtTrade":181519.0, "valAtCur":201400.0, "proLoss":19881.0, "earningRate":10.95 }, { "assetType":"KDQ", "isinCode":"USU652221081", "qty":71.0, "tradeType":"SUM", "valAtTrade":514957.0, "valAtCur":501970.0, "proLoss":-12987.0, "earningRate":-2.52 } ], "fundList":[ { "fundCode":"KRZ500395135",

"fundName":"삼성중소형 FOCUS증권자 1호[주식]", "valAtTrade":0.0, "valAtCur":7.2329965E7, "proLoss":7.2329965E7, "firstDateBuy":"20160112", "lastDateBuy":"20160113", "maturity":"00000000", "earningRate":-9.58 }, { "fundCode":"KRZ500395136",

"fundName":"삼성중소형 FOCUS증권자 1호[주식]", "valAtTrade":0.0, "valAtCur":8747937.0, "proLoss":8747937.0, "firstDateBuy":"20150820", "lastDateBuy":"20150910", "maturity":"00000000", "earningRate":-12.52 }, { "fundCode":"KRZ501831185",

"fundName":"메리츠코리아증권투자신탁 1호[주", "valAtTrade":0.0, "valAtCur":8416030.0,

페이지 52 / 80

"proLoss":8416030.0, "firstDateBuy":"20150818", "lastDateBuy":"20150819", "maturity":"00000000", "earningRate":-15.83 } ], "etcList":[ { "assetType":"BOND",

"assetName":"국민주택 1종 11-07", "qty":1.0E10, "tradeType":"SUM", "valAtTrade":9.438E9, "valueAtCur":1.1584E10, "earningRate":22.73 }, { "assetType":"BOND",

"assetName":"한국지역난방공사 13-1", "qty":1.0E10, "tradeType":"SUM", "valAtTrade":9.992E9, "valueAtCur":1.0168E10, "earningRate":1.76 }, { "assetType":"BOND",

"assetName":"주택금융공사 MBS2016-10(1-4)", "qty":1.0E10, "tradeType":"SUM", "valAtTrade":1.0E10, "valueAtCur":1.0145E10, "earningRate":1.45 }, { "assetType":"BOND",

"assetName":"주택금융공사 MBS2016-7(1-5)", "qty":2.0E10, "tradeType":"SUM", "valAtTrade":2.0E10, "valueAtCur":2.0616E10, "earningRate":3.08 }, { "assetType":"BOND",

"assetName":"강원도개발공사 121", "qty":1.0E10, "tradeType":"SUM", "valAtTrade":1.0E10, "valueAtCur":1.0024E10, "earningRate":0.24 }, { "assetType":"DLS",

"assetName":"우리투자증권(DLS)1120",

페이지 53 / 80

"qty":5.4E10, "tradeType":"SUM", "valAtTrade":5.4E10, "valueAtCur":5.54094E10, "earningRate":2.61 }, { "assetType":"ELS",

"assetName":"NH투자증권(ELB)759", "qty":2.0E10, "tradeType":"SUM", "valAtTrade":2.0E10, "valueAtCur":2.05E10, "earningRate":2.5 }, { "assetType":"CP",

"assetName":"루카스 20131227-89-2", "qty":1.0E9, "tradeType":"SUM", "valAtTrade":9.91452055E8, "valueAtCur":1.0E9, "earningRate":0.86 }, { "assetType":"CP",




"assetName":"루카스 20131227-89-14", "qty":1.0E9, "tradeType":"SUM",

페이지 54 / 80

"valAtTrade":9.91452055E8, "valueAtCur":1.0E9, "earningRate":0.86 }, { "assetType":"CP",

"assetName":"루카스 20131227-89-15", "qty":1.0E9, "tradeType":"SUM", "valAtTrade":9.91452055E8, "valueAtCur":1.0E9, "earningRate":0.86 } ] } }, "resp":{ "respCode":"200", "respMsg":"OK" } }

페이지 55 / 80

거래내역 조회 API

조회대상이 되는 계좌의 입금, 출금, 매수, 매도 이력을 조회할 수 있는 API

Syntax

URI

/account/transaction/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body


partner complex 핀테크 서비스 정보



commonHeader Complex 요청 메시지 제어 헤더

┗ reqIdPlatform String(20) 사용안함 플랫폼에서 사용하는 메시지 구분

자

┗ reqIdConsumer String(20) 필수 핀테크 기업에서 사용하는 메시지

구분자


devInfo Complex


(dot없이 3자리를 12자리로 채워

서 설정하며, 모바일인 경우 휴대

폰번호로 설정하고 dash없이 10자

리로 채워서 설정)


(PC의 경우 MAC을 : 없이 붙여

12자리로 표현하고, 모바일인 경우

https://apigw.koscom.co.kr/v1/account/transaction/search

페이지 56 / 80

UUID 설정)

accInfo Complex


transactionHistoryRequestBody

┗ queryPrams 조회범위는 증권사마다 상이

┗ fromDate String(12) 필수 조회시작날짜(YYYYMMDD)

┗ toDate String(12) 필수 조회종료날짜(YYYYMMDD)

┗ isinCode String(20) 필수 조회조건: 종목코드, 종목코드지정

없으면 전체종목을 대상

┗ side String(8) 필수 조회조건으로 값은: BID(매도),

ASK(매수), DEP(이체입금), WID(이

체출금), 조회조건이 없거나 ‘ALL’

이면 전체구분자가 대상

┗ count Number 필수 응답 별 최대 응답 건수이며 증권

사는 반드시 이 요청건수에 맞춰

전송할 필요는 없으나, 단일응답에

담기는 데이터는 이 건수를 초과하

지 않음

0을 설정하면 증권사 전송 시스템

이 판단한 전송 가능한 적절한 건

수로 요청함을 의미함

assetType이 ‘ALL’인 경우는 page

없이 일괄전송이므로 본 필드는 의

미 없음

┗ page String(24) 필수 다음 page를 지시하는 키로 첫 요

청은 null로 표기하고, 다음 페이지

부터는 response에서 주는 page

값을 넣어 요청

Response Body



┗ reqIdPlatform String(20) 사용안함 플랫폼에서 사용하는 메시지 구

분자

┗ reqIdConsumer String(20) 반환 핀테크 기업에서 사용하는 메시

지 구분자



accInfo



페이지 57 / 80

transactionHistoryResponseBody

┗accInfo



┗ queryResult



┗ page String(24) 설정 다음 page 번호, “null” 이면 더

이상 없음

┗ queryPrams

┗ fromDate String(12) 반환 조회시작날짜(YYYYMMDD)

┗ toDate String(12) 반환 조회종료날짜(YYYYMMDD)

┗ isinCode String(12) 반환 조회조건: 종목코드

┗ side String[8] 반환 조회조건으로 값은: BID(매도),

ASK(매수)

┗ count Number 반환 응답 별 건수 (default는 50)

0이면 50건과 동일

┗ page String(24) 반환 응답데이터의 특정 지점을 지정

할 경우 (요청 시 값)

transList 거래내역 리스트

┗transaction Array 거래

┗ isinCode String(20) 설정 종목코드 (입출금은 CASH로

표기)

┗ transDate String(12) 설정 거래일자 (YYYYMMDD)

┗ transType String[8] 설정 거래구분이며 값은: BID(매도),

ASK(매수),

DEP(이체입금), WID(이체출금)

┗ changeAmt Number 설정 금액증감 (매도/매수/이체에 따

른 금액변동)

┗ changeQty Number 설정 수량증감 (매도/매수량, 이체 시

는 0)

┗ qty Number 설정 잔고수량 (거래 후 잔량)

resp



페이지 58 / 80

Example


{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"ID00003", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "devInfo":{ "ipAddr":"123456789012", "macAddr":"7054D27EE247" }, "accInfo":{ "realAccNo":null, "vtAccNo":"160731060768600001" }, "transactionHistoryRequestBody":{ "queryParams":{ "fromDate":"20160101", "toDate":"20160720", "isinCode":"", "side":"", "count":30, "page":"" } } }

페이지 59 / 80


{ "commonHeader":{ "reqIdPlatform":"2ddacehgg", "reqIdConsumer":"ID00003", "certDn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "accInfo":{ "realAccNo":"", "vtAccNo":"160731060768600001" }, "transactionHistoryResponseBody":{ "queryParams":{ "fromDate":"20160101", "toDate":"20160720", "isinCode":"", "side":"", "count":30, "page":"" }, "queryResult":{ "count":30, "page":"201603100000000961", "totalCnt":120 } }, "transList":{ "transaction":[ { "transDate":"20160126", "transType":"DEP", "isinCode":"", "changeAmt":14399400, "changeQty":0, "qty":0 }, { "transDate":"20160126", "transType":"ASK", "isinCode":"NC30010", "changeAmt":-14399400, "changeQty":0, "qty":0 }, { "transDate":"20160202", "transType":"DEP", "isinCode":"", "changeAmt":100, "changeQty":0, "qty":0 },

페이지 60 / 80

{ "transDate":"20160202", "transType":"ETC", "isinCode":"", "changeAmt":-100, "changeQty":0, "qty":0 }, { "transDate":"20160310", "transType":"BID", "isinCode":"NC30010", "changeAmt":180456840, "changeQty":0, "qty":0 }, { "transDate":"20160310", "transType":"WID", "isinCode":"", "changeAmt":-10000, "changeQty":0, "qty":0 }, { "transDate":"20160310", "transType":"WID", "isinCode":"", "changeAmt":-10500, "changeQty":0, "qty":0 } ] }, "resp":{ "respCode":"200", "respMsg":"OK" } }

페이지 61 / 80

관심종목 조회 API

조회대상이 되는 계좌에 설정된 관심종목을 조회할 수 있는 API

Syntax

URI

/account/interest/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body


partner complex - 핀테크 서비스 정보



commonHeader Complex - 요청 메시지 제어 헤더

┗ reqIdPlatform String(20) 사용안함 플랫폼에서 사용하는 메시지 구분

자

┗ reqIdConsumer String(20) 필수 핀테크 기업에서 사용하는 메시지

구분자


devInfo


(dot없이 3자리를 12자리로 채워

서 설정하며, 모바일인 경우 휴대

폰번호로 설정하고 dash없이 10자

리로 채워서 설정)


https://apigw.koscom.co.kr/v1/account/interest/search

페이지 62 / 80

(PC의 경우 MAC을 : 없이 붙여

12자리로 표현하고, 모바일인 경우

UUID 설정)

accInfo


InterestSymbolListRequestBody

┗ queryType queryType 지원증권사 : 삼성증권

┗ assetType String(8) 필수 EQY(유가증권/코스닥)

┗ rspType String(8) 필수 "" (값없음)

┗ count Int 필수 응답 별 최대 응답 건수이며 증권

사는 반드시 이 요청건수에 맞춰

전송할 필요는 없으나, 단일응답에

담기는 데이터는 이 건수를 초과하

지 않음

0을 설정하면 증권사 전송 시스템

이 판단한 전송 가능한 적절한 건

수로 요청함을 의미함

┗ page String(24) 필수 다음 page를 지시하는 키로 첫 요

청은 “null”로 표기하고, 다음 페이

지부터는 response에서 주는

page 값을 넣어 요청

주) queryType은 삼성증권만 지원되며, 타 증권사는 사용하지 못함

Response Body



┗ reqIdPlatform String(20) 사용안함 플랫폼에서 사용하는 메시지 구

분자

┗ reqIdConsumer String(20) 반환 핀테크 기업에서 사용하는 메시

지 구분자



accInfo



interestSymbolListResponseBody

┗ queryType queryType 지원증권사: 삼성증권

┗ assetType String(8) 반환

┗ rspType String(8) 반환

┗ count Int 반환

페이지 63 / 80


┗ queryResult queryType 지원증권사: 삼성증권



┗ page String(24) 설정 다음 page 번호, null이면 더 이

상 없음

┗ groupList 관심종목그룹

┗group Array

┗groupName String(20) 설정 관심종목 그룹 이름

┗modifyDate String(12) 선택 최종 수정일

┗isinCode String

Array

(각 20)

설정 종목코드

resp



Example


{ "partner":{ "comId":"F9999", "srvId":"999" }, "commonHeader":{ "reqIdPlatform":"", "reqIdConsumer":"ID0000020", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "devInfo":{ "ipAddr":"123456789012", "macAddr":"7054D27EE247" }, "accInfo":{ "vtAccNo":"160731060768600001" }, "interestSymbolListRequestBody":{ "queryType":{ "assetType":"", "rspType":null, "count":0, "page":"", "totalCnt":0 } } }

페이지 64 / 80


{ "commonHeader":{ "reqIdPlatform":"fs901jjshgs", "reqIdConsumer":"ID0000020", "certDn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/k0XB/9jQ==" }, "accInfo":{ "realAccNo":"", "vtAccNo":"160731060768600001" }, "interestSymbolListResponseBody":{ "groupList":{ "group":[ { "isinCode":[ "KR7122870009", "KR7028260008", "KR7001360007", "KR7011070000", "KR7017800004" ],

"groupName":"관심종목00",

"modifyDate":"" }, { "isinCode":[ "KR7176950004", "KR7143860005", "KR7138230008", "KR7205720006" ], "groupName":"ETF", "modifyDate":"" } ] } }, "resp":{ "respCode":"200", "respMsg":"OK" } }

페이지 65 / 80

Error 처리

Error는 증권회사, 오픈플랫폼의 시스템 등 여러 위치에서 발생할 수 있으나 HTTP

Response Status Code와 Response Body를 통해 오픈플랫폼 표준 error code와 message로

전달합니다.

Error message format

HTTP Response

Status Code

4xx ~ 5xx

HTTP Response

Content-Type

Application/json; charset=utf-8

HTTP Response

Body

{

"category": "op-exco", // 오류 발생 지점.

"code": 9011, // 상세 오류 코드

"message": "invalid virtual account number.", // 상세 오류 메세지

"description": "blah blah~" // 추가 정보

}

Error category

Category 시스템

op-apim 오픈플랫폼 API Gateway Server

op-auth 오픈플랫폼 인증 서버

op-exco 오픈플랫폼 증권사 연계 서버

{증권사명} Ex) saumgsung, Hyundai

Field Data Type

Field Data type

category String

code Integer

message String

description(*optional) string

페이지 66 / 80

Error Code/Message

Common Error

오픈플랫폼에서 발생하는 공통오류는 HTTP표준 상태 코드와 오류코드를 동일하게

준용

HTTP

Response

Status

Code

Error

Code Error Message Description

400 400 Bad Request

요청 자원에 대한 Parameter, URI

Variable, Payload, Content Media-

Type 이 서버가 요구하는 명세와 다르거나

받아들일 수 없는 경우.

401 401 Unauthorized 클라이언트의 인증 요청이 실패한 경우.

(e.g. API Key, OAuth…)

403 403 Forbidden API 이용 권한 획득에 실패한 경우.

404 404 Not Found API 가 존재하지 않는 경우.

405 405 Method Not Allowed API 가 허용하지 않는 HTTP Method

요청의 경우.

406 406 Not Acceptable API 가 허용하지 않는 Accept Media-

Type 요청의 경우.

408 408 Request Timeout 요청 API 의 수행 시간이 기준 시간보다

초과된 경우.

415 415 Unsupported Media

Type

API 가 허용하지 않는 Content-Type

요청의 경우.

500 500 Internal Server Error

플랫폼 내부에서 발생하는 저 수준 오류의

경우.

(* low-level error 는 비즈니스 오류가

아닌, 코드상의 오류를 말함)

503 503 Service Unavailable 서버가 일시적인 오류이거나 정상적인

서비스가 불가능한 경우.

505 505 HTTP Version Not

Supported

지원되지 않는 HTTP 버전으로 요청한

경우.

페이지 67 / 80

Custom Error - 오픈플랫폼 인증서버

HTTP

Response

Status

Code

Error


401

2001 Authentication Failed 핀테크 서비스 포탈 사용자의 인증에 실패

한 경우.

2002 Invalid OTP Key OTP Secret Key가 유효하지 않거나 만료된

경우.

2003 Account Locked 인증 시도 제한 횟수를 초과하여 계정이

임시 잠김.

403 2100 Authorization Failed API 및 서비스 이용 권한 획득에 실패한

경우.

Custom Error – 오픈플랫폼 증권사 연계 서버

HTTP

Response

Status

Code

Error


500 3001 Bad response trcode 금투사로부터 잘못된 TRCODE가 옴

400 3002 Unknown api url 요청한 금투사 api 연결정보를 찾을 수 없

는 경우

400 3003 필수 항목 누락 필수 항목이 누락된 경우

500 3004 network error 일시적 network 장애가 발생한 경우

500 3005 network timeout 금투사 서버로부터 메시지 응답이 지연된

경우

500 3006 not found dn 요청한 ci로 사용자 dn값을 찾을 수 없을

경우

500 3007 not found user 요청한 CI로 사용자를 찾을 수 없을 경우

페이지 68 / 80

500 3008 not found company info 요청한 금투사의 정보를 찾을 수 없을 경

우

500 3009 not found account info 실계좌번호를 찾을 수 없을 경우

500 3010 expired account 요청계좌가 폐기된 계좌일 경우

500 3011 Json parsing error Json 메시지 규격에 오류가 있을 경우

500 3012 Unknown account

number 요청계좌가 증권사에 존재하지 않을 경우

500 3013 Unknown account type 등록되지 않은 계좌 유형의 경우

500 3999 Unknown error 프로그램 내부 에러(ex : DB에러) 가 발생

했을 경우

503 3600 Target Company Service

Unavailable

금투사 서버가 정상적인 서비스가 불가능

한 경우.

Custom Error – 증권사 서버

HTTP

Response

Status

Code

Error


500

200 OK 정상

4000 Mismatch between

DN and AccoutNo DN 과 계좌번호가 서로 불일치

4001 Account Not Found 해당계좌를 찾을 수 없음

4002 DN Not Found DN 값을 찾을 수 없음

4003 Mismatch between CI

and AccountNo CI 와 계좌번호가 서로 불일치

4004 CI Not Found CI 값을 찾을 수 없음

4005 Mismatch between

DN and CI DN 과 CI 가 서로 불일치

페이지 69 / 80

5004

Failure To Enrol an

vtAccNo, {상세한 사유

를 대괄호안에 명시}

플랫폼에서 발급한 가상계좌번호 등록 실패 (요

청방향: 플랫폼->증권사)

5005

Failure To Change an



발급된 가상계좌번호 또는 가상계좌별칭 변경

실패 (요청방향: 플랫폼->증권사)

5006

Failure To Issue an



증권사로 요청한 가상계좌발급이 실패 (요청방

향: 플랫폼->증권사)

5007

Failure To discard an



가상계좌 폐기요청이 실패 (요청방향: 증권사->

플랫폼, 플랫폼->증권사)

6001 Invalid Asset Type 지원하지 않는 상품구분자

6002 Invalid Rsp Type 지원하지 않는 응답유형 (QTY, RAT 이 아닌 값

이 요청에 포함된 경우)

6003 Invalid Page Value 존재하지 않는 Page Key 값 요청 (연속조회시

존재하지 않는 Key 값)

6004

Invalid Query Type, {상

세한 사유를 대괄호안에

명시}

6005

Result Too Many, {요청

한 조회에 대한 결과건

수}

증권사에서 제공 가능한 총 건수 (연속조회를

포함)를 초과한 경우

6006

Date Range Exceeded,

{최대 조회 가능 날짜

수 명시}

조회 가능한 날짜 범위 초과

6007 Invalid Isincode 존재하지 않는 isincode 로 조회요청

6008 Invalid Side Type 잘못된 거래구분 조회조건, BID, ASK, DEP,

WID, ALL 이 아닌 값으로 조회

7000

Bad Request, {상세한

사유를 대괄호안에 명

시}

요청에서 무엇이 문제인지 사유 명시 필요

페이지 70 / 80

참고1. 금융투자 핀테크 포탈 이용 절차

① 포탈초기화면

② 본인인증절차

본인인증은 휴대폰인증과 아이핀인증의 두 가지 타입을 제공

페이지 71 / 80

③ 공인인증서 등록

금융거래정보 제3자 제공 동의 및 개인식별 보조수단으로 인증서를 사용하기 때문에

인증서 등록 절차 필요. 공인인증서를 통해 증권사의 고객을 식별하기 때문에 증권사

마다 서로 다른 공인인증서를 사용하는 경우 포탈에 등록된 공인인증서와 다른 공인

인증서를 사용하는 증권사는 사용에 제약을 받음

페이지 72 / 80

④ 금융투자 핀테크 포털 이용약관 동의

⑤ 회원기본정보 등록

보안강화를 위해 OTP(오픈플랫폼 전용 모바일OTP)를 사용하는 경우 OTP등록

필요 (OAuth 인증용으로만 사용됨)

페이지 73 / 80

⑥ 이메일주소 확인

⑦ 이용 증권사 선택

페이지 74 / 80

⑧ 가상계좌발급

증권사에 따라 본인명의의 계좌리스트를 제공하는 곳이 있고, 지원하지 않는

증권사는 직접 실계좌번호와 계좌별칭을 입력하는 창으로 제공

페이지 75 / 80

⑨ 핀테크 서비스 선택

발급된 가상계좌번호를 기준으로 해당증권사를 지원하는 핀테크 서비스 목록이

리스팅되며, 핀테크 서비스를 선택 후 하단의 가상계좌번호를 선택하면 핀테크

서비스가 API를 통해 계좌를 조회할 수 있는 권한정보가 오픈플랫폼에 설정됨

페이지 76 / 80

⑩ 금융거래정보 제3자 제공 동의

핀테크 서비스에 가상계좌를 연결하고 나면 금융거래정보 제3자 동의를 위한 ‘정보

제공동의’버튼이 활성화 되며, 버튼을 누르면 동의서가 팝업되며 전자서명을 할 수

있음

페이지 77 / 80

⑪ 핀테크 서비스 연결 완료

페이지 78 / 80

발급된 가상계좌 조회

이용 신청된 핀테크 서비스 조회

페이지 79 / 80

REST API Developer Guide - developers.koscom.co.kr · 페이지 5 / 80 계좌기반 조회 자산...

Documents

Transcript of REST API Developer Guide - developers.koscom.co.kr · 페이지 5 / 80 계좌기반 조회 자산...