자본시장공동핀테크오픈플랫폼 REST API Developer Guide Version 0.91(Draft),

Transcription

1 자본시장공동핀테크오픈플랫폼 REST API Developer Guide Version 0.91(Draft),

2 코스콤 박재성팀장 김흥재차장 오픈플랫폼운영담당자 (02) (02) 페이지 0 / 80

3 본문서는최종사용자에게정보를제공하기위한것이며, 코스콤은언제든지본문서를변경또는철회할수있습니다. 본문서는코스콤의재산적정보이며코스콤의사전서면동의없이본문서의전체혹은일부를복사, 전송, 재생, 공개, 수정또는복제할수없습니다. 코스콤은본문서의사용으로인해발생되는직, 간접손실이나손해 ( 수익의손실, 사업의중단, 영업권또는데이터손실포함 ) 에대해서는 ( 상기손실이나손해에대해사전에명시적으로통지를받은경우라하더라도 ) 귀하나제3자에게책임을지지않습니다. Copyright 2016 KOSCOM, All right reserved. 페이지 1 / 80

4 개정내역 버전 개정일 개정내역 비고 Request 요청중불필요한필드삭제 (DN, 실계좌번호등 ) - 관련 Json sample 수정 Sandbox 개발자센터안내추가 (19p) API 호출공통사항추가 (29p) 증권사제공 API 중 accinfo 블럭위치변경 ( 빨간색으로표시 ) OAuth 인증 Type API 호출시 header 에 apikey 삽입정책삭제 (15p) 페이지 2 / 80

5 Chapter 1. 자본시장공동핀테크오픈플랫폼개요 자본시장공동핀테크오픈플랫폼 ( 이하, 오픈플랫폼 ) 은증권회사를포함하는금융투자회사, 유관기관, 기타정보제공벤더가제공하는데이터및서비스를표준화된프로토콜, 단일인증방식, 표준메시지스펙으로핀테크기업과기타 3 rd 파트너에게 API를제공하는중계플랫폼입니다. 페이지 3 / 80

6 Chapter 2. 오픈플랫폼제공 API 제공 API 유형 오픈플랫폼에서제공하고있는 API는크게금융거래정보를받기위한것과기타정보를전달하기위한것으로나뉩니다. 금융거래정보API는주로금융회사의계좌를기반으로하고있으며, 관련법령에따라본인의동의절차를거쳐제3자에게제공되어야하기때문에추가적인권한확인절차가요구됩니다. 계좌기반 API를사용하여개발한서비스는요청메시지의키가되는실계좌번호를노출시키지않고, 안전하게제3자에게제공하기위해서비스이용자가금융투자핀테크포탈에가입하여가상계좌번호를발급하고, 금융거래정보제3자제공동의서를작성한후가상계좌번호를사용하고자하는핀테크서비스에연결하는선행과정이필요합니다. 그리고핀테크서비스가해당 API를이용하려고시도하는과정에서서비스이용자의확인과정이개입됩니다. 계좌기반 API를제외한나머지 API는금융투자핀테크포탈가입여부와관계없이오픈플랫폼에등록이된핀테크기업의경우이용자에게서비스를제공할수있습니다. API 유형 API 명제공구간기능 ( 데이터 ) 제공주체 ( 속성 ) 핀테크서비스이용자가오픈플랫폼 오픈플랫폼 회원인지확인하기위한 API 가입여부확인 가상계좌번호발급, 정보제공동의서작성등 서비스 연동 가상계좌목록조회 오픈플랫폼 -> 핀테크 사전절차안내필요여부확인用핀테크서비스이용자가발급받은가상계좌번호목록을금투사名과함께제공 금투사名과가상계좌목록을핀테크서비스 App에출력하여이용할계좌를 오픈플랫폼 ( 일반정보 ) 간편하게선택할수있도록함 페이지 4 / 80

7 투자자의자산내역 ( 증권, 파생, 펀드, 기타금융상품 ) 을보유비율 ( 구성비 ) 로 제공 자산 포트폴리오조회 자산상세내역 ( 투자금액, 보유주식수등 을노출시키지않고, 자산의구성비율만부담 없이제공할수있게함으로써투자성향분석등자문의기초자료로활용가능투자자가 HTS 등에등록해놓은관심종목리 금투사 ( 민감도낮은금융정보 ) 금투사 스트를조회할수있는기능 계좌기반 조회 관심종목 조회 -> 오픈플랫폼 -> 투자자가관심을보이는종목에대해뉴스, 분석정보, 이벤트 ( 급등락, 공시등 ) 의정보를능동적으로제공할수있는기초 핀테크 자료로활용가능 투자자의자산내역을보유종목, 보유수 계좌잔고조회거래내역조회 량, 손익, 예탁금등으로상세하게제공 통합자산관리, 자문서비스를위한기본정보, 향후주문서비스확대시자산변동실시간조회용으로활용금융상품의매수, 매도, 현금입출금내역을지정한기간별로조회하기위한 API 투자성향분석, 매수 / 매도시점분석을통해거래행태에대한자문가능 금투사 ( 민감도높은금융정보 ) 페이지 5 / 80

8 종목리스트조회 API 종목마스터데이터조회 API 유가증권및코스닥시세조회 (6종) : 종목명, 상하한가, 전일거래량, 기준가등 종목별과거데이터조회 API : 일, 주및월별과거시세제공 투자자별종가정보조회 API : 투자주체별매수 / 매도거래량, 거래대금 종목별호가정보조회 API 종목별체결정보조회 API : 현재가, 체결량, 누적거래량 코스콤 종목리스트조회 API 시세조회 선물시세조회 -> 오픈플랫폼 -> 종목마스터데이터조회 API : 종목명, 상하한가, 전일거래량, 기준가등 종목별과거데이터조회 API 코스콤 ( 일반정보 ) (6 종 ) 핀테크 : 일, 주및월별과거시세제공 -9 월제공 종목별호가정보조회 API 종목별체결정보조회 API : 현재가, 체결량, 누적거래량 종목리스트조회 API 종목마스터데이터조회 API 옵션시세 : 종목명, 상하한가, 전일거래량, 기준가등 조회 종목별과거데이터조회 API (6 종 ) : 일, 주및월별과거시세제공 -9 월제공 종목별호가정보조회 API 종목별체결정보조회 API : 현재가, 체결량, 누적거래량 페이지 6 / 80

9 금융뉴스 통합시세조회서비스 API 핀테크 / 정보검색 검색 기업정보조회 API ( 재무데이터 ) 위버플 (3 종 ) 금융뉴스검색 API ( 키워드, 분야별 ) ( 일반정보 ) 정보제공 재무정보제공 (2종) 비재무정보제공 (1종) 핀테크- > 오픈플랫폼- > 금투사, 핀테크 종목별영업이익률조회 API 업종별평균영업이익률조회 API 비재무정보 (ESG * ) 기반 기업가치분석조회 API * 환경, 소셜, 거버넌스 핀테크 / BSMIT ( 일반정보 ) 핀테크 / 지속가능발전소 ( 일반정보 ) API 이용절차 향후절차제공예정 페이지 7 / 80

10 Chapter 3. 핀테크서비스등록 등록절차를현재관련기관들과조율중입니다. 향후확정되면알려드리겠습니다. 등록절차 가마련되기전까지는코스콤으로연락주시면개발에필요한것들을준비해드리겠습니다. 페이지 8 / 80

11 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 " 페이지 9 / 80

12 POST 방식 : HTTP header 의 apikey 필드에 API Key 를넣어전송 curl -X POST -H "apikey: l7xxf234248b6fbd42a1a b2320" -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": " 홍길동 " ' " 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를사용할경우에적합하며, 주기적으로 페이지 10 / 80

13 데이터소유자의위임을받아데이터에접근할필요가있는비즈니스모델에사용됩니다. 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 절차 ] 페이지 11 / 80

