본시장 공동 ଘ테크 오랫૬ · 오랫૬에 등록 된 ଘ테크 기업의 경ࡋ ࡊ에게 서비스를 제공ଡ 수 있습니다. 단, 주문 및 매매 관련 api는

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

REST API Developer Guide

Version 1.05, 2017-08-22

페이지 0 / 133

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

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

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

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

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

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

Copyright © 2016 KOSCOM, All right reserved.

오픈플랫폼 운영 담당자

코스콤

박재성 팀장 (02)767-7831

[email protected]

이상목 차석 (02)767-7940

[email protected]

mailto:[email protected]


페이지 1 / 133

개정내역

버전 개정일 개정내역 비고

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

- (DN, 실계좌번호 등)

- 관련 Json sample 수정

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

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

증권사 제공 API 중 accInfo 블럭

위치변경(빨간색으로 표시)

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

apikey 삽입 정책 삭제 (15p)

1.0 17.05.30 API 제공유형 추가 (3p)

오픈플랫폼 이용 방법 추가 (7p)

Basic Authentication 인증 추가 (9p)

일임매매 연계 전문 추가 (78p)

1.01 17.06.26 Complex -> Object

Complex Array -> Array

문자변경

1.02. 17.07.11 주문체결조회 전문의 “qrAccNo”선택 ->

필수 (76P)

Required 변경

1.03 17.08.01 ‘금융투자 핀테크 포털’ 수정

‘오핀’ 모바일 앱 추가

1.04 17.08.17 일임매매 page 항목 String 변경(24=>100) p80 ~ 106

1.05 17.08.22 일임 계좌잔고 조회 balance 항목 제거 p88

일임매매 결제예정정산조회 url 변경

/b2baccount/settlement/search=>

/b2baccount/settlelist/search

p94

페이지 2 / 133

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

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

금융투자회사, 유관기관, 기타 정보제공벤더가 제공하는 데이터 및 서비스를 표준화된

프로토콜, 단일 인증방식, 표준 메시지 스펙으로 핀테크 기업과 기타 3rd 파트너에게

API를 제공하는 중계 플랫폼 입니다.

페이지 3 / 133

Chapter 2. 오픈플랫폼 제공 API

제공 API 유형

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

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

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

하기 때문에 추가적인 권한확인 절차가 요구됩니다.

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

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

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

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

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

확인과정이 개입됩니다.

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

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

단, 주문 및 일임매매 관련 API는 투자일임업 라이선스를 보유한 법인만 사용 가능

합니다.

페이지 4 / 133

API

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

제공주체

(속성)

공통

서비스

오픈플랫폼

가입여부 확인

오픈플랫폼

->

핀테크

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

폼 회원인지 확인하기 위한 API

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

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

오픈플랫폼

(일반정보)

가상계좌

목록 조회

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

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

제공

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

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

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

계좌

서비스

자산

포트폴리오 조회

금투사

->

오픈플랫폼

->

핀테크

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

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

로 제공

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

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

부담 없이 제공할 수 있게 함으로

써 투자성향분석 등 자문의 기초

자료로 활용 가능

금투사

(민감도

낮은

금융정보)

관심종목

조회

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

리스트를 조회할 수 있는 기능

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

대해 뉴스, 분석정보, 이벤트(급등락, 공

시 등)의 정보를 능동적으로 제공할 수

있는 기초자료로 활용 가능

계좌잔고

조회

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

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

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

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

변동 실시간 조회용으로 활용

금투사

(민감도

높은

금융정보)

페이지 5 / 133

거래내역

조회

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

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

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

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

주문

서비스

신규주문 금투사

<->

STB-HUB

<->

오픈플랫폼

<->

핀테크

신규 주문 제출

▶ 증권사 마다 주문번호 부여 기준이

다를 수 있고, List 주문은 지원 하지 않음

금투사

(일임형

자문업자만

사용 가능)

주문취소 제출된 주문 취소

▶ List 취소 주문은 지원 하지 않음

주문정정

제출된 주문 정정

▶ 가격 정정 : 일부 정정은 불가, 잔량

전체 지정

▶ 수량 정정 : 수량 증가 불가

일임매매

서비스

주문체결

조회

금투사

->

오픈플랫폼

->

핀테크

금융상품의 주문 및 체결된 정보를 조회

하기 위한 API

금투사

(일임형

자문업자만

사용 가능)

일임계좌 잔고

조회

자산내역을 보유종목, 보유수량, 손익

등으로 상세하게 제공하기 위한 API

결제 예정 정산

조회

매매 정리된 정보를 통해 결제예정 사항

을 확인하기 위한 API

일임 설정계좌

조회

일임매매 기관의 일임설정 계좌에 대한

정보를 제공하기 위한 API

일임계좌 거래내역

조회

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

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

시세

서비스

유가증권

및

코스닥

시세조회

코스콤

->

오픈플랫폼

->

핀테크

▶ 종목리스트 조회 API

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

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

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

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

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

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

▶ 종목별 호가 정보 조회 API

▶ 종목별 체결 정보 조회 API

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

코스콤

(일반정보)

페이지 6 / 133

선물시세

조회









옵션시세

조회









분석

서비스

비씨카드 섹터별

지수

비씨카드

->

오픈플랫폼

->

핀테크

국내 카드 가맹점들의 섹터별/월별

매출 거래 건수에 대한 지수 정보 비씨카드

(일반정보) 비씨카드 종목지수

(제공예정)

카드 빅데이터 기반으로 상장 종목

의 월별 매출 추세를 추산한 지수

RA테스트베드

알고리즘

코스콤

->

오픈플랫폼

->

핀테크

▶ 알고리즘 목록조회

▶ 알고리즘 운용실적

▶ 알고리즘 위험 및 성과지표

코스콤/RA테

스트베드

사무국

(일반정보)

BIGBOT

핀테크

->

오픈플랫폼

->

핀테크

▶ 종목분석

▶ 투자성향 조사

▶ 포트폴리오 추천 및 평가

▶ 자산배분

핀테크/

빅트리

(일반정보)

뉴스

서비스

금융뉴스

검색

핀테크

->

오픈플랫폼

->

금투사, 핀테크

▶ 통합 시세조회 서비스 API

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

핀테크/

위버플

(일반정보)

재무

서비스

재무정보

제공

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

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

핀테크/

BSMIT

페이지 7 / 133

▶ 금액별 포트폴리오

▶ 파봇랭크

(일반정보)

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

핀테크/

위버플

(일반정보)

페이지 8 / 133

Chapter 3. 오픈플랫폼 이용 방법

API 이용 절차

오픈 플랫폼에 API를 게시(제공) 또는 API를 구독(사용)하기 위해서는 사전에 이용기

관 등록이 완료되어야 합니다.

이용기관 등록 절차

① API및 서비스 사전 검증

- API 게시(제공) 또는 API 구독(사용) 서비스의 자본시장 발전과 관련 여부 검토

※ 사행성, 미풍양속의 저해 여부 등 검토

② 관련서류 제출

- 오픈 플랫폼 이용 신청서(별도 양식)

- 법인등기부등본, 사업자 등록증

- 사업계획서 (자유양식)

- API 기능 내역(API 제공자) 또는 API 이용 예정 서비스 내역(API 구독자)

※ 금융투자 핀테크 포털 (기업/금투사) biz.koscom.co.kr > 오픈플랫폼 이용 안내 참조

③ 오픈 플랫폼 이용 적정성 검토

- 오픈 플랫폼 이용 자격 등 검토

④ 최종 승인 및 회원사 공지

