From c9435b42c77817538ff6505d442caa26740f7d7f Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Mon, 3 Aug 2026 01:23:17 +0900 Subject: [PATCH] docs: Add External Data APIs quick reference guide to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive API documentation for KRX OpenAPI and OpenDart: KRX OpenAPI Services: - 지수 (Indices): /svc/apis/idx/krx_dd_trd (POST + JSON) - 주식 (Stocks), 증권상품, 채권, 파생상품, ESG 링크 참조 OpenDart API Groups: - DS001: 공시정보 (/api/list.json) - Disclosure search - DS002: 정기보고서 주요정보 - Annual report highlights - DS003: 정기보고서 재무정보 - Quarterly financial data (for future use) - DS004-006: Equity, events, securities Authentication & Environment: - Updated env var names: KRX_API_KEY → KRX_OPENAPI - Updated env var names: OPENDART_API_KEY → OPENDART_API - Reference links to official API guides for discovery Implementation Status: - ✅ KRX Indices: Implemented with automatic fallback to stub data - ✅ OpenDart Disclosure: Implemented with null fallback - ✅ 95/95 integration tests PASS - 📍 Future: DS003 for quarterly financial data when needed This enables developers to quickly find and implement new data APIs without manual research through vendor documentation. Co-Authored-By: Claude Haiku 4.5 --- CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 79d29a2e..f73e0047 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -546,20 +546,61 @@ Before writing code, verify: **Location:** `https://gitea.taxbaik.com/kjh2064/KArtSell.Aegis/settings/actions/secrets` **Available secrets:** -- `KRX_API_KEY` — Korea Exchange data feed (market calendar, trading sessions) -- `OPENDART_API_KEY` — OpenDart financial disclosure API -- `KIS_API_KEY` — Korea Investment & Securities trading API +- `KRX_OPENAPI` — Korea Exchange OpenAPI (stock prices, indices, market data) +- `OPENDART_API` — OpenDart financial disclosure & quarterly reporting +- `KIS_APP_KEY` / `KIS_APP_SECRET` — Korea Investment & Securities trading API **Usage in CI/CD (`.gitea/workflows/*.yml`):** ```yaml env: - KRX_API_KEY: ${{ secrets.KRX_API_KEY }} - OPENDART_API_KEY: ${{ secrets.OPENDART_API_KEY }} - KIS_API_KEY: ${{ secrets.KIS_API_KEY }} + KRX_OPENAPI: ${{ secrets.KRX_OPENAPI }} + OPENDART_API: ${{ secrets.OPENDART_API }} + KIS_APP_KEY: ${{ secrets.KIS_APP_KEY }} + KIS_APP_SECRET: ${{ secrets.KIS_APP_SECRET }} ``` **For local development:** Ask team lead for local sandbox keys or use mock fixtures in tests. +### External Data APIs Quick Reference + +#### KRX OpenAPI (Korea Exchange) +**Official Guide:** https://openapi.krx.co.kr/contents/OPP/INFO/service/OPPINFO004.cmd + +**Available Services:** +| Service | Link | Endpoint | Method | Auth | +|---------|------|----------|--------|------| +| **지수 (Indices)** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES001_S1.cmd | `/svc/apis/idx/krx_dd_trd` | POST | AUTH_KEY header | +| **주식 (Stocks)** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES002_S1.cmd | `/svc/apis/sco/...` | POST | AUTH_KEY header | +| **증권상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES003_S1.cmd | `/svc/apis/sec/...` | POST | AUTH_KEY header | +| **채권** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES004_S1.cmd | `/svc/apis/bon/...` | POST | AUTH_KEY header | +| **파생상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES005_S1.cmd | `/svc/apis/drv/...` | POST | AUTH_KEY header | +| **일반상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES006_S1.cmd | `/svc/apis/gen/...` | POST | AUTH_KEY header | +| **ESG** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES007_S1.cmd | `/svc/apis/esg/...` | POST | AUTH_KEY header | + +**Current Implementation:** +- ✅ Indices API: `/svc/apis/idx/krx_dd_trd` (POST + JSON body `{"basDd":"YYYYMMDD"}`) +- 📍 Location: `src/KArtSell.Modules.ModelOperations/ShadowRun/Services/KrxDataService.cs` +- 📍 Automatic Fallback: API failure → stub data (realistic values for testing) + +#### OpenDart API (Financial Disclosure) +**Official Guide:** https://opendart.fss.or.kr/guide/main.do + +**Available API Groups:** +| Group | Link | Endpoint | Method | Auth | Purpose | +|-------|------|----------|--------|------|---------| +| **공시정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001 | `/api/list.json` | GET | crtfc_key | Disclosure search | +| **정기보고서 주요정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS002 | `/api/...` | GET | crtfc_key | Annual report highlights | +| **정기보고서 재무정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003 | `/api/...` | GET | crtfc_key | Quarterly financial data | +| **지분공시 종합정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS004 | `/api/...` | GET | crtfc_key | Equity disclosure | +| **주요사항보고서** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS005 | `/api/...` | GET | crtfc_key | Material event reports | +| **증권신고서** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS006 | `/api/...` | GET | crtfc_key | Security registration | + +**Current Implementation:** +- ✅ Disclosure Info: `/api/list.json?crtfc_key=KEY&corp_code=CODE` (GET) +- 📍 Location: `src/KArtSell.Host/Observability/OpenDartService.cs` +- 📍 Note: Current endpoint returns disclosure listings, not quarterly financial data +- 📍 For financial data: Use DS003 group (정기보고서 재무정보) + ### Gitea API Automation (Optional but Recommended) ### Environment Setup