14 0~1. 핀테크서비스자체인증수행 2~6. Authorization Code 요청과응답데이터소유자의동의를통해 authorization code를받기위한 flow를클라이언트사이드에서수행하고, 그결과를서버사이드에구현된 OAuth callback listener로 redirect하는과정입니다. (2) Authorization Code 요청 Method Endpoint Parameters Example GET > > response_type=code& client_id= 클라이언트 ID(API Key)& redirect_uri= 구현된 callback listener 주소 & scope= 지정된 scope& state= 돌려받을 opaque value response code _type client_id 서비스등록시부여받은 Client ID(API Key) redirect_ 핀테크기업의웹서버에구현된 OAuth callback listener uri 주소이며, 이값은최초서비스등록시입력했던값과동일해야함 scope API가접근하고자하는자원범위 ( 현재는사용안함 ) state state 값은본래 cross-site request forgery(csrf) 공격에대응하기위해사용하나, 대체로사용자세션정보를넣어 authorization code 요청의응답이서버로 redirect되었을때어느사용자의 authorization code인지를구분하기위해사용하는것이보통임. 요청에전송했던값이응답에그대로반환됨 ype=code&client_id=l7xxf234248b6fbd42a1a b2320&redirect_uri= callbacknew&scope=test.kiwoom&state=70e86bd5 페이지 12 / 80