- 금투사의 금융거래 API 를 이용한 서비스의 경우 회원사 공지

페이지 9 / 133

API 게시(제공) 절차

오픈 플랫폼에 API를 게시하기 위해서는 Sandbox에서 API 게시 및 테스트를 완료하여

야 합니다.

API 구독(사용) 절차

핀테크 기업이 오픈 플랫폼의 API를 이용하여 새로운 서비스를 제공하기 위해서는

Sandbox에서 업무적합성 검증을 완료하여야 합니다.

페이지 10 / 133

Chapter 4. API 인증 방식

인증방식

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

같습니다.

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

코스콤 개발자센터 (developers.koscom.co.kr)에 앱을 등록 완료 후 할당 받은

API Key를 지정된 Query parameter 혹은 HTTP header에 넣어 전송하고, 이를

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

Basic Authentication: 일임매매 전용 API를 사용하는 경우 코스콤 개발자센터

(developers.koscom.co.kr)에 앱을 등록 완료 후 할당 받은 API Key 및 Secret를

조합하여 Base64로 인코딩한 값을 지정된 HTTP header에 넣어 전송하고, 이를

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

OAuth: 계좌기반API를 사용하는 경우 코스콤 개발자센터

(developers.koscom.co.kr)에 앱을 등록 완료 후 할당 받은 API Key(Client ID),

Client Secret와 개발자가 입력한 redirect_uri 및 API별 scope를 지정된 HTTP

header에 넣고, 추가로 API를 호출하기 전 이용자로부터 정보접근 동의를 받은

후 오픈플랫폼으로부터 제공받는 Access Token을 헤더에 포함시켜 인증을

받는 방식

API Key Authentication

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

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

확인하게 됩니다.

페이지 11 / 133

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"

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/XB8Yw==

"

},

"body": {

"korName": "홍길동"

}

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

페이지 12 / 133

Basic Authentication

Basic Authentication 인증체계를 사용하는 API는 민감정보가 포함된 데이터를 전용회선

을 사용하는 금융기관에 한정하여 API 요청•응답하는 경우이며, API호출 시 포함되어 전

송된 인증 값의 정상 여부를 판단하여 접근을 승인하고 있습니다. 승인과정이 정상적으

로 처리되면 오픈플랫폼은 API호출에 필요한 핀테크 서비스는 API를 호출할 때 서비스

를 받아주어 해당 금융기관에 전송하게 됩니다.

Base64로 encoding방법

- Apikey + “:” + Secret 값을 결합하여 string 생성

- 생성된 string을 base64 encoding 함

- ‘Basic ‘ + encode string 결합하여 Authorization의 인자 값으로 사용함

- apikey 및 secret : 개발자 센터에서 앱 성생 시 발급되는 고유 정보

headers: {

‘Authorization’: ‘Basic ‘ + new Buffer(apikey + ‘:’ + secret).toString(‘base64’)

}

POST 방식: HTTP header의 authorization 필드에 값을 넣어 전송

curl -X POST -H "comId:00995” –H

“authorization:Basic QwsxdWAf1D34A5fdsdassdeerf234248b6fbd42a1a6844861524b2320” -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": “null”,

페이지 13 / 133

"ci": "null"

},

"contractRequestBody": {

"count”: 0,

“page”: ”null”

}

}' "https://sandbox-apigw.koscom.co.kr/v1/account/accountlist/search"

페이지 14 / 133

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를 사용할

경우에 적합하며, 주기적으로 데이터소유자의 위임을 받아 데이터에 접근할

필요가 있는 비즈니스 모델에 사용됩니다.

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

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

데이터접근동의를 하고 access token을 받아 단말 프로그램에서 API를 호출하는

구조에 적합합니다. 따라서 응답으로 온 데이터를 주로 화면에 출력하는

비즈니스 모델에 사용됩니다. 발급된 access token의 유효시간을 연장시키는

refresh token은 지원되지 않으며, access token의 유효시간이 만료되면

데이터접근동의절차를 다시 수행해야 합니다.

Authorization Code Grant Flow

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

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

페이지 15 / 133

이용자가 위임했던 데이터접근권한을 무효화시키기 위한 수단이 서비스에

마련되어야 합니다.

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

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

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

합니다.

[Authorization Code Grant Flow 절차]

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

2~6. Authorization Code 요청과 응답

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

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

redirect하는 과정입니다.

(2) Authorization Code 요청

Method GET

페이지 16 / 133

Endpoint > https://sandbox-

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

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

Parameter

s

response_type=code&

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

redirect_uri=구현된 callback listener 주소&

scope=지정된 scope&

state=돌려받을 opaque value

respons

e_type

code

client_i

d

서비스 등록 시 부여 받은 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=l7xxf234248b6fbd42a1a684486152

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

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

Scope

scope 설명 유효시간

profile 회원 프로필 API 600초

페이지 17 / 133

(*별도 문의) (10분)

account

금융투자 회사의 계좌조회 API

▶ 계좌잔고

▶ 거래내역

▶ 포트폴리오

▶ 관심종목

2592000초

(30일)

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

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

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

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

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

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

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

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

필요합니다.

페이지 18 / 133

