KisStock/backend/api.md

BatchuKis API Specification

이 문서는 프론트엔드와 백엔드 간의 통신을 위한 API 인터페이스 명세서입니다. 데이터 모델(JSON 구조)의 상세 정의는 models.md를 참조하십시오.

---

1. 설정 및 시스템 (Settings)

1.1 전체 설정 가져오기

• URL: GET /api/settings
• Response: ApiSettings (See models.md)

1.2 전체 설정 저장하기

• URL: POST /api/settings
• Body: ApiSettings
• Response: { "success": boolean, "message": string }

1.3 AI 엔진 풀(Pool) 관리

1.3.1 등록된 AI 엔진 목록 조회

• URL: GET /api/settings/ai-configs
• Response: AiConfig[]

1.3.2 신규 AI 엔진 추가

• URL: POST /api/settings/ai-configs
• Body: Omit<AiConfig, 'id'>
• Response: { "id": string, "success": true }

---

2. 자산 및 잔고 (Portfolio)

2.1 보유 종목 리스트

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

2.2 계좌 요약 (자산/예수금)

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

---

3. 자동매매 전략 (Auto Trading)

3.1 로봇 리스트 조회

• URL: GET /api/auto-trades
• Response: AutoTradeConfig[]

3.2 로봇 등록/수정

• URL: POST /api/auto-trades
• Body: AutoTradeConfig (ID가 없으면 생성, 있으면 수정)
• Response: { "id": string }

---

4. 실시간 감시 주문 (Reserved Orders)

4.1 감시 목록 조회

• URL: GET /api/reserved-orders
• Response: ReservedOrder[]

4.2 감시 등록

• URL: POST /api/reserved-orders
• Body: Omit<ReservedOrder, 'id' | 'status' | 'createdAt'>
• Response: { "id": string }

---

5. 종목 및 시세 (Market Data & Discovery)

5.1 마스터 종목 리스트 (동기화용)

• URL: GET /api/kis/master-stocks
• Query: ?market=Domestic|Overseas
• Response: StockItem[]

5.2 개별 종목 시세 차트 데이터

• URL: GET /api/kis/ticks/:code
• Query: ?limit=100
• Response: StockTick[]

5.3 [NEW] 종목 발굴 랭킹 데이터

• URL: GET /api/discovery/rankings
• Query: ?market=Domestic|Overseas&category=VOLUME|VALUE|GAIN|LOSS|FOREIGN_BUY|INSTITUTION_BUY
• Response: DiscoveryRankingResponse (See models.md)
• 설명: 토스증권 스타일의 발굴 페이지에 데이터를 공급합니다. 거래비율(buyRatio/sellRatio) 및 수급 데이터가 포함됩니다.

5.4 [NEW] 실시간 커뮤니티 심리 요약 (AI 전용)

• URL: GET /api/discovery/sentiment/:code
• Response: { "insights": string[], "sentimentScore": number }
• 설명: 특정 종목에 대한 AI의 실시간 커뮤니티/뉴스 요약 정보를 반환합니다.