GoogleAIBuilder/KisStock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86c1c54126e65ebbbb7f535fab6a171088f34b52
KisStock/backend/api.md
LGram16 6d673e06ce 문서작업
2026-02-02 23:13:28 +09:00

6.9 KiB
Raw Blame History

BatchuKis API Specification

이 문서는 프론트엔드와 백엔드 간의 통신을 위한 API 인터페이스 명세서입니다.

1. 설정 및 시스템 (Settings & System)

1.1 전체 설정 (Global Settings)

  • URL: GET /api/settings / POST /api/settings
  • Description: KIS API 키, 서비스 활성화 여부 등 전체 앱의 사용자 설정을 관리합니다.
  • Body (POST): ApiSettings object.

1.2 AI 엔진 관리 (AI Configurations)

  • URL: GET /api/settings/ai-configs / POST /api/settings/ai-configs
  • Description: 사용자 지정 AI 프로필(Gemini, Ollama 등) 목록을 관리합니다.
  • PUT/DELETE: PUT /api/settings/ai-configs/:id, DELETE /api/settings/ai-configs/:id

2. 계좌 및 자산 (Account & Portfolio)

2.1 계좌 요약 (Account Summary)

  • URL: GET /api/account/summary
  • Response: { "totalAssets": number, "buyingPower": number, "dailyProfit": number, "dailyProfitRate": number }

2.2 보유 자산 (Holdings)

  • URL: GET /api/holdings
  • Query: ?market=Domestic|Overseas
  • Response: HoldingItem[]

3. 관심종목 관리 (Watchlist)

3.1 그룹 관리 (Watchlist Groups)

  • URL: GET /api/watchlists / POST /api/watchlists
  • PUT/DELETE: PUT /api/watchlists/:id (그룹명 수정 및 종목 코드 리스트 업데이트), DELETE /api/watchlists/:id
  • Response: WatchlistGroup[]

4. 종목 및 시세 (Market Data)

4.1 종목 검색 및 마스터 (Stock Discovery)

  • URL: GET /api/stocks/search?query=...
  • URL: GET /api/kis/master-stocks?market=... (로컬 검색성능을 위한 대량 데이터 수동 동기화용)

4.2 시세 및 차트 (Quotes & Charts)

  • URL: GET /api/kis/quotes/:code (현재가 및 호가)
  • URL: GET /api/kis/ticks/:code?limit=... (차트용 틱 데이터)

4.3 발견 및 랭킹 (Market Discovery)

  • URL: GET /api/discovery/rankings?market=...&category=... (거래량, 상승률 등)

5. 뉴스 및 AI 분석 (News & AI Intelligence)

5.1 뉴스 스크랩 (News Feed)

  • URL: GET /api/news?query=...
  • Description: 네이버 API 등을 통해 실시간 금융 뉴스를 가져옵니다.

5.2 AI 뉴스 분석 (AI News Briefing)

  • URL: POST /api/ai/analyze-news
  • Body: { "aiConfigId": string, "headlines": string[] }
  • Response: { "report": string, "sentimentMetadata": any[] }

5.3 AI 종목 분석 (AI Stock Deep-Dive)

  • URL: POST /api/ai/analyze-stock
  • Body: { "aiConfigId": string, "stockCode": string, "context": any }

6. 주문 및 거래 (Trading & History)

6.1 수동 주문 (Manual Trading)

  • URL: POST /api/trade/order
  • Body: { "code": string, "type": "BUY"|"SELL", "quantity": number, "price": number, "orderType": "MARKET"|"LIMIT" }

6.2 예약/감시 주문 (Reserved Orders)

  • URL: GET /api/reserved-orders / POST /api/reserved-orders
  • DELETE: DELETE /api/reserved-orders/:id

6.3 자동매매 전략 (Auto Trading)

  • URL: GET /api/auto-trades / POST /api/auto-trades
  • Description: AI 전략 로봇 등록 및 상태 관리.

6.4 거래 기록 (Execution History)

  • URL: GET /api/history/orders
  • Query: ?page=...&limit=...&stockCode=...&startDate=...&endDate=...
  • Response: TradeOrder[]