(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을

요청합니다.

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

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 authorizatio

n

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

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

Basic Base64(client_id:client_secret)

Content-

type

Application/x-www-form-urlencoded

Parameter

s

grant_type=authorization_code&

code=할당받은 authorizationcode&

redirect_uri=구현된 callback listener 주소

grant_type authorization_code

code Authorization code 요청을 통해 받은 code

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


페이지 19 / 133

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 유효시간 (초)

API 호출

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

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

Method POST

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

Header Authorizatio

n

발급받은 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": {

페이지 20 / 133

"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"

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

Header authorizatio

n





페이지 21 / 133


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

Parameter

s

grant_type=refresh_token&

refresh_token=발급받은 refresh_token&

scope=지정된 scope

grant_type refresh_token

refresh_toke

n

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

refresh token

scope 지정된 scope으로 선택항목

Example

Access Token 갱신 (Refresh Token) 응답

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

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/re

voke

Header authorizatio

n




페이지 22 / 133

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

Parameter

s

token=발급받았던_token&

token_type_hint=access_token또는refresh_token

token rovoke대상이되는 access token

token_type_

hint

access_token, refresh_token

Token Revocation 응답

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

Implicit Grant Flow

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

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

페이지 23 / 133

모바일 앱에서 오핀과 연동하기

핀테크 서비스가 모바일 앱으로 구현 되었다면, ‘금융투자 핀테크 포털’ 모바일 버전인

‘오핀’을 통해 사용자 인증을 받을 수 있습니다.

핀테크 앱 실행 OAuth 로그인 정보제공 권한 허용

핀테크 서비스가 앱으로 구현되었다면

오핀과 연동 하세요.

OFIN설치 여부 체크 후 설치되어 있을

경우 OFIN 실행>OAuth 화면이 열립니다.

OAuth로그인이 완료되면 정보제공 권한

여부 설정 화면으로 이동합니다. [허용]

터치 시 핀테크 앱의 서비스를 이용할 수

있습니다.

iOS 및 Android 용 SDK를 지원하고 있습니다.

‘코스콤 개발자센터 (developers.koscom.co.kr) > API 문서 > 참조문서’ 및 ‘리소스 >

SDK 다운로드’ 를 참조 하세요.

페이지 24 / 133

Chapter 5. Sandbox 개발자 센터 이용

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

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

발송되며, 신청서류를 ( http://biz.koscom.co.kr/ ‘오픈플랫폼 이용안내’ 참조 ) 작성하여

[email protected]으로 메일 발송하시면, 관리자에 의해 승인 후 승인 완료 메일 수신

후 로그인이 가능합니다.

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

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

수 있도록 관련 기능을 제공합니다.

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

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

Application 정보 등록

응용 프로그램 이름

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

않습니다.)

설명

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

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

http://biz.koscom.co.kr/


페이지 25 / 133

API 관리 정보 등록

API 추가

-Subscribing을 원하는 API를 선택

이용약관 동의

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

API가 없으면 ‘Next Step’버튼을 누릅니다.

인증 정보 등록

페이지 26 / 133

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’ 와 같이 입력 하세요.

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

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

수 있습니다.

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

API 테스트

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

페이지 27 / 133

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

인증방식 - API Key Type

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

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

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

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

식으로 선택 하세요.

페이지 28 / 133

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

습니다.

페이지 29 / 133

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

인증방식 - OAuth

현재는 OAuth2.0 Grant Type 중 Authorization Code만 지원하며, Implicit Grant Type등은 보안수준, 비즈니

스모델에 따라 협의가 필요합니다.

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

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

페이지 30 / 133

Grant Type

‘Authorization Code’를 선택 합니다.

Client ID

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

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’ 값을 입력 합니다.

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


페이지 31 / 133

‘OK’ 버튼을 누르시면, 사용자 로그인창이 오픈 되며, 아이디 및 비밀번호를 입력하시고, 로그인 합니다.

아이디와 비밀번호(OTP번호)는 금융투자 핀테크 포털 가입 시 등록한 것이며, 테스트를 위해 별도로 부여

되며 ( 테스트 계정 : https://developers.koscom.co.kr ‘API문서 > 계좌서비스’ 가상증권사용 테스트 데이

터 참조 ) 추가적인 고유 계정이 필요 하시면 관리자에게 문의 하십시요.

https://developers.koscom.co.kr/

페이지 32 / 133

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

습니다.

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

페이지 33 / 133

페이지 34 / 133

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 표기법 표준에 따라

페이지 35 / 133

Scientific notation 사용

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

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

돌아옴을 의미하며, “선택”은 주로 다른 항목의 구분 값에 따라 필수 항목인

경우를 의미

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

항목

서비스 연동 API

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

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

계좌기반조회 API를 사용하는 핀테크 서비스의 경우 먼저 이용자가 금융투자 핀테크

포탈에 가입했는지를 API를 통해 확인하고, 미 가입자는 금융투자 핀테크 포탈

가입화면으로 유도해야 합니다. 그리고 사용하려는 증권회사의 계좌번호에 대응되는

가상계좌번호를 발급받아 핀테크서비스에 연결(핀테크 서비스 신청)을 수행해야 합니다.

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

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

API를 이용하여 설정한 가상계좌가 있는지를 확인하고, 이용자가 원하는 계좌가 추가로

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

페이지 36 / 133

금융투자 핀테크 포탈 가입 여부 확인 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

Authentication

API Key

header – apikey: 발급받은 API key

Request Body

Property type Required? Description

partner Object -

┗ comId String(5) 필수 핀테크 기업 코드

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

commonHeader Object

┗ reqIdPlatform String 사용안함

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

┗ ci String(88) 필수 연계정보 88byte

body Object -

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



페이지 37 / 133

Response Body


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

Example

Request Body Example

{

"partner":{

"comId":"F9999",

"srvId":"999"

},

"commonHeader":{

"reqIdPlatform":"",

"reqIdConsumer":"fsfsfshi23",

"ci":"Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rg

fgdfgfhpf5vmzjaA=="

},

"body":{

"korName":"홍길동"

}

}

Response Body Example

{

"result": "member"

}

페이지 38 / 133

핀테크 앱 사용 신청 여부 확인 및 가상계좌 리스트 조회 API

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

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

Syntax

URI



HTTP methods

POST

Format


Content-Type

Application/json

Authentication

API Key

header – apikey: 발급받은 API key

Request Body


partner Object



commonHeader Object

┗ reqIdPlatform String(20) 사용안함

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


body Object - 요청 메시지 본문



페이지 39 / 133

┗ 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":"Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rg

fgdfgfhpf5vmzjaA=="

},

"body":{

"korName":"홍길동"

}

}

페이지 40 / 133


{

"vtAccList":[

{

"comId": " 00002",

"vtAccNo":"160657695589800099",

"vtAccAlias":"주식투자용"

},

{

"comId":" 00002",

"vtAccNo":"160657695589800099",

"vtAccAlias":"펀드투자용"

}

]

}

페이지 41 / 133

계좌기반 조회 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/

페이지 42 / 133

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

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

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

신한금융투자 SHINHAN 00002 제공

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

대신증권 DAISHIN 00004 제공

대우증권 DAEWOO 00005 미제공(미정)

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

유진투자증권 EUGENE 00008 제공

한양증권 HANYANG 00009 미제공(예정)

메리츠종합금융증권 MERITZ 00010 미제공(예정)

NH투자증권 NHINVEST 00012 제공

부국증권 BOOKOOK 00013 미제공(예정)

KB투자증권 KBINVEST 00017 제공

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

에이치엠씨투자증권 HMC 00022 미제공(미정)

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

유안타증권 YUANTA 00024 제공

SK증권 SK 00025 제공

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

삼성증권 SAMSUNG 00030 제공

동부증권 DONGBU 00031 제공

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

하이투자증권 HI 00046 제공

미래에셋증권 MIRAEASSET 00049 미제공(미정)

키움증권 KIWOOM 00050 미제공(예정)

리딩투자증권 LEADING 00052 미제공(미정)

하나금융투자 HANA 00056 미제공(미정)

이베스트투자증권 EBEST 00063 제공

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

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

페이지 43 / 133

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

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

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

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

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

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

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

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

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

페이지 44 / 133

자산 포트폴리오 조회 API

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

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

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

Syntax

URI

/account/portfolio/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication

OAuth 2- Authorization

header – Authorization: Bearer 발급받은 access token

Request Body


partner Object - 핀테크 서비스 정보



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

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

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

자


devInfo Object 단말정보

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

페이지 45 / 133

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

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

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

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

설정)

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

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

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

정)

accInfo -

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

portfolioRequestBod

y

Object

┗ queryType Object

┗ 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 값을 넣어 요

청

페이지 46 / 133

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

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

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

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

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

Response Body


commonHeader Object 요청 메시지 제어 헤더


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

자

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

┗ ci String(88) 반환 연계정보 88byte

accInfo

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

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

portfolioResponseBod

y

Object

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

┗ assetType String(8) 반환

┗ rspType String(8) 반환

┗ count Number 반환

┗ page String(24) 반환

┗ queryResult Object 응답 결과

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

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

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

portfolioList Object

portfolio Object

┗ cash Object CASH

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

┗ equityList array EQTY

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

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

페이지 47 / 133

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

┗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 Object

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

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

Example


페이지 48 / 133

{

"partner":{

"comId":"F9999",

"srvId":"999"

},

"commonHeader":{

"reqIdPlatform":"",

"reqIdConsumer":"ID000001",

"ci":"S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKS

ZNibNGg+/k0XB/9jQ=="

},

"devInfo":{

"ipAddr":"123451234500",

"macAddr":"7054D27EE247"

},

"accInfo":{

"vtAccNo":"160678007213500001"

},

"portfolioRequestBody":{

"queryType":{

"assetType":"ALL",

"rspType":"RAT",

"count":0,

"page":"null"

}

}

}