15 (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을요청합니다. 에러처리는에러처리챕터를참고하시기바랍니다. 페이지 13 / 80

16 7~8. Access Token 요청과응답 (7) Access Token 요청 실제 API를호출할때필요한것은 access token입니다. Access token은 authorization code를이용하여요청할수있습니다. Method POST Endpoint > > 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 유효시간 ( 초 ) 페이지 14 / 80

17 API 호출 Access Token 발급절차를통해받은 access token 을 HTTP 헤더내의지정된필드에 포함시켜 API 를호출하면됩니다. Method Endpoint Header POST 호출하고자하는각 API의 endpoint Authorization 발급받은 access token을아래형식으로설정 Bearer access_token curl -X POST -H "Authorization: Bearer 748c46c8-940f-4eb8-a dbac6" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d ' "accinfo": "vtaccno": " " "balancerequestbody": "querytype": "assettype": "string", "count": 0, "page": "string" "commonheader": "ci": "Q9z5ccmjYNrhPVXrdfgfgfFdfgFGHdfg3fGFGgghDFFGghghgSSSfgfgcvbdfgert45rgfgdfgfhpf5vmzjaA==", "reqidconsumer": "string" "devinfo": "ipaddr": "IP", "macaddr": "string" "partner": "comid": "F0000", "srvid": "Mock" ' " 페이지 15 / 80

18 Access Token 갱신 (Refresh Token) 요청, Refresh token 기능지원여부는추후결정될것이므로이를고려한비즈니스모 델은사전협의필요 Access token 발급메시지에는갱신에사용되는 refresh token(refresh_token) 과 유효시간 (expires_in) 이들어있습니다. 필요에따라각 access token이만료되기전에 갱신을요청하면새로운 access token을발급받을수있습니다. Method POST Endpoint > > Header authorization client_id와 client_secret을 : 으로연결하여 base64 로 encoding한값을아래형식으로설정 Basic Base64(client_id:client_secret) 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 메시지가전달됩니다. 페이지 16 / 80

19 Token Revocation 핀테크서비스를구현할때반드시고객이위임하였던정보접근권한 (access token, refresh token) 을무효화할수있는기능을제공및사전안내해야하며, 이를 OAuth에서는 Token revocation으로구현할수있습니다. Revocation된후에다시 API를통해서비스를재사용하려면 OAuth 인증 flow를다시수행하면됩니다. Method POST or DELETE Endpoint > > evoke Header authorization client_id와 client_secret을 : 으로연결하여 base64 로 encoding한값을아래형식으로설정 Basic Base64(client_id:client_secret) 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 로전송 페이지 17 / 80

20 Implicit Grant Flow 현재제공되는 OAuth 인증체계를사용하는 API 중 implicit grant type을지원하는 API는없습니다. 향후본인증체계를사용하게되는경우에상세내용을제공하겠습니다. 페이지 18 / 80

21 Chapter 5. Sandbox 개발자센터이용 API에대한개발가이드와테스트를하기위해서는오픈플랫폼개발자센터 ( 회원에가입하시고, 이메일로승인대기안내메일이발송되며, 관리자에의해승인후로그인이가능합니다. ( 공식오픈까지는회원가입후오픈플랫폼관리자에게메일또는전화를주시면승인해드리겠습니다.) Sandbox 개발자센터는 API 개발에관련된가이드와개발및테스트용핀테크서비스응용프로그램 ( 앱또는웹서비스이며, 이하앱 ) 을등록하여개발단계에이용하실수있도록관련기능을제공합니다. 핀테크서비스애플리케이션등록 대시보드 > 어플리케이션에서하단에있는 응용프로그램추가 버튼을통해앱을생성 합니다. Application 정보등록 응용프로그램이름 플랫폼 ( 서비스플랫폼유형이며, 참고정보이며이값에따라제공되는 API 특성이결정되지는않습니다.) 설명 Application 정보 에해당항목을입력하고, Next Step 버튼을클릭합니다. 페이지 19 / 80

22 API 관리정보등록 API 추가 -Subscribing 을원하는 API 를선택 이용약관동의 API 관리 탭에서는사용할 API 를선택하고, 그에해당하는 API 이용약관에동의 하고, 더이상사용할 API 가없으면 Next Step 버튼을누릅니다. 페이지 20 / 80

23 인증정보등록 Callback URL Scope 유형 인증 의 Callback URL, Scope, 유형항목은사용할 API 의인증방식이 OAuth ( 현재는 OAuth2.0 만지원 ) 일때는필수로입력해야합니다. 유형은 public 를선택합니다. ( 현재는 OAuth2.0 Grant Type 중 Authorization Code 방식만지원함 ) API 문서 > 서비스 의 Swagger UI 로 OAuth2.0 을테스트하시려면, Callback URL 을 와같이입력하세요. 저장 버튼을누르고정상적으로접수가되면앱이추가되고, 앱상태가 승인보류 가됩니다. 코스콤개발자센터관리자가해당앱의사용을승인하면회원정보에등록된이메일로 앱승인 메일을받으실수있습니다. 앱등록정책에맞지않으면해당사유와함께거부될수도있습니다. 페이지 21 / 80

24 API 테스트 APIs & 플랜 메뉴에서테스트하려는 API 의인증유형을확인합니다. 인증방식 - API Key Type 페이지 22 / 80

25 API 문서 > 시세서비스 > 주식종목 메뉴에서 Select an Application 을눌러서앱을선택 합니다. 앱이보이지않으시면해당 API 를사용하는앱을먼저만드셔야합니다. Authentication (None) 버튼을누르시고, 인증방식을 API Key 로선택합니다. 해당 API 의 Method 가 GET 방식이면, API Key Type 를 Query 로선택하시고, POST 방식이면 Header 방식으로선택하세요. 테스트할 API 를선택하시고, Try it Out 버튼을누르시면아래와같이 Response 결과를 받아보실수있습니다. 페이지 23 / 80

26 기타에러코드는별도참조 Query 버튼을누르시면 Request 및다양한랭귀지의샘플데이터를참고하실수 있습니다. 페이지 24 / 80

27 인증방식 - 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 값을입력합니다. ( 자동입력 ) 페이지 25 / 80

28 Client Secret 앱의 Secret 값을입력합니다. ( 자동입력 ) Scope 앱에등록한 Scope 값을입력합니다 Authorize Endpoint 값을입력합니다. Token Endpoint 값을입력합니다. OK 버튼을누르시면, 사용자로그인창이오픈됩니다. 페이지 26 / 80

29 아이디및비밀번호를입력하시고, 로그인합니다. 아이디와비밀번호 (OTP 번호 ) 는금융투자 핀테크포털가입시등록한것이며, 테스트를위해별도로부여될수있으니관리자에게 확인이필요합니다. 테스트할 API 를선택하시고, Try it Out 버튼을누르시면아래와같이 Response 결과를 받아보실수있습니다. 페이지 27 / 80

30 Query 버튼을누르시면 Request 및다양한개발언어별샘플코드를참고하실수 있습니다. 페이지 28 / 80

31 Chapter 6. 금융투자회사 ( 증권사 ) 제공 API 이용 현재증권회사가오픈플랫폼을통해제공하고있는 API는모두계좌를기반으로하고있습니다. 따라서핀테크서비스회원과증권사고객정보를연결시킬식별자가필요하며이를휴대폰 아이핀본인확인서비스를통해발급받은연계정보 (CI, Connecting Information) 을사용하고있습니다. 또한증권사의실제계좌번호와 1:1로매핑된가상계좌번호를오픈플랫폼금융투자핀테크포탈 ( 에서발급하여연계정보와함께 API를통한요청의키로사용합니다. 따라서핀테크서비스가금융투자회사가제공하는계좌기반 API와같이금융거래정보가전달되는 API를사용하여개발하였다면핀테크서비스이용자는사전에 `금융투자핀테크포탈`에가입하여핀테크서비스에연결하고자하는증권회사의실계좌번호에연결된가상계좌번호를발급받아야하며, 사용하고자하는핀테크서비스에가상계좌번호를연결하는과정이선행되어야합니다. 자세한내용은참고자료에있습니다. 따라서계좌기반 API를사용하는핀테크서비스를이용자가사용하기위해서는사전에위와같은이용조건을충족했는지를확인하는것이필요합니다. 금융투자핀테크포탈`에가입하지않은이용자는포탈가입을유도해야하며, 가입이된이용자라하더라도가상계좌발급을받았는지여부와가상계좌를핀테크서비스에연결하였는지를확인할수있어야합니다. 오픈플랫폼은이를확인하기위한 API를제공하고있습니다. API 호출공통사항 요청데이터의값없음표기방법 : 필수필드이나값이없는경우는 로표기응답데이터의값없음표기방법 : 필드또는블록이없음 (null), 필드값이 null, 필드값이 null, 필드값이 로올수있으므로 null체크로직구현의주의필요 숫자표기에서 0이 9개이상표기되어야하는경우는 JSON 표기법표준에따라 Scientific notation 사용 스펙의 required 항목은 필수 는값이반드시있어야하거나, 적어도값이 로라도존재해야하는항목이며, 반환 은요청시값이그대로응답에실려돌아옴을의미하며, 선택 은주로다른항목의구분값에따라필수항목인경우를의미 Type의괄호안의숫자는권장최대길이이며, [ ] 안의숫자는길이가지정된항목 페이지 29 / 80

32 서비스연동 API 오픈플랫폼과핀테크서비스간에연동을위해금융투자핀테크포탈가입여부확인 API와핀테크서비스에연결된가상계좌를조회할수있는 API를제공합니다. 계좌기반조회 API를사용하는핀테크서비스의경우먼저이용자가금융투자핀테크포탈에가입했는지를 API를통해확인하고, 미가입자는금융투자핀테크포탈가입화면으로유도해야합니다. 그리고사용하려는증권회사의계좌번호에대응되는가상계좌번호를발급받아핀테크서비스에연결 ( 핀테크서비스신청 ) 을수행해야합니다. 이미금융투자핀테크포탈에가입한이용자는핀테크서비스에가상계좌를연결하였는지를확인하기위해핀테크서비스연결여부확인및가상계좌리스트조회 API를이용하여설정한가상계좌가있는지를확인하고, 이용자가원하는계좌가추가로필요하다면가상계좌발급과연결을안내해야합니다. 금융투자핀테크포탈가입여부확인 API 핀테크서비스이용자가금융투자핀테크포탈에가입했는지를확인하기위한 API Syntax URI HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json 페이지 30 / 80

33 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 Property type Required? Description result String(12) 필수요청의결과로값은 : member, nonmember Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"fsfsfshi23", "ci":"q9z5ccmjynrhpvxrdfgfgffdfgfghdfg3fgfggghdffgghghgsssfgfgcvbdfge rt45rgfgdfgfhpf5vmzjaa==" "body": "korname":" 홍길동 " 페이지 31 / 80

34 Response Body Example "result": "member" 핀테크서비스연결여부확인및가상계좌리스트조회 API 핀테크서비스이용자가금융투자핀테크포탈에서사용하려는핀테크서비스에연결한 가상계좌리스트를조회하기위한 API ( 금융거래정보제 3 자제공동의계좌 ) Syntax URI HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json Authentication header apikey: 발급받은 API key Request Body Property type Required? Description partner comid String[5] 필수 핀테크기업코드 srvid String(20) 필수 핀테크서비스코드 commonheader reqidplatform String(20) 사용안함 reqidconsumer String(20) 선택 핀테크기업에서사용하는메시지구분자 페이지 32 / 80

35 ci String[88] 필수연계정보 88byte body Complex - 요청메시지본문 korname String(12) 필수한글이름 Response Body Property type Required? Description vtacclist Array 가상계좌번호묶음 ( 배열로반복 ) comid String[5] 필수 금융회사코드 vtaccno String[18] 필수 가상계좌번호 vtaccalias String(20) 필수 가상계좌번호별칭 Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"fsfsfshi23", "ci":"q9z5ccmjynrhpvxrdfgfgffdfgfghdfg3fgfggghdffgghghgsssfgfgcvbdfge rt45rgfgdfgfhpf5vmzjaa==" "body": "korname":" 홍길동 " 페이지 33 / 80

36 Response Body Example "vtacclist":[ "comid": " 00002", "vtaccno":" ", "vtaccalias":" 주식투자용 " ] "comid":" 00002", "vtaccno":" ", "vtaccalias":" 펀드투자용 " 페이지 34 / 80

37 계좌기반조회 API 계좌기반조회 API는증권사별로호출 URI가다르나큰틀은동일하며단지증권사구분이 URI에포함되어있는구조입니다. API는버전으로구분되기때문에 URI에버전정보가포함되어있습니다. URI구조전체 URI - / 버전정보 / 증권사단축명 / 조회서비스구분 Endpoint / 버전정보 / 증권사단축명 / 오픈플랫폼 API gateway 주소 Production Sandbox 조회유의사항조회는 API에지정된가상계좌를조회범위로하기때문에계좌속성 ( 위탁, 펀드, 파생상품등 ) 에따라조회조건이충족되지않을수있으므로전상품군을대상으로조회할경우는주의가필요합니다. 예로보통증권회사의종합계좌는모든금융상품을취급할수있는것이지만경우에따라파생상품과같은특정상품군은별도로관리되는증권회사도있으며, 종합계좌개념을도입하지않는증권사도존재합니다. 따라서종합계좌라고판단되어 KOSPI200 파생상품잔고를조회하였을때응답에해당상품이반드시포함될것이라판단하고비즈니스를설계하면안됩니다. 예로자산포트폴리오조회와계좌잔고조회의경우모든상품군을조회범위에포함하는 ALL 검색조건을지원하는증권사의경우해당조건으로모든계좌를조회하면문제가없지만, ALL 검색조건을지원하지않는증권사의경우각상품군별로모든계좌를대상으로조회해야누락없이전상품군을조회할수있습니다. 페이지 35 / 80

38 증권사단축명과 API제공여부 ( 일기준 ) 증권사명 단축명 코드 API제공여부 교보증권 KYOBO 미제공 ( 미정 ) 신한금융투자 SHINHAN 제공 한국투자증권 KOREAINVEST 제공 (9 월중 ) 대신증권 DAISHIN 제공 대우증권 DAEWOO 미제공 (`17년) 신영증권 SHINYOUNG 미제공 ( 미정 ) 유진투자증권 EUGENE 미제공 ( 미정 ) 한양증권 HANYANG 제공 메리츠종합금융증권 MERITZ 제공 엔에이치투자증권 NHINVEST 제공 부국증권 BOOKOOK 제공 현대증권 HYUNDAI 제공 한화투자증권 HANWHA 미제공 ( 미정 ) 에이치엠씨투자증권 HMC 미제공 (12월계획) 유화증권 YUWHA 미제공 ( 미정 ) 유안타증권 YUANTA 제공 SK증권 SK 미제공 (9월중) 골든브릿지투자증권 GBRIDGE 미제공 ( 계획중 ) 삼성증권 SAMSUNG 제공 동부증권 DONGBU 미제공 (9월중) 케이비투자증권 KB 미제공 ( 계획중 ) 미래에셋증권 MIRAEASSET 미제공 (`17년) 키움증권 KIWOOM 제공 리딩투자증권 LEADING 미제공 ( 계획중 ) 하나금융투자 HANA 미제공 (12월중) 이베스트투자증권 EBEST 미제공 (9월중) 코리아에셋투자증권 KOREAASSET 미제공 ( 계획중 ) 비엔지증권 BNG 미제공 ( 계획중 ) 흥국증권 HEUNGKUK 미제공 ( 계획중 ) IBK투자증권 IBK 미제공 ( 계획중 ) 바로투자증권 BAROFN 미제공 ( 계획중 ) 페이지 36 / 80

39 토러스투자증권 TAURUS 미제공 ( 계획중 ) KTB투자증권 KTB 미제공 ( 계획중 ) 엘아이지투자증권 LIG 미제공 ( 계획중 ) 애플투자증권 APPLE 미제공 ( 계획중 ) 비엔케이투자증권 BNKFN 미제공 ( 계획중 ) 주 ) API 제공증권사와일정, API 제공범위는증권사의사정에따라변경될수있음 페이지 37 / 80

40 자산포트폴리오조회 API 조회대상이되는계좌의실제잔고수량, 투자금액대신금융투자상품의구성비만을제공함으로써개인금융정보의노출부담을최소화하면서도투자자산을기초로자산통합관리, 자문, 정보제공등을받을수있도록하기위한 API Syntax URI /account/portfolio/search HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json Authentication header Authorization: Bearer 발급받은 access token header apikey: 발급받은 API Key(Client ID) Request Body Property type Required? Description partner - 핀테크서비스정보 comid String[5] 필수 핀테크기업코드 srvid String(20) 필수 핀테크서비스코드 commonheader - 요청메시지제어헤더 reqidplatform String(20) 사용안함 플랫폼에서사용하는메시지구분자 reqidconsumer String(20) 필수 핀테크기업에서사용하는메시지구분자 ci String[88] 필수 연계정보 88byte devinfo 단말정보 ipaddr String(32) 필수 사용자단말 IP주소 (dot없이 3자리를 12자리로채워서설정 하며, 모바일인경우휴대폰번호로설정 하고 dash없이 10자리로채워서설정 ) macaddr String(50) 필수 사용자 MAC 주소 (PC의경우 MAC을 : 없이붙여 12자리 페이지 38 / 80

41 로표현하고, 모바일인경우 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투자증권, 대신증권, 키움증권, 신한증권 - 주 ) 보유비중조회는현재일부증권사의경우값이부정확한경우가있고, 비중대신수량을제공하는경우도있으므로주의필요함. 보유비중은수익기여도 ( 해당자산군에서해당종목이차지하는수익기여도 ) 로산출한경우가대부분이며, 증권사별산출기준은추후게시예정 페이지 39 / 80

42 Response Body Property type Required? Description commonheader complex 요청메시지제어헤더 reqidplatform String(20) 사용안함플랫폼에서사용하는메시지구분자 reqidconsumer String(20) 반환 핀테크기업에서사용하는메시지구분자 certdn String(256) 사용안함 "" ci String[88] 반환연계정보 88byte accinfo realaccno String(40) 사용안함 "" vtaccno String(30) 반환가상계좌번호 portfolioresponsebody querytype Complex assettype String(8) 반환 rsptype String(8) 반환 count Number 반환 page String(24) 반환 queryresult 요청시설정했던값이그대로전송 응답결과 totalcnt Number 설정조회조건의총메시지건수 count Number 설정현메시지내응답건수 page String(24) 설정다음 page 번호, null 이면더이상없음 portfoliolist portfolio cash complex 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 째 함 자리까지 ) earningrate Number 설정수익률 ( 소수점 2 째자리까지 ) maturity String(12) 설정만기일 (YYYYMMDD) etclist Array ETC 페이지 40 / 80

43 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째자리까지 ) 신용매수분포함하고대출잔고는반영안함 earningrate Number 설정 수익률 ( 소수점 2째자리까지 ) resp respcode String(8) 설정 응답코드참고 respmsg String(50) 설정 응답메시지참고 Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"id000001", "ci":"s1v7hgxbv1epgbjastzf4fqv+eopoc1pfizbyv6uieejhm/pf9qku+pu2otheog7qmvk SZNibNGg+/k0XB/9jQ==" "devinfo": "ipaddr":" ", "macaddr":"7054d27ee247" "accinfo": "vtaccno":" " "portfoliorequestbody": "querytype": "assettype":"all", "rsptype":"rat", "count":0, "page":"null" 페이지 41 / 80

44 페이지 42 / 80 Response Body Example "commonheader": "reqidplatform":"fs27abe2231", "reqidconsumer":"id000001", "certdn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "accinfo": "realaccno":"", "vtaccno":" " "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": "equitylist":[ "assettype":"ksp", "isincode":"hk ", "qty":0.0, "earningrate":-12.9 "assettype":"kdq", "isincode":"hk ", "qty":0.0, "earningrate": "assettype":"ksp", "isincode":"kr ", "qty":0.0, "earningrate":10.95

45 "assettype":"ksp", "isincode":"kr ", "qty":1.0, "earningrate":-3.97 "assettype":"ksp", "isincode":"kr ", "qty":0.0, "earningrate":-2.68 ], "fundlist":[ "fundcode":"krz ", "fundname":" 삼성중소형 FOCUS 증권자 1 호 [ 주식 ]", "qty":46.0, "earningrate":-9.58, "maturity":" " "fundcode":"krz ", "fundname":" 삼성중소형 FOCUS 증권자 1 호 [ 주식 ]", "qty":5.0, "earningrate":-12.52, "maturity":" " "fundcode":"krz ", "fundname":" 미래에셋고배당포커스증권자 1 호 (", "qty":5.0, "earningrate":-6.32, "maturity":" " ], "etclist":[ "assettype":"bond", "assetname":" 국민주택 1 종 11-07", "qty":2.0, "earningrate":22.73 "assettype":"bond", "assetname":" 국고 (14-5)", "qty":2.0, "earningrate":7.68 "assettype":"bond", "assetname":" 물가 (11-4)", "qty":3.0, "earningrate":4.39 페이지 43 / 80

46 "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":" 루카스 ", "qty":0.0, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":0.0, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":0.0, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":0.0, "earningrate":0.86 ] 페이지 44 / 80

47 계좌잔고조회 API 조회대상이되는계좌의실제잔고수량, 손익, 수익률등을상세히조회하기위한 API Syntax URI /account/balance/search HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json Authentication header Authorization: Bearer 발급받은 access token header apikey: 발급받은 API Key(Client ID) Request Body Property type Required? Description partner complex - 핀테크서비스정보 comid String[5] 필수 핀테크기업코드 srvid String(20) 필수 핀테크서비스코드 commonheader complex - 요청메시지제어헤더 reqidplatform String(20) 사용안함 플랫폼에서사용하는메시지구분자 reqidconsumer String(20) 필수 핀테크기업에서사용하는메시지구분자 ci String[88] 필수 연계정보 88byte devinfo ipaddr String(32) 필수 사용자단말 IP주소 (dot없이 3자리를 12자리로채워서설정 하며, 모바일인경우휴대폰번호로설정 하고 dash없이 10자리로채워서설정 ) macaddr String(20) 필수 사용자 MAC 주소 (PC의경우 MAC을 : 없이붙여 12자리 로표현하고, 모바일인경우 UUID 설정 ) 페이지 45 / 80

48 accinfo - 요청메시지본문 vtaccno String(30) 필수 가상계좌번호 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) 반환 핀테크기업에서사용하는메시지구분자 certdn String(256) 사용안함 "" ci String[88] 반환연계정보 88byte accinfo - 요청메시지본문 realaccno String(40) 사용안함 "" vtaccno String(30) 반환가상계좌번호 balanceresponsebody querytype assettype String(8) 반환요청하는자산유형이며값은 : SUM( 현금 ), 페이지 46 / 80

49 EQTY( 주식 ), FUND( 펀드 ), ETC( 기타자산 ), ALL( 전체 ) rsptype String(8) 반환 - count Int 반환 page String(24) 반환 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 (EQTY) array 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 설정 평가손익 earningrate Number 설정 수익률 ( 소수점 2째자리까지 ) fundlist Complex (FUND) array fundcode String(20) 설정 펀드표준코드 fundname Number 설정 펀드이름 valattrade Number 설정 매수금액 페이지 47 / 80

50 valatcur Number 설정 평가금액 proloss Number 설정 평가손익 firstdatebuy String(12) 설정 최초매수일 (YYYYMMDD) lastdatebuy String(12) 설정 최종매수일 (YYYYMMDD) maturity String(12) 설정 만기일 (YYYYMMDD) earningrate Number 설정 수익률 ( 소수점 2째자리까지 ) etclist Complex (ETC) array 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( 분류가불가한경우구분없이합산한경우며대출잔고는제외 ) valattrade Number 설정 매수금액 valueatcur Number 설정 평가금액 earningrate Number 설정 수익률 ( 소수점 2째자리까지 ) resp respcode String(8) 설정 응답코드참고 respmsg String(50) 설정 응답메시지참고 Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"id00002", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "devinfo": "ipaddr":" ", "macaddr":"7054d27ee247" 페이지 48 / 80

51 "accinfo": "vtaccno":" " "balancerequestbody": "querytype": "assettype":"all", "count":0, "page":"null" 페이지 49 / 80

52 Response Body Example "commonheader": "reqidplatform":"fagbbs22321", "reqidconsumer":" ID00002", "certdn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "accinfo": "realaccno":"", "vtaccno":" " "balanceresponsebody": "querytype": "assettype":"all", "count":"0", "page":"null" "queryresult": "totalcnt":157.0, "count":157.0, "page":"null" "balancelist": "balance": "summary": "cashbalance": , "d1": , "d2": , "substitute": e7, "receivable":0.0, "subsmargin": , "loancredit":0.0, "valattrade": e11, "valueatcur": e11, "proloss": e10, "totalaccval": e11, "cashavwithdraw": "equitylist":[ "assettype":"ksp", "isincode":"hk ", "qty":120.0, "tradetype":"sum", "valattrade": , "valatcur": , "proloss": , "earningrate":-12.9 "assettype":"kdq", 페이지 50 / 80

53 "isincode":"hk ", "qty":1186.0, "tradetype":"sum", "valattrade": , "valatcur": , "proloss": , "earningrate": "assettype":"ksp", "isincode":"kr ", "qty":19.0, "tradetype":"sum", "valattrade": , "valatcur": , "proloss": , "earningrate":10.95 "assettype":"kdq", "isincode":"usu ", "qty":71.0, "tradetype":"sum", "valattrade": , "valatcur": , "proloss": , "earningrate":-2.52 ], "fundlist":[ "fundcode":"krz ", "fundname":" 삼성중소형 FOCUS 증권자 1 호 [ 주식 ]", "valattrade":0.0, "valatcur": e7, "proloss": e7, "firstdatebuy":" ", "lastdatebuy":" ", "maturity":" ", "earningrate":-9.58 "fundcode":"krz ", "fundname":" 삼성중소형 FOCUS 증권자 1 호 [ 주식 ]", "valattrade":0.0, "valatcur": , "proloss": , "firstdatebuy":" ", "lastdatebuy":" ", "maturity":" ", "earningrate": "fundcode":"krz ", "fundname":" 메리츠코리아증권투자신탁 1 호 [ 주 ", "valattrade":0.0, "valatcur": , 페이지 51 / 80

54 "proloss": , "firstdatebuy":" ", "lastdatebuy":" ", "maturity":" ", "earningrate": ], "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":" 주택금융공사 MBS (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", 페이지 52 / 80

55 "qty":5.4e10, "tradetype":"sum", "valattrade":5.4e10, "valueatcur": e10, "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":" 루카스 ", "qty":1.0e9, "tradetype":"sum", "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":1.0e9, "tradetype":"sum", "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":1.0e9, "tradetype":"sum", "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":1.0e9, "tradetype":"sum", "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":1.0e9, "tradetype":"sum", 페이지 53 / 80

56 "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 "assettype":"cp", "assetname":" 루카스 ", "qty":1.0e9, "tradetype":"sum", "valattrade": e8, "valueatcur":1.0e9, "earningrate":0.86 ] "resp": "respcode":"200", "respmsg":"ok" 페이지 54 / 80

57 거래내역조회 API 조회대상이되는계좌의입금, 출금, 매수, 매도이력을조회할수있는 API Syntax URI /account/transaction/search HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json Authentication header Authorization: Bearer 발급받은 access token header apikey: 발급받은 API Key(Client ID) Request Body Property type Required? Description partner complex 핀테크서비스정보 comid String[8] 필수 핀테크기업코드 srvid String(20) 필수 핀테크서비스코드 commonheader Complex 요청메시지제어헤더 reqidplatform String(20) 사용안함 플랫폼에서사용하는메시지구분 자 reqidconsumer String(20) 필수 핀테크기업에서사용하는메시지 구분자 ci String[88] 필수 연계정보 88byte devinfo Complex ipaddr String(32) 필수 사용자단말 IP주소 (dot없이 3자리를 12자리로채워 서설정하며, 모바일인경우휴대 폰번호로설정하고 dash없이 10자 리로채워서설정 ) macaddr String(20) 필수 사용자 MAC 주소 (PC의경우 MAC을 : 없이붙여 12자리로표현하고, 모바일인경우 페이지 55 / 80

58 UUID 설정 ) accinfo Complex vtaccno String(30) 필수 가상계좌번호 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 commonheader Property type Required? Description 요청메시지제어헤더 reqidplatform String(20) 사용안함플랫폼에서사용하는메시지구 reqidconsumer String(20) 반환핀테크기업에서사용하는메시 분자 지구분자 certdn String(256) 사용안함 "" ci String[88] 반환연계정보 88byte accinfo realaccno String(40) 사용안함 "" vtaccno String(30) 반환가상계좌번호 페이지 56 / 80

59 transactionhistoryresponsebody accinfo realaccno String(40) 사용안함 "" vtaccno String(30) 반환 가상계좌번호 queryresult totalcnt Number 설정 총메시지건수 count Number 설정 메시지내응답건수 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 respcode String(8) 설정 응답코드참고 respmsg String(50) 설정 응답메시지참고 페이지 57 / 80

60 Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"id00003", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "devinfo": "ipaddr":" ", "macaddr":"7054d27ee247" "accinfo": "realaccno":null, "vtaccno":" " "transactionhistoryrequestbody": "queryparams": "fromdate":" ", "todate":" ", "isincode":"", "side":"", "count":30, "page":"" 페이지 58 / 80

61 페이지 59 / 80 Response Body Example "commonheader": "reqidplatform":"2ddacehgg", "reqidconsumer":"id00003", "certdn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "accinfo": "realaccno":"", "vtaccno":" " "transactionhistoryresponsebody": "queryparams": "fromdate":" ", "todate":" ", "isincode":"", "side":"", "count":30, "page":"" "queryresult": "count":30, "page":" ", "totalcnt":120 "translist": "transaction":[ "transdate":" ", "transtype":"dep", "isincode":"", "changeamt": , "changeqty":0, "qty":0 "transdate":" ", "transtype":"ask", "isincode":"nc30010", "changeamt": , "changeqty":0, "qty":0 "transdate":" ", "transtype":"dep", "isincode":"", "changeamt":100, "changeqty":0, "qty":0

62 "transdate":" ", "transtype":"etc", "isincode":"", "changeamt":-100, "changeqty":0, "qty":0 "transdate":" ", "transtype":"bid", "isincode":"nc30010", "changeamt": , "changeqty":0, "qty":0 "transdate":" ", "transtype":"wid", "isincode":"", "changeamt":-10000, "changeqty":0, "qty":0 "transdate":" ", "transtype":"wid", "isincode":"", "changeamt":-10500, "changeqty":0, "qty":0 ] "resp": "respcode":"200", "respmsg":"ok" 페이지 60 / 80

63 관심종목조회 API 조회대상이되는계좌에설정된관심종목을조회할수있는 API Syntax URI /account/interest/search HTTP methods POST Format JSON <application/json; charset=utf-8> Content-Type Application/json Authentication header Authorization: Bearer 발급받은 access token header apikey: 발급받은 API Key(Client ID) Request Body Property type Required? Description partner complex - 핀테크서비스정보 comid String[5] 필수 핀테크기업코드 srvid String(20) 필수 핀테크서비스코드 commonheader Complex - 요청메시지제어헤더 reqidplatform String(20) 사용안함 플랫폼에서사용하는메시지구분 자 reqidconsumer String(20) 필수 핀테크기업에서사용하는메시지 구분자 ci String[88] 필수 연계정보 88byte devinfo ipaddr String(32) 필수 사용자단말 IP주소 (dot없이 3자리를 12자리로채워 서설정하며, 모바일인경우휴대 폰번호로설정하고 dash없이 10자 리로채워서설정 ) macaddr String(16) 필수 사용자 MAC 주소 페이지 61 / 80

64 (PC의경우 MAC을 : 없이붙여 12자리로표현하고, 모바일인경우 UUID 설정 ) accinfo vtaccno String(30) 필수 가상계좌번호 InterestSymbolListRequestBody querytype querytype 지원증권사 : 삼성증권 assettype String(8) 필수 EQY( 유가증권 / 코스닥 ) rsptype String(8) 필수 "" ( 값없음 ) count Int 필수 응답별최대응답건수이며증권사는반드시이요청건수에맞춰전송할필요는없으나, 단일응답에담기는데이터는이건수를초과하지않음 0을설정하면증권사전송시스템이판단한전송가능한적절한건수로요청함을의미함 page String(24) 필수 다음 page를지시하는키로첫요청은 null 로표기하고, 다음페이 지부터는 response에서 주는 page 값을넣어요청 주 ) querytype 은삼성증권만지원되며, 타증권사는사용하지못함 Response Body commonheader Property type Required? Description 요청메시지제어헤더 reqidplatform String(20) 사용안함플랫폼에서사용하는메시지구 reqidconsumer String(20) 반환핀테크기업에서사용하는메시 분자 지구분자 certdn String(256) 사용안함 "" ci String[88] 반환연계정보 88byte accinfo realaccno String(40) 사용안함 "" vtaccno String(30) 반환가상계좌번호 interestsymbollistresponsebody querytype assettype String(8) 반환 rsptype String(8) 반환 count Int 반환 querytype 지원증권사 : 삼성증권 페이지 62 / 80

65 page String(24) 반환 queryresult querytype 지원증권사 : 삼성증권 totalcnt Number 설정 총메시지건수 count Number 설정 메시지내응답건수 page String(24) 설정 다음 page 번호, null이면더이상없음 grouplist 관심종목그룹 group Array groupname String(20) 설정 관심종목그룹이름 modifydate String(12) 선택 최종수정일 isincode String 설정 종목코드 Array ( 각 20) resp respcode String(8) 설정 응답코드참고 respmsg String(50) 설정 응답메시지참고 Example Request Body Example "partner": "comid":"f9999", "srvid":"999" "commonheader": "reqidplatform":"", "reqidconsumer":"id ", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "devinfo": "ipaddr":" ", "macaddr":"7054d27ee247" "accinfo": "vtaccno":" " "interestsymbollistrequestbody": "querytype": "assettype":"", "rsptype":null, "count":0, "page":"", "totalcnt":0 페이지 63 / 80

66 Response Body Example "commonheader": "reqidplatform":"fs901jjshgs", "reqidconsumer":"id ", "certdn":"", "ci":" S1V7HGXBV1EPGBJastZf4fQV+eOpOc1pfizByV6UIEEJHM/PF9QKu+PU2OThEog7QmVKSZNibNGg+/ k0xb/9jq==" "accinfo": "realaccno":"", "vtaccno":" " "interestsymbollistresponsebody": "grouplist": "group":[ "isincode":[ "KR ", "KR ", "KR ", "KR ", "KR " ], "groupname":" 관심종목00", "modifydate":"" "isincode":[ "KR ", "KR ", "KR ", "KR " ], "groupname":"etf", "modifydate":"" ] "resp": "respcode":"200", "respmsg":"ok" 페이지 64 / 80

67 Error 처리 Error 는증권회사, 오픈플랫폼의시스템등여러위치에서발생할수있으나 HTTP Response Status Code 와 Response Body 를통해오픈플랫폼표준 error code 와 message 로 전달합니다. Error message format HTTP Response Status Code HTTP Response Content-Type HTTP Response Body 4xx ~ 5xx Application/json; charset=utf-8 "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 category code message description(*optional) Data type String Integer String string 페이지 65 / 80

68 Error Code/Message Common Error 오픈플랫폼에서발생하는공통오류는 HTTP표준상태코드와오류코드를동일하게 준용 HTTP Response Error Status Code Error Message Description Code 요청자원에대한 Parameter, URI Bad Request Variable, Payload, Content Media- Type 이서버가요구하는명세와다르거나받아들일수없는경우 Unauthorized 클라이언트의인증요청이실패한경우. (e.g. API Key, OAuth ) Forbidden API 이용권한획득에실패한경우 Not Found API 가존재하지않는경우 Method Not Allowed API 가허용하지않는 HTTP Method 요청의경우 Not Acceptable API 가허용하지않는 Accept Media- Type 요청의경우 Request Timeout 요청 API 의수행시간이기준시간보다초과된경우 Unsupported Media API 가허용하지않는 Content-Type Type 요청의경우. 플랫폼내부에서발생하는저수준오류의 Internal Server Error 경우. (* low-level error 는비즈니스오류가아닌, 코드상의오류를말함 ) Service Unavailable 서버가일시적인오류이거나정상적인서비스가불가능한경우 HTTP Version Not 지원되지않는 HTTP 버전으로요청한 Supported 경우. 페이지 66 / 80

69 Custom Error - 오픈플랫폼인증서버 HTTP Response Status Code Error Code Error Message 2001 Authentication Failed 2002 Invalid OTP Key 2003 Account Locked 2100 Authorization Failed Description 핀테크서비스포탈사용자의인증에실패한경우. OTP Secret Key가유효하지않거나만료된경우. 인증시도제한횟수를초과하여계정이임시잠김. API 및서비스이용권한획득에실패한경우. Custom Error 오픈플랫폼증권사연계서버 HTTP Response Status Error Code Error Message Description Code Bad response trcode 금투사로부터잘못된 TRCODE 가옴 Unknown api url 요청한금투사 api 연결정보를찾을수없 는경우 필수항목누락필수항목이누락된경우 network error 일시적 network 장애가발생한경우 network timeout not found dn 금투사서버로부터메시지응답이지연된경우요청한 ci로사용자 dn값을찾을수없을경우 not found user 요청한 CI 로사용자를찾을수없을경우 페이지 67 / 80

70 not found company info 요청한금투사의정보를찾을수없을경 우 not found account info 실계좌번호를찾을수없을경우 expired account 요청계좌가폐기된계좌일경우 Json parsing error Json 메시지규격에오류가있을경우 Unknown account number 요청계좌가증권사에존재하지않을경우 Unknown account type 등록되지않은계좌유형의경우 Unknown error 프로그램내부에러 (ex : DB 에러 ) 가발생 했을경우 Target Company Service Unavailable 금투사서버가정상적인서비스가불가능 한경우. Custom Error 증권사서버 HTTP Response Status Error Code Error Message Description Code 200 OK 정상 4000 Mismatch between DN and AccoutNo DN 과계좌번호가서로불일치 4001 Account Not Found 해당계좌를찾을수없음 DN Not Found DN 값을찾을수없음 4003 Mismatch between CI and AccountNo CI 와계좌번호가서로불일치 4004 CI Not Found CI 값을찾을수없음 4005 Mismatch between DN and CI DN 과 CI 가서로불일치 페이지 68 / 80

71 Failure To Enrol an vtaccno, 상세한사유를대괄호안에명시 Failure To Change an vtaccno, 상세한사유를대괄호안에명시 Failure To Issue an vtaccno, 상세한사유를대괄호안에명시 Failure To discard an vtaccno, 상세한사유를대괄호안에명시 플랫폼에서발급한가상계좌번호등록실패 ( 요청방향 : 플랫폼-> 증권사 ) 발급된가상계좌번호또는가상계좌별칭변경실패 ( 요청방향 : 플랫폼-> 증권사 ) 증권사로요청한가상계좌발급이실패 ( 요청방향 : 플랫폼-> 증권사 ) 가상계좌폐기요청이실패 ( 요청방향 : 증권사-> 플랫폼, 플랫폼-> 증권사 ) 6001 Invalid Asset Type 지원하지않는상품구분자 6002 Invalid Rsp Type 6003 Invalid Page Value Invalid Query Type, 상 6004 세한사유를대괄호안에명시 Result Too Many, 요청 6005 한조회에대한결과건수 Date Range Exceeded, 6006 최대조회가능날짜수명시 지원하지않는응답유형 (QTY, RAT 이아닌값이요청에포함된경우 ) 존재하지않는 Page Key 값요청 ( 연속조회시존재하지않는 Key 값 ) 증권사에서제공가능한총건수 ( 연속조회를포함 ) 를초과한경우조회가능한날짜범위초과 6007 Invalid Isincode 존재하지않는 isincode 로조회요청 6008 Invalid Side Type Bad Request, 상세한 7000 사유를대괄호안에명시 잘못된거래구분조회조건, BID, ASK, DEP, WID, ALL 이아닌값으로조회 요청에서무엇이문제인지사유명시필요 페이지 69 / 80

72 참고 1. 금융투자핀테크포탈이용절차 1 포탈초기화면 2 본인인증절차 본인인증은휴대폰인증과아이핀인증의두가지타입을제공 페이지 70 / 80

73 3 공인인증서등록 금융거래정보제3자제공동의및개인식별보조수단으로인증서를사용하기때문에인증서등록절차필요. 공인인증서를통해증권사의고객을식별하기때문에증권사마다서로다른공인인증서를사용하는경우포탈에등록된공인인증서와다른공인인증서를사용하는증권사는사용에제약을받음 페이지 71 / 80

74 4 금융투자핀테크포털이용약관동의 5 회원기본정보등록 보안강화를위해 OTP( 오픈플랫폼전용모바일 OTP) 를사용하는경우 OTP 등록 필요 (OAuth 인증용으로만사용됨 ) 페이지 72 / 80

75 6 이메일주소확인 7 이용증권사선택 페이지 73 / 80

76 8 가상계좌발급 증권사에따라본인명의의계좌리스트를제공하는곳이있고, 지원하지않는 증권사는직접실계좌번호와계좌별칭을입력하는창으로제공 페이지 74 / 80

77 9 핀테크서비스선택 발급된가상계좌번호를기준으로해당증권사를지원하는핀테크서비스목록이 리스팅되며, 핀테크서비스를선택후하단의가상계좌번호를선택하면핀테크 서비스가 API 를통해계좌를조회할수있는권한정보가오픈플랫폼에설정됨 페이지 75 / 80

78 10 금융거래정보제 3 자제공동의 핀테크서비스에가상계좌를연결하고나면금융거래정보제 3 자동의를위한 정보 제공동의 버튼이활성화되며, 버튼을누르면동의서가팝업되며전자서명을할수 있음 페이지 76 / 80

79 11 핀테크서비스연결완료 페이지 77 / 80

80 발급된가상계좌조회 이용신청된핀테크서비스조회 페이지 78 / 80

81 페이지 79 / 80