7. 실시간 데이터 (Real-time Data - WebSockets)

백엔드는 KIS 실시간 시세 서버와 웹소켓을 유지하며, 프론트엔드에게 가공된 데이터를 스트리밍합니다.

7.1 실시간 체결가 (Real-time Price)

  • Topic: /ws/market/price/:code
  • Data: 현재가, 등락률, 거래량 등

7.2 실시간 주문 알림 (Order Notifications)

  • Topic: /ws/trade/events
  • Data: 자신의 계좌에서 발생하는 체결 알림, 미체결 취소 알림 등

8. 내부 서비스 인터페이스 (Internal Engine Services)

프론트엔드에 노출되지 않지만, 백엔드 엔진 내부 모듈 간의 협업 또는 외부 API 래핑을 위한 서비스 인터페이스입니다.

8.1 BrokerageInterface (증권사 서버 통신)

  • PlaceOrder(stockCode, side, qty, price, type): KIS 서버로 최종 주문 패킷 전송. (Returns: orderNo)
  • GetRealtimeApprovalKey(): 실시간 웹소켓 접속용 Approval Key 발급 및 갱신.
  • FetchHoldings(): 계좌 내 전 종목 보유 및 평단가 수집.

8.2 RealtimeManager (웹소켓 데이터 관리)

  • AddSubscription(code, source): 구독 요청 (source: 'HOLDING' | 'FRONTEND').
    • Logic: 해당 종목의 Reference Count 증가. Count == 1이 되는 순간 KIS 웹소켓 구독 전송.
  • RemoveSubscription(code, source): 구독 해제 요청.
    • Logic: Reference Count 감소. Count == 0이 되면 KIS 웹소켓 구독 해제(자원 절약).
  • OnStreamReceived(data): 수신된 로우 데이터를 파싱하여 필요 모듈(AutoTrader, FrontendWS)로 브로드캐스팅.

8.3 AiOrchestrator (AI 엔진 처리 핸들러)

  • RequestAnalysis(aiConfigId, prompt): 지정된 엔진 프로필을 사용하여 원격 AI API 호출.
  • ApplySentiment(newsId, result): 분석된 심리 결과를 DB(news_cache)에 업데이트 및 프론트 전송.

8.4 Scheduler (배치 작업 제어)

  • SyncMasterStocks(): 매일 새벽 종목 명칭 및 코드 리스트 동기화.
  • PersistMarketDataCache(): 메모리에 수신된 실시간 현재가를 주기적으로 DB에 영구 저장 (API 호출 없음).
  • RefreshNaverNews(): 10분 단위 키워드별 뉴스 스크랩 및 분석 트리거.

9. KIS API Integration Map (증권사 연동 맵)

BrokerageInterface가 실제 호출해야 할 한국투자증권(KIS) Open API 엔드포인트 매핑입니다.

Category Internal Function Domestic API (국내) Overseas API (해외) Note
Auth GetAuthToken /oauth2/tokenP (Common) OAuth2 Access Token
Auth GetWebsocketKey /oauth2/approval (Common) WebSocket Approval Key
Order PlaceOrder /uapi/domestic-stock/v1/trading/order-cash /uapi/overseas-stock/v1/trading/order 현금 매수/매도
Order ModifyOrder /uapi/domestic-stock/v1/trading/order-rvsecncl /uapi/overseas-stock/v1/trading/order-rvsecncl 정정/취소
Price GetCurrentPrice /uapi/domestic-stock/v1/quotations/inquire-price /uapi/overseas-stock/v1/quotations/price 현재가 조회
Price GetDailyChart /uapi/domestic-stock/v1/quotations/inquire-daily-price /uapi/overseas-stock/v1/quotations/daily-price 일봉 데이터
Balance FetchHoldings /uapi/domestic-stock/v1/trading/inquire-balance /uapi/overseas-stock/v1/trading/inquire-balance 잔고 조회
Socket RealtimePrice /tryit/H0STCNT0 (H0STCNT0) /tryit/HDFSCNT0 (HDFSCNT0) 실시간 체결가
Reference in New Issue View Git Blame Copy Permalink