{

"commonHeader":{

"reqIdPlatform":"fs27abe2231",


"certDn":"",

페이지 49 / 133

"ci":"

S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNG

g+/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

},

{

페이지 50 / 133

"assetType":"KDQ",

"isinCode":"HK0000054723",

"qty":0.0,

"earningRate":-19.72

},

{

"assetType":"KSP",

"isinCode":"KR7000020008",

"qty":0.0,

"earningRate":10.95

},

{

"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"

},

{


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

"qty":5.0,


"maturity":"00000000"

페이지 51 / 133

},

{


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

"qty":5.0,


"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":"광주지방채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,

페이지 52 / 133

"earningRate":2.5

},

{

"assetType":"CP",

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

"qty":0.0,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":0.0,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":0.0,

"earningRate":0.86

}

]

}

}

}

페이지 53 / 133

계좌잔고 조회 API

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

Syntax

URI

/account/balance/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body







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

자


devInfo Object


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

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


페이지 54 / 133

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

설정)


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

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

정)

accInfo Object - 요청 메시지 본문


balanceRequestBody Object


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

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

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

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

가능





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

판단한 전송 가능한 적절한 건수로 요

청함을 의미함

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

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


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

터는 response에서 주는 page 값을 넣

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

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

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

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

페이지 55 / 133

Response Body

Property type Requried? Description


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

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

자



accInfo Object - 요청 메시지 본문



balanceResponseBody Object


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

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

ALL(전체)

┗ rspType String(8) 반환 -

┗ count Int 반환


┗ queryResult Object

┗ totalCnt Number 설정 총 메시지 건수

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

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

balanceList Object 잔고 종합

┗ balance Object

┗ summary Object 잔고 요약 (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 설정 총평가금액

페이지 56 / 133

┗ cashAvWithdraw Number 설정 출금가능액

┗ equityList 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 Array (FUND)

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

┗fundName Number 설정 펀드이름


┗valAtCur Number 설정 평가금액

┗proLoss Number 설정 평가손익

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

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

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


┗ etcList 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(분류가 불가한 경우 구

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

외)

페이지 57 / 133


┗valueAtCur Number 설정 평가금액


resp Object



Example


{

"partner":{

"comId":"F9999",

"srvId":"999"

},

"commonHeader":{

"reqIdPlatform":"",


"ci":"


g+/k0XB/9jQ=="

},

"devInfo":{

"ipAddr":"123451234500",


},

"accInfo":{

"vtAccNo":"160678007213500001"

},

"balanceRequestBody":{

"queryType":{

"assetType":"ALL",

"count":0,

"page":"null"

}

페이지 58 / 133

}

}


{

"commonHeader":{

"reqIdPlatform":"fagbbs22321",

"reqIdConsumer":" ID00002",

"certDn":"",

"ci":"


g+/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,

페이지 59 / 133

"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",

"isinCode":"HK0000054723",

"qty":1186.0,

"tradeType":"SUM",


"valAtCur":1867950.0,

"proLoss":-458921.0,


},

{

"assetType":"KSP",

"isinCode":"KR7000020008",

"qty":19.0,

"tradeType":"SUM",



"proLoss":19881.0,

"earningRate":10.95

페이지 60 / 133

},

{

"assetType":"KDQ",

"isinCode":"USU652221081",

"qty":71.0,

"tradeType":"SUM",



"proLoss":-12987.0,

"earningRate":-2.52

}

],

"fundList":[

{


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

"valAtTrade":0.0,

"valAtCur":7.2329965E7,

"proLoss":7.2329965E7,

"firstDateBuy":"20160112",

"lastDateBuy":"20160113",

"maturity":"00000000",

"earningRate":-9.58

},

{


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

"valAtTrade":0.0,

"valAtCur":8747937.0,

"proLoss":8747937.0,



"maturity":"00000000",


}, {


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

"valAtTrade":0.0,

페이지 61 / 133

"valAtCur":8416030.0,

"proLoss":8416030.0,



"maturity":"00000000",


}

],

"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",



"earningRate":1.76

},

{

"assetType":"BOND",

"assetName":"주택금융공사 MBS2016-10(1-4)",

"qty":1.0E10,

"tradeType":"SUM",



"earningRate":1.45

},

{

"assetType":"BOND",

페이지 62 / 133

"assetName":"주택금융공사 MBS2016-7(1-5)",

"qty":2.0E10,

"tradeType":"SUM",



"earningRate":3.08

},

{

"assetType":"BOND",

"assetName":"강원도개발공사 121",

"qty":1.0E10,

"tradeType":"SUM",



"earningRate":0.24

},

{

"assetType":"DLS",

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

"qty":5.4E10,

"tradeType":"SUM",



"earningRate":2.61

},

{

"assetType":"ELS",

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

"qty":2.0E10,

"tradeType":"SUM",



"earningRate":2.5

},

{

"assetType":"CP",

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

"qty":1.0E9,

페이지 63 / 133

"tradeType":"SUM",


"valueAtCur":1.0E9,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":1.0E9,

"tradeType":"SUM",


"valueAtCur":1.0E9,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":1.0E9,

"tradeType":"SUM",


"valueAtCur":1.0E9,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":1.0E9,

"tradeType":"SUM",


"valueAtCur":1.0E9,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":1.0E9,

"tradeType":"SUM",


페이지 64 / 133

"valueAtCur":1.0E9,

"earningRate":0.86

},

{

"assetType":"CP",

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

"qty":1.0E9,

"tradeType":"SUM",


"valueAtCur":1.0E9,

"earningRate":0.86

}

]

}

},

"resp":{

"respCode":"200",

"respMsg":"OK"

}

}

페이지 65 / 133

거래내역 조회 API

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

Syntax

URI

/account/transaction/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body


partner Object 핀테크 서비스 정보

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



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

분자

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

지 구분자


devInfo Object


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

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

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

페이지 66 / 133

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

자리로 채워서 설정)


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

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

우 UUID 설정)

accInfo Object


transactionHistoryRequestBod

y

Object

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

┗ 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


페이지 67 / 133

commonHeader 요청 메시지 제어 헤더

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

구분자

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

시지 구분자



accInfo



transactionHistoryResponseBod

y

Object

┗accInfo Object






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

더 이상 없음

┗ queryPrams Object

┗ 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 Object 거래내역 리스트

┗transaction Array 거래

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

표기)

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

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

도), ASK(매수),

페이지 68 / 133

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

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

따른 금액변동)

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

시는 0)

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

resp Object



Example


{

"partner":{

"comId":"F9999",

"srvId":"999"

},

"commonHeader":{

"reqIdPlatform":"",


"ci":"


g+/k0XB/9jQ=="

},

"devInfo":{

"ipAddr":"123456789012",


},

"accInfo":{

"realAccNo":null,

"vtAccNo":"160731060768600001"

},

"transactionHistoryRequestBody":{

"queryParams":{

"fromDate":"20160101",

"toDate":"20160720",

페이지 69 / 133

"isinCode":"",

"side":"",

"count":30,

"page":""

}

}

}


{

"commonHeader":{

"reqIdPlatform":"2ddacehgg",


"certDn":"",

"ci":"


g+/k0XB/9jQ=="

},

"accInfo":{

"realAccNo":"",

"vtAccNo":"160731060768600001"

},

"transactionHistoryResponseBody":{

"queryParams":{

"fromDate":"20160101",

"toDate":"20160720",

"isinCode":"",

"side":"",

"count":30,

"page":""

},

페이지 70 / 133

"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

},

{

"transDate":"20160202",

"transType":"ETC",

"isinCode":"",

"changeAmt":-100,

"changeQty":0,

페이지 71 / 133

"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"

}

}

