무엇을 보관하나: 조회 전용 대시보드에 담는 데이터의 성격
이 글은 KB증권 계좌를 가진 직장인 투자자가 주문 기능은 쓰지 않고 잔고, 수익률, 관심종목 시세만 자신의 스프레드시트나 개인 대시보드에 모아 보려는 상황을 다룹니다. 자동매매까지 바로 가지 않고 조회부터 연결하려는 투자자는 베타 기간에 무엇을 기대할 수 있는지, 무엇이 아직 정해지지 않았는지 먼저 알아야 합니다. 서비스 개념과 기본 절차는 KB증권이 직접 정리한 KB증권 Open API란 안내에 나와 있으므로, 이 글은 개념 설명을 되풀이하지 않고 조회 전용 연결이라는 범위 안에서 확인할 기준만 정리합니다.
KB증권 안내 자료는 Open API로 만들 수 있는 것 가운데 하나로 개인 투자 대시보드를 들고, 내용을 내 자산 조회, 수익률 분석, 포트폴리오 관리로 설명합니다. 같은 자료는 관심종목 관리와 시세 확인, 잔고 조회·체결 조회·손익 분석도 활용 사례로 제시합니다. 조회 전용 대시보드가 다루는 데이터는 크게 세 가지로 나뉩니다.
- 계좌 데이터: 잔고, 보유 종목, 체결 내역처럼 내 계좌에서만 나오는 정보입니다. 계좌번호와 함께 다뤄지므로 노출 관리가 가장 중요합니다.
- 시세 데이터: 국내주식 시세, 종목 정보처럼 시장에서 나오는 정보입니다. 실시간 여부와 제공 범위는 API 문서에서 확인해야 합니다.
- 가공 데이터: 수익률, 비중, 손익처럼 위 두 데이터를 계산해서 만드는 값입니다. API가 주는 값이 아니라 이용자가 계산하는 값이므로 계산 오류에 대한 책임도 이용자에게 있습니다.
보관 조건: 베타 기간, 이용료, 거래비용을 나누어 봅니다
기간 조건부터 보면, KB증권 Open API는 2026년 7월 20일 베타로 오픈했고 정식 오픈은 2026년 연내 예정입니다. 고객 안내 자료는 오픈 일정과 제공 기능이 준비 상황과 운영 정책에 따라 달라질 수 있다고 밝히고 있습니다. 이 글의 근거 자료는 작성 기준일이 2026년 8월 28일이므로, 그 이후 바뀐 내용은 KB증권 Open API 포털의 최신 공지로 확인해야 합니다. 베타 기간에 만든 대시보드는 정식 오픈 시점에 API 명세나 호출 조건이 달라지면 수정이 필요할 수 있다는 전제로 운영하는 것이 합리적입니다.
비용 조건은 두 갈래로 나누어 봐야 합니다. 첫째는 API 이용료이며, 안내 자료는 이용료를 Open API 포털에서 확인하라고 안내합니다. 둘째는 거래비용이며, API를 통한 주문에도 거래 수수료·유관기관 비용·세금이 적용될 수 있다고 명시되어 있습니다. 조회 전용 대시보드는 주문을 내지 않으므로 둘째 항목은 주문 기능을 쓰는 순간부터 문제가 됩니다. 다만 API 주문에 어떤 수수료율이 적용되는지는 근거 자료에 따로 나와 있지 않으므로, 주문 기능으로 넘어가기 전 KB증권 수수료 안내에서 따로 확인해야 합니다. 증권회사별 거래 수수료를 비교해 보고 싶다면 금융투자협회가 공시하는 증권회사 수수료 비교 자료를 함께 참고할 수 있습니다.
보관 방식: 조회형 연결과 주문형 연결 비교
같은 인증 방식을 쓰더라도 조회만 하는 연결과 주문까지 하는 연결은 준비할 것이 다릅니다. 두 방식 모두 App Key와 Secret Key로 접근 토큰을 발급받고, 요청 헤더에 Bearer 형식으로 토큰을 담아 호출하는 구조입니다. 요청과 응답은 JSON 형식이며 인증은 Client Credentials 방식입니다. 차이는 오류가 났을 때 생기는 결과와 확인할 조건의 수에 있습니다.
- 조회형 연결의 오류 결과: 잘못된 값이 화면에 표시되는 수준에 그칩니다. 토큰 만료나 호출 실패 시 HTTP 상태 코드와 API 오류 코드를 확인해 다시 불러오면 됩니다.
- 주문형 연결의 오류 결과: 실제 체결로 이어질 수 있습니다. 안내 자료는 주문 요청을 단순히 반복하지 말고 주문번호와 체결 여부를 먼저 조회해야 중복 주문을 막을 수 있다고 설명합니다.
- 조회형 연결의 비용: API 이용료 기준만 확인하면 됩니다.
- 주문형 연결의 비용: API 이용료에 더해 거래 수수료·유관기관 비용·세금을 함께 따져야 합니다.
- 공통 준비물: KB증권 계좌, Open API 서비스 신청, 인증키 발급, 그리고 인증키를 코드에 직접 넣지 않고 환경변수나 별도 보관소에 두는 관리 방식입니다.
개발 경험이 적은 투자자라면 Java, Python, JavaScript, PHP, Ruby 샘플 코드 생성 기능을 활용해 조회 호출부터 시험해 볼 수 있습니다. 안내 자료는 모의거래 체험 기능을 제공한다고 적으면서도, 자주 묻는 질문에서는 모의투자 서비스가 추후 제공 예정이라고 따로 밝히고 있습니다. 두 기능의 범위가 같은지는 자료만으로 확정할 수 없으므로, 주문 로직을 시험하려는 시점에 포털에서 어떤 형태로 제공되는지 확인해야 합니다.
꺼낼 때: 주문 기능으로 넘어가거나 연동을 멈추는 기준
조회 전용으로 시작한 대시보드를 주문 기능으로 넓히는 시점은 기술 준비보다 조건 확인을 기준으로 정하는 것이 안전합니다. 안내 자료는 자동매매가 제공되는 주문 API 범위 안에서 가능하며, 주문 가능 상품과 시간, 호출 제한, 오류 처리 조건을 최신 API 문서로 확인해야 한다고 설명합니다. 따라서 주문 가능 상품, 수수료 적용 기준, 중복 주문 방지 절차 세 가지가 확인되기 전까지는 조회 전용 상태를 유지하는 것이 하나의 기준이 될 수 있습니다. 국내주식 정규시장 거래시간 같은 시장 운영 기준은 한국거래소가 공지하는 기준을 따르므로, API 이용 가능 시간과는 별개로 확인해야 합니다.
연동을 멈추거나 인증키를 교체해야 하는 경우도 미리 정해 두는 것이 좋습니다. 인증키가 공개 저장소, 블로그, 화면, 로그에 노출되었다면 즉시 폐기하고 다시 발급받아야 한다고 안내되어 있습니다. 대시보드 화면을 다른 사람과 공유하거나 화면을 캡처해 기록하는 습관이 있다면 계좌번호와 인증키가 함께 찍히지 않는지 점검해야 합니다. 시스템 점검, 장애, 정책 변경 시에는 일부 서비스 이용이 제한될 수 있으므로, 대시보드에 표시된 값이 갱신되지 않았을 때 증권사 앱의 잔고와 대조하는 절차도 함께 정해 두는 것이 바람직합니다.
점검 주기: 정식 오픈 전까지 확인할 항목
베타 기간에는 제공 범위가 단계적으로 바뀔 수 있으므로 정기적으로 확인할 항목을 정해 두는 것이 효율적입니다. 특히 근거 자료 안에서도 표현이 엇갈리는 부분이 있습니다. 이용 안내 표에서는 해외주식과 기타 금융상품을 향후 확대 예정으로 적고 있지만, 자주 묻는 질문에서는 제공 기능이 계좌·잔고 조회, 국내주식 시세·주문, 해외주식 등으로 시작한다고 적고 있습니다. 해외주식 잔고까지 대시보드에 담으려는 투자자라면 이 차이를 포털의 API 목록으로 직접 확인해야 합니다.
- 매월 확인: 포털 공지의 정식 오픈 일정 변경 여부, API 목록에 새로 추가된 기능, 이용료 기준 변경 여부입니다.
- 호출 오류 발생 시 확인: 초당·일일 호출 한도와 이용 가능 시간입니다. 안내 자료는 한도가 API와 운영 정책에 따라 다를 수 있다고 밝히며, 재시도 간격과 호출량 관리를 권고합니다.
- 정식 오픈 직후 확인: 토큰 발급 경로와 요청 형식, 각 API에 필요한 추가 헤더나 요청값의 변경 여부입니다.
- 주문 기능 도입 전 확인: 주문 가능 상품과 시간, KB증권 수수료 안내의 적용 기준, 모의거래 제공 형태입니다.
표기 차이도 점검 대상입니다. 공지와 포털에서는 App Key·Secret Key로, 개발가이드에서는 App key·App Secret으로 표기하며, 안내 자료는 이것이 같은 인증키를 가리킨다고 설명합니다. 문서를 오가며 설정할 때 이름이 달라 보여도 같은 값이라는 점을 알아 두면 설정 오류를 줄일 수 있습니다. 이 글은 특정 종목이나 상품의 매매를 권유하지 않으며, Open API를 활용한 자동 조회와 주문 역시 투자 판단과 실행의 책임이 이용자 본인에게 있다는 점을 밝혀 둡니다.