페이지 72 / 133

관심종목 조회 API

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

Syntax

URI

/account/interest/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication



Request Body







분자

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

지 구분자


devInfo Object


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

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

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

페이지 73 / 133

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

자리로 채워서 설정)


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

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

우 UUID 설정)

accInfo Object


InterestSymbolListRequestBod

y

Object

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

권

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

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

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

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

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

답에 담기는 데이터는 이 건수를

초과하지 않음

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

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

건수로 요청함을 의미함

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

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

페이지부터는 response에서 주는

page 값을 넣어 요청

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

Response Body




분자

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

지 구분자

페이지 74 / 133



accInfo Object



interestSymbolListResponseBod

y

Object

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

권

┗ assetType String(8) 반환

┗ rspType String(8) 반환

┗ count Int 반환


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

권



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

상 없음

┗ groupList Object 관심종목그룹

┗group Array

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

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

┗isinCode String

Array

(각 20)

설정 종목코드

resp Object



Example


{

"partner":{

"comId":"F9999",

페이지 75 / 133

"srvId":"999"

},

"commonHeader":{

"reqIdPlatform":"",


"ci":"


g+/k0XB/9jQ=="

},

"devInfo":{

"ipAddr":"123456789012",


},

"accInfo":{

"vtAccNo":"160731060768600001"

},

"interestSymbolListRequestBody":{

"queryType":{

"assetType":"",

"rspType":null,

"count":0,

"page":"",

"totalCnt":0

}

}

}

페이지 76 / 133


{

"commonHeader":{

"reqIdPlatform":"fs901jjshgs",


"certDn":"",

"ci":"


g+/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":""

}

페이지 77 / 133

]

}

},

"resp":{

"respCode":"200",

"respMsg":"OK"

}

}

페이지 78 / 133

일임매매 연계 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/

페이지 79 / 133

주문체결 조회 API

계좌의 주문 체결 내역을 상세히 조회하기 위한 API

Syntax

URI

/b2baccount/orderdetail/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication


header – comId: 오픈 플랫폼으로부터 발급받은 기관 코드번호

header – authorization: Basic Authentication 인증 사용

Request Body

Property type Required

?

Description






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

orderDetailListRequestBo

dy

Object


페이지 80 / 133

┗ queryParameter Object

┗ qrAssetType String(8) 필수 자산유형[EQTY(주식), FUND(펀드),

ETC(기타)]

┗ qrSellBuyType String(8) 필수 매도수구분 [0(전체), 1(매도), 2(매수)]

┗ qrAccNo String(20) 필수 계좌번호

┗ qrOrderDate String(12) 선택 주문일자(입력 없는 경우 당일

(YYYYMMDD))

┗ qrIsinCode String(20) 선택 종목코드(입력 시 해당 종목만 요청)

┗ qrOrderNo String(20) 선택 주문번호(입력 시 해당 주문만 조회)

┗ count

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






함을 의미함

┗ page String(100) 선택 다음 page를 지시하는 키로 첫 요청은

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

response에서 주는 page 값을 넣어 요

청함

Response Body




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


┗ ci String(88) 사용안함 연계정보 88byte

orderDetailListRespons

eBody

Object


┗ qrAssetType String(8) 반환 자산유형[EQTY(주식), FUND(펀드), ETC(기

타자산)]

┗ qrSellBuyType String(8) 반환 매도수구분 [0(전체), 1(매도), 2(매수)]

┗ qrAccNo String(20) 반환 계좌번호(해당 계좌만 조회)

페이지 81 / 133

┗ qrOrderDate String(12) 반환 주문일자(입력 없는 경우 당일

(YYYYMMDD))

┗ qrIsinCode String(20) 반환 종목코드(입력 시 해당 종목만 요청)

┗ qrOrderNo String(20) 반환 주문번호(입력 시 해당 주문만 요청)



┗ queryResult




orderDetailList Object

┗ orderDeatil Array

┗ accNo String(20) 설정 계좌번호

┗ accName String(20) 설정 계좌명

┗ modifyType String(8) 설정 정정구분 [0(정상), 1(정정)]

┗ cancelType String(8) 설정 취소구분 [0(정상), 1(취소)]

┗ orderNo String(20) 설정 주문번호

┗ orgOrderNo String(20) 설정 원주문번호

┗ sellBuyType String(8) 설정 매도수구분 [1(매도), 2(매수)]

┗ orderType String(20) 설정 주문유형 – Text표기

┗ exchange String(20) 설정 KRX를 제외한 시장의 거래소명) - Text표

기

┗ crcyCode String(8) 설정 외화의 경우 통화코드 표기

┗ orderQty Number 설정 주문수량

┗ orderPrice Number 설정 주문단가

┗ execSumQty Number 설정 체결합계수량

┗ orderExecType String(20) 설정 주문체결구분[(접수전, 정정, 취소확인,

거부 등)] - Text표기

┗ cmsnType String(20) 설정 수수료유형 – Text표기

┗ settDays Number 설정 결제일수

┗ buyQtyUnit Number 설정 매도수량단위

┗ sellQtyUnit Number 설정 매도수량단위

┗ orderTime String(12) 설정 주문시각

┗ orderRejectReason String(20) 설정 주문거부사유 - Text표기

┗ isinInfo Array

┗ isinType String(20) 설정 종목코드종류(표준코드,축약코드, 축약영

문 등) - Text표기

페이지 82 / 133

┗ isinCode String(20) 설정 종목코드

┗ isinName String(40) 설정 종목명

┗ execList Array

┗ execQty Number 설정 체결 수량

┗ execPrice Number 설정 체결 단가

┗ execNo Number 설정 체결번호

┗ execTime String(12) 설정 체결시각

Resp Object



Example


{

"partner": {

"comId": "F9999",

"srvId": "999"

},

"commonHeader": {

"reqIdConsumer": "Fintech-2016062200001"

},

"orderDetailListRequestBody": {

"queryParameter": {

"qrAssetType": "EQTY",

"qrSellBuyType": "1",

"qrAccNo": "0019923122221",

"qrOrderDate": "20160622",

"qrIsinCode": null,

"qrOrderNo": null,

"count": 0,

"page": null

}

}

}

페이지 83 / 133


{

"commonHeader":

{

"reqIdPlatform": "5b19a7a5-443a-4b6b-a22b-17a627d3561b",

"reqIdConsumer": "Fintech-2016062200001",

"certDn": null,

"ci": null

},

"resp":

{

"respCode": "200",

"respMsg": "OK"

},

"orderDetailListResponseBody":

{

"queryParameter":

{



"qrAccNo": "001-01-992323232",


"qrIsinCode": null,

"qrOrderNo": null,

"count": 0,

"page": null

},

"queryResult":

{

"totalCnt": 0,

"count": 0,

"page": null

}

},

"orderDetailList":

페이지 84 / 133

{

"orderDetail": [

{

"accNo": "001-01-992323232",

"accName": "일임계좌",

"modifyType": "0",

"cancelType": "0",

"orderNo": null,

"orgOrderNo": null,

"sellBuyType": "1",

"orderType": null,

"exchange": null,

"crcyCode": null,

"orderQty": 0,

"orderPrice": 0,

"execSumQty": 0,

"orderExecType": null,

"cmsnType": null,

"settDays": 0,

"buyQtyUnit": 0,

"sellQtyUnit": 0,

"orderTime": "2016062211262636",

"orderRejectReason": null,

"isinInfo": [

{

"isinType": null,

"isinCode": "KR7000020008",

"isinName": "동화약품"

}

],

"execList": [

{

"execQty": 0,

"execPrice": 0,

"execNo": 0,

"execTime": null

}

]

페이지 85 / 133

}

]

}

}

페이지 86 / 133

일임 계좌잔고 조회 API

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

오전 08:30이전과 오후 16:00 이후 조회 가능

Syntax

URI

/b2baccount/balancelist/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication




Request Body


?

Description








페이지 87 / 133

balanceListRequestBody Object




ETC(기타)]







함을 의미함




어 요청함

Response Body

Property type Requried

?

Description






balanceListResponseBod

y

Object


┗ qrAccNo String(20) 반환 계좌번호


타자산)]





페이지 88 / 133



balanceList Object

┗ balance(항목삭제) Array 항목삭제(Array 삭제)

┗ accInfo Object



┗ cashBalInfo Array

┗ cashBalance Number 설정 현금잔고

┗ margin Number 설정 증거금

┗ substitute Number 설정 대용금

┗ receivable Number 설정 미수미납금

┗ totCreditAmt Number 설정 총대출금

┗ totlLoanAmt Number 설정 총신용금액

┗ valAtCur Number 설정 평가금액

┗ crcyCode String(8) 설정 통화코드(국제 통화코드 표기)

┗cashAvWithdraw Number 설정 출금가능현금

┗ securitiesBalInfo Array

┗ assetType String(8) 설정 자산유형(상품유형 표 참조)

┗ exchange String(20) 설정 KRX를 제외한 시장의 거래소명(대표적

으로 해외주식) - Text표기


┗ loanCreditType String(20) 설정 신용/대출구분 - Text표기

┗ loanCreditAmt Number 설정 신용/대출금

┗ qty Number 설정 잔고수량

┗ valAtTrade Number 설정 매수금액

┗ valAtCur Number 설정 평가금액

┗ proLoss Number 설정 평가손익

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

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

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

┗ foreignDeposit Number 설정 외화예수금

┗ wonDeposit Number 설정 원화예수금

┗ currencyRate Number 설정 기준환율

┗ isinInfo Array

┗ isinType String(20) 설정 코드종류(표준코드, 펀드코드, 단축코드,

상품코드 등) - Text표기

페이지 89 / 133

┗ isinCode String(20) 설정 종목코드, 펀드코드, 상품코드

┗ isinName String(40) 설정 종목명, 펀드명, 상품코드명

resp Object



Example


{

"partner": {

"comId": "F9999",

"srvId": "100"

},

"commonHeader": {


},

"balanceListRequestBody": {

"queryParameter": {

"qrAccNo": "0019923122221",


"count": 0,

"page": null

}

}

}

페이지 90 / 133


{

"commonHeader":

{

"reqIdPlatform": "4e4fe6b0-5598-4bfb-8fbd-b1da17b411fa",


"certDn": null,

"ci": null

},

"resp":

{

"respCode": "200",

"respMsg": "OK"

},

"balanceListResponseBody":

{

"queryParameter":

{


"qrAccNo": "0019923122221",

"count": 0,

"page": "null"

},

"queryResult":

{

"totalCnt": 2,

"count": 0,

"page": "null"

}

},

"balanceList":

{

"balance": [

{

"accInfo":

{

페이지 91 / 133

"accNo": "0019923122221",

"accName": "홍길동"

},

"cashBalInfo": [

{

"cashBalance": 3000000,

"margin": 2500000,

"substitute": 5000000,

"receivable": 0,

"totCreditAmt": 0,

"totLoanAmt": 3600000,

"valAtCur": 5500000,

"crcyCode": null,

"cashAvWithdraw": 500000

}

],

"securitiesBalInfo": [

{

"assetType": "KSP",

"exchange": null,

"crcyCode": null,

"loanCreditType": "자기융자",

"loanCreditAmt": 3600000,

"qty": 300,

"valAtTrade": 9000000,


"proLoss": -300000,

"earningRate": -0.1,

"lastBuyDate": "20170621",

"maturity": "20170921",

"foreignDeposit": 0,

"wonDeposit": 0,

"currencyRate": 0,

"isinInfo": [

{

"isinType": "표준코드",

"isinCode": "KR0065300",

"isinName": "삼성생명"

페이지 92 / 133

},

{

"isinType": "단축코드",

"isinCode": "A06530",


}

]

},

{

"assetType": "KSP",

"exchange": null,

"crcyCode": null,

"loanCreditType": null,

"loanCreditAmt": 0,

"qty": 120,

"valAtTrade": 4000000,


"proLoss": 400000,

"earningRate": 0.1,

"lastBuyDate": "20170621",

"maturity": null,

"foreignDeposit": 0,

"wonDeposit": 0,

"currencyRate": 0,

"isinInfo": [

{



"isinName": "삼성전자"

},

{



"isinName": "삼성전자"

}

페이지 93 / 133

]

}

]

}

]

}

}

페이지 94 / 133

결제예정 정산 조회 API

전일 및 당일 주문 체결 내역에 대한 매매정리 내역을 상세히 조회하기 위한 API로

오전 08:30이전과 오후 16:00 이후 조회 가능

Syntax

URI

/b2baccount/settlelist/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication




Request Body


?

Description







페이지 95 / 133


settleListRequestBody Object



ETC(기타)]

┗ qrSellBuyType String(8) 필수 매도수구분[0(전체), 1(매도), 2(.매수)]


┗ qrOrderDate String(12) 선택 주문일자(결제 전인 경우만 입력,

입력없음 당일(YYYYMMDD))

┗ qrIsinCode String(20) 선택 종목코드(입력 시 해당 종목만 요청)







함을 의미함




어 요청함

Response Body







settleListResponseBod

y

Object



타자산)]

┗ qrSellBuyType String(8) 반환 매도수구분[0(전체), 1(매도), 2(.매수)]

페이지 96 / 133


┗ qrOrderDate String(12) 반환 주문일자(입력 없음 당일(YYYYMMDD))

┗ qrIsinCode String(20) 반환 종목코드(입력 시 해당 종목만 요청)







settleList Object 결제예정 내역

┗ settleInfo Array



┗ sellBuyType String(8) 설정 매도수구분 [1(매도), 2(매수)]

┗ exchange String(20) 설정 거래소명 - Text표기


┗ settQty Number 설정 결제수량

┗ settAmt Number 설정 결제금액

┗ tradeType String(20) 설정 거래유형 – Text 표기

┗ loanCreditDate String(12) 설정 신용/대출일(YYYYMMDD)

┗ loanCreditAmt Number 설정 신용/대출금액

┗ settDate String(12) 설정 결제일자

┗ costTotal Number 설정 비용합계

┗ isinInfo Array

┗ isinType String(20) 설정 코드 종류(표준코드, 펀드코드, 단축코드,

상품코드 등) - Text표기

┗ isinCode String(20) 설정 종목코드, 펀드코드, 상품코드

┗ isinName String(40) 설정 종목명, 펀드명, 상품코드명

┗ costInfo Array

┗ costName String(20) 설정 비용명(수수료, 거래세, 농특세, 주민세

등) - Text표기

┗ cost Number 설정 비용금액

Resp Object



페이지 97 / 133

Example


{

"partner": {

"comId": "F9999",

"srvId": "100"

},

"commonHeader": {


},

"settleListRequestBody": {

"queryParameter": {



"qrAccNo": "0019923122221",


"qrIsinCode": "KR0065300",

"count": 0,

"page": null

}

}

}

페이지 98 / 133


{

"commonHeader":

{

"reqIdPlatform": "702889e9-3477-40fd-9711-299c7f4e2b24",


"certDn": null,

"ci": null

},

"resp":

{

"respCode": "200",

"respMsg": "OK"

},

"settleListResponseBody":

{

"queryParameter":

{

"qrAssetType": "KSP",


"qrAccNo": "0019923122221",


"qrIsinCode": "KR0065300",

"count": 0,

"page": "null"

},

"queryResult":

{

"totalCnt": 1,

"count": 0,

"page": "null"

}

},

"settleList":

{

"settleInfo": [

{

"accNo": "0019923122221",

페이지 99 / 133

"accName": "이지선",

"sellBuyType": "1",

"exchange": null,

"crcyCode": null,

"settQty": 300,

"settAmt": 9000000,

"tradeType": "자기융자매도",

"loanCreditDate": "20170627",

"loanCreditAmt": 360000,

"settDate": "20170627",

"costTotal": 171990,

"isinInfo": [

{




},

{




}

],

"costInfo": [

{

"costName": "거래세",

"cost": 45000

},

{

"costName": "주민세",

"cost": 126000

},

{

"costName": "일반수수료",

"cost": 990

페이지 100 / 133

}

]

}

]

}

}

일임설정 계좌 조회 API

핀테크 기업의 일임 설정 계좌의 정보 조회하기 위한 API

Syntax

URI

/b2baccount/accountlist/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication




Request Body


?

Description


페이지 101 / 133







accountListRequestBody Object







함을 의미함




어 요청함

Response Body


?

Description






accountListResponseBo

dy

Object







페이지 102 / 133


accountList Object

┗ account Array



┗ virtualAccNo String(20) 설정 가상계좌번호

┗ contractStatus String(8) 설정 일임설정상태[0(계약), 1(해지), 2(만기)]

resp Object



Example


{

"partner": {

"comId": "00995",

"srvId": "100"

},

"commonHeader": {


},

"accountListRequestBody": {

"queryParameter": {

"count": 0,

"page": null

}

}

}


{

"commonHeader":

{

"reqIdPlatform": "cc36edbf-e70b-4297-8e61-faafb2225c63",


페이지 103 / 133

"certDn": null,

"ci": null

},

"resp":

{

"respCode": "200",

"respMsg": "OK"

},

"accountListResponseBody":

{

"queryParameter":

{

"count": 0,

"page": "null"

},

"queryResult":

{

"totalCnt": 1,

"count": 0,

"page": "null"

}

},

"accountList":

{

"account": [

{

"accNo": "0019923122221",

"accName": "홍길동",

"virtualAccNo": "0929923212342",

"contractStatus": "0"

}

]

}

}

페이지 104 / 133

일임계좌 거래내역 조회 API

계좌의 거래내역을 상세히 조회하기 위한 API

Syntax

URI

/b2baccount/tradebook/search

HTTP methods

POST

Format


Content-Type

Application/json

Authentication




Request Body


?

Description







tradeBookListRequestBod

y

Object


페이지 105 / 133



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

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







함을 의미함




어 요청함

Response Body


?

Description






tradeBookListResponseBo

dy

Object



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

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






페이지 106 / 133


tradeBookList Object 거래내역 리스트

┗ tradeBook Array 거래



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

┗ transType String[8] 설정 거래구분[BID(매도), ASK(매수),DEP(이

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

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

변동으로 감소 시 “-“ 표기)

┗ changeQty Number 설정 수량증감 (매도/매수/출고에 따른 변동

으로 수량 감소 시 “-“ 표기)

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

┗ amt Number 설정 예수금 (거래 후 현금)

┗ exchange String(20) 설정 거래소명 – Text표기

┗ crcyCode String(8) 설정 통화코드

┗ subject String(40) 설정 계정명 – Text 표기

┗ summary String(40) 설정 적요명 – Text 표기

┗ isinInfo Array 종목코드정보

┗ isinType String(20) 설정 종목코드 종류 – Text 표기

┗ isinCode String(20) 설정 종목코드, 펀드코드, 상품코드 등

┗ isinName String(40) 설정 종목명

┗ costInfo Array 비용정보

┗ costName String(20) 설정 비용명 – Text 표기

┗ cost Number 설정 비용

Resp Object



Example


{

"partner": {

"comId": "00995",

"srvId": "100"

페이지 107 / 133

},

"commonHeader": {


},

"tradeBookListRequestBody": {

"queryParameter": {

"qrAccNo": "0019923122221",

"qrFromDate": "20170622",

"qrToDate": "20170627",

"count": 0,

"page": "null"

}

}

}


{

"commonHeader":

{

"reqIdPlatform": "88ea978a-22ab-4b32-9607-89c4fffaf103",


"certDn": null,

"ci": null

},

"resp":

{

"respCode": "200",

"respMsg": "OK"

},

"tradeBookListResponseBody":

{

"queryParameter":

{

"qrAccNo": "0019923122221",

"qrFromDate": "20170622",

"qrToDate": "20170627",

"count": 0,

페이지 108 / 133

"page": "null"

},

"queryResult":

{

"totalCnt": 1,

"count": 0,

"page": "null"

}

},

"tradeBookList":

{

"tradeBook": [

{

"isinInfo": [

{




},

{




}

],

"costInfo": [

{

"costName": "거래세",

"cost": 45000

},

{

"costName": "주민세",

"cost": 126000

},

{

페이지 109 / 133

"costName": "일반수수료",

"cost": 990

}

],

"accNo": "0019923122221",

"accName": "홍길동",

"transDate": "20170622",

"transType": "BID",

"changeAmt": -9000000,

"changeQty": 300,

"qty": 300,

"amt": 3000000,

"exchange": null,

"crcyCode": null,

"subject": "위탁자",

"summary": "이체출금"

}

]

}

}

기타 API

해당 문서에 기술되지 않은 일반 정보 API 관련 매뉴얼은 ‘코스콤 개발자 센터

(https://developers.koscom.co.kr) > API 문서 > 참고문서’를 참조해 주십시요.

https://developers.koscom.co.kr/

페이지 110 / 133

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

페이지 111 / 133

code Integer

message String

description(*optional) string

Error Code/Message

Common Error

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

HTTP

Respons

e 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 플랫폼 내부에서 발생하는 저 수준

오류의 경우.

페이지 112 / 133

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

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

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

서비스가 불가능한 경우.

505 505 HTTP Version Not

Supported

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

경우.

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

HTTP

Respons

e 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

Respons

e Status

Code

Error


페이지 113 / 133

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로 사용자를 찾을 수 없을 경

우

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

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

능한 경우.

페이지 114 / 133

Custom Error – 증권사 서버

HTTP

Respons

e 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 가 서로 불일치

4006 Agreement of Financial

Information Not Found. 정보제공 동의서의 동의 여부 확인 요망

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 이 아닌

값이 요청에 포함된 경우)

페이지 115 / 133

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, {상세한

사유를 대괄호안에 명

시}

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

페이지 116 / 133

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

① 포탈초기화면

② [회원가입] 금융투자 핀테크 포털 이용약관 동의

페이지 117 / 133

③ [회원가입] 본인인증절차

- 본인인증은 휴대폰을 통해 SMS 인증 문자 발송 후 수신 받은 인증번호를

입력 하시면 됩니다.

④ [회원가입] 회원정보 입력

페이지 118 / 133

⑤ [회원가입] 회원가입 완료

- 이메일로 회원가입 완료 메일 송신

페이지 119 / 133

⑥ 서비스 관리 > 앱 사용 신청

⑦ 사용하실 핀테크 앱 선택

페이지 120 / 133

⑧ 앱 사용 신청

⑨ 금융투자 회사의 가상계좌 발급

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

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

페이지 121 / 133

기존 계좌가 발급 되어 있어야함

⑩ 공인인증서 등록 및 금융거래정보 제3자 제공 동의 (플랫폼-금융투자회사)

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

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

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

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

오픈플랫폼을 통해 금융투자회사의 금융거래 정보를 제공하기 위해 필수적인 절차

입니다. 최초 한번만 동의하면 1년간 오픈플랫폼을 통한 금융거래 정보 전달 가능

※ 신규 금융투자회사가 추가되는 경우 계좌 생성시 재동의 절차가 필요함

페이지 122 / 133

⑪ [앱 사용 신청] 연결할 계좌 선택

하단의 가상계좌번호를 선택하면 핀테크 서비스가 API를 통해 계좌를 조회할 수

있는 가상계좌 권한정보가 오픈플랫폼에 설정됨

⑫ 금융거래정보 제3자 제공 동의 (핀테크 기업-금융투자회사)

공인인증서 전자서명 혹은 ARS인증 사용

페이지 123 / 133

핀테크 기업을 통해 금융투자회사의 금융거래 정보를 제공하기 위해 필수적인 절

차 입니다. 핀테크 기업별로 한번만 동의하면 1년간 핀테크 기업으로 금융거래 정

보 전달 가능 합니다.

핀테크기업-금융투자회사간의 금융거래 정보 제공 동의는 ‘공인인증서 전자서명’ 혹

은 ‘ARS 인증’을 통해 등록된 휴대폰 번호로 ARS 인증을 요청 합니다.

※ ARS 인증의 경우 전화 수신 후 내용을 청취 후 안내에 따라 인증 번호를 눌

러 주시면 됩니다.

페이지 124 / 133

⑬ 앱 사용 신청 완료

앱 사용 신청이 완료 되면, 해당 핀테크 서비스에 연결된 가상계좌를 통해 금융거

래 정보를 이용 하 실 수 있습니다. 사용 방법은 서비스별로 상의 할 수 있으며,

자세한 사항은 해당 서비스를 참조 하세요.

페이지 125 / 133

가상 계좌 관리

동의서 관리

페이지 126 / 133

통합계좌조회

코스콤 오픈플랫폼에 연결된 금융투자회사의 API를 통해 ’금융투자 핀테크 포털’에 등

록된 가상계좌를 통해 잔고현황, 거래내역, 포트폴리오, 관심종목등의 정보를 하나의

화면으로 조회 하실 수 있습니다.

페이지 127 / 133

참고 2. 오핀 (OFIN) 앱 이용 절차 (모바일)

① 메인

로그인 전 로그인 후 검색

로그인 전에는 플랫폼에 등록된 모든 앱

목록이 출력됩니다. 목록 터치 시 상세

화면으로 이동합니다.

로그인 후에는 신청 완료된 내 앱 목록이

출력됩니다.

키워드 입력 후 키패드의 이동 또는 다음

버튼을 터치하면 검색 결과가 출력됩니다.

- [X]버튼 터치 시, 검색 결과 초기화

② 메뉴

메인 메뉴 플로팅 메뉴 (로그인 전) 플로팅 메뉴(로그인 후)

앱 우측 상단 메뉴 버튼 터치 시 메뉴가

활성화됩니다. 메뉴명을 터치하시면 각


우측 하단 플로팅 버튼 터치 시, 로그인


로그인 후 우측 하단 플로팅 버튼 터치

시, 앱 사용 신청과 계좌관리 화면으로

이동할 수 있는 버튼이 활성화됩니다.

페이지 128 / 133

③ 회원가입

회원가입 안내 약관 및 본인인증 휴대폰 인증

로그인 화면에서 [회원가입] 버튼을

터치하면 가입에 대한 안내 화면으로

이동합니다. 내용 확인 후 [가입진행]

버튼을 터치합니다.

약관에 동의하시면 휴대폰 인증 버튼이

활성화됩니다.

정보 입력 후 [인증번호 전송] 버튼을

터치하면 SMS로 인증번호가

발송됩니다. 수신된 인증번호 입력 후

[인증하기] 버튼을 터치합니다.

페이지 129 / 133

④ 앱 사용 신청

앱 목록 앱 소개 (상세) 인증서 등록 및 정보제공동의

목록에서 신청할 앱을 터치합니다. 사용 신청 버튼을 터치합니다.

목록 버튼을 터치하면 앱 목록 화면으로

이동합니다.

핀테크 오픈 플랫폼 서비스 신청을

위해서는 공인인증서 등록 및

정보제공동의가 필요합니다.

[인증서 등록 및 전자서명] 영역을

터치합니다.

연결계좌 선택 연결계좌 선택 금융거래정보 제공 동의

가상계좌 추가가 완료되었습니다. 선택한 앱에 연결할 가상계좌 선택 후

다음 버튼을 터치합니다.

선택된 핀테크 기업(핀테크 앱 개발사)에

금융거래정보 제공을 위한 동의가

필요합니다.

페이지 130 / 133

앱 사용 신청 완료 메인 (앱목록) 상세

신청이 완료되었습니다. 코스콤과 선택한

핀테크기업에 정보 제공을 허용한

유효기간 동안 서비스 이용이

가능합니다.

신청이 완료되면 로그인 후 내 앱 목록에

표시됩니다.

신청 완료 후 상세 화면에서 연결계좌와

금융거래정보 제공 동의 내용을 조회할

수 있습니다.

계좌 추가가 필요할 경우 [신청 정보

수정] 버튼을 터치하면 수정화면으로

이동합니다.

페이지 131 / 133

⑤ 계좌관리

목록 수정 삭제

등록된 계좌 목록이 출력되며 별칭 또는

계좌번호 영역을 터치하시면 수정


별칭 수정이 가능합니다. 화면 하단 삭제 버튼을 터치하시면 삭제

재확인 후 삭제 처리됩니다.

⑥ 통합계좌조회

통합계좌조회 신청 여부 체크 앱 사용 신청 정보제공 권한 허용

통합계좌조회 메뉴 터치 시, 신청 여부를

체크하여 신청 전일 경우 메시지를

앱 신청과 관련된 부분은 앱 사용 신청

부분을 참고하시기 바랍니다.

신청 완료 후, 통합계좌조회 메뉴를

터치하면 .정보제공 권한 허용 선택

화면으로 이동합니다. 허용을 선택하시면

페이지 132 / 133

출력합니다. 확인 버튼 터치 시 신청


통합계좌조회 서비스를 이용할 수

있습니다.

통합계좌조회 통합계좌조회 통합계좌조회

상단에는 통합계좌조회 서비스에

연결된 계좌의 수와 해당 계좌의

금융투자회사 수가 출력되며 계좌는

등록되었지만 통합계좌조회 서비스에

연결되지 않은 계좌가 있을 경우

추가버튼이 출력됩니다.

검색을 원하는 금융투자회사 또는

가상계좌 선택 후 상단 검색 버튼을

터치합니다.

자산현황/거래내역/포트폴리오/관심종목

모두 원하는 조건 선택 후 검색 버튼을

터치하면 결과가 조회됩니다.

자산현황과 포트폴리오의 경우

주식/펀드/기타로 구분하여 조회됩니다.

Documents

본시장 공동 ଘ테크 오랫૬ · 오랫૬에 등록 된 ଘ테크 기업의 경ࡋ ࡊ에게 서비스를 제공ଡ 수 있습니다. 단, 주문 및 매매 관련 api는