dart-box - OpenDART API 프록시

핵심 기능

⚡

다층 캐싱 시스템

OpenDART API 호출을 95% 이상 감소하고, 캐시 시 430배 빠른 응답 속도 제공

🤖

AI 에이전트 친화적

구조화된 택소노미 정보와 한글/영문 라벨로 재무 분석 자동화 지원

🔒

완전한 타입 안전성

Litestar + msgspec.Struct로 신뢰할 수 있는 계약과 초고속 직렬화

💾

유연한 스토리지

로컬 파일 시스템과 S3 간 유연한 전환 지원

API 엔드포인트

Method	Endpoint	설명
GET	`/health`	서비스 상태 확인
GET	`/krx/{stock_code}/company`	회사 기본 정보 조회
GET	`/krx/{stock_code}/filings`	공시 목록 조회 (날짜 범위, 페이지네이션 지원)
GET	`/krx/{stock_code}/filings/{rcept_no}`	공시 문서 상세 조회 (ZIP 해제 결과)
GET	`/krx/.../filings/.../{reprt_code}/xbrl` Summary	XBRL 핵심 지표 + 라벨 목록 (~17KB) AI 에이전트 추천
GET	`/krx/.../filings/.../{reprt_code}/xbrl/filter` Filter	XBRL 필터링 (label_ko, prefix, name, sj_div) 특정 계정과목 조회
GET	`/krx/.../filings/.../{reprt_code}/xbrl/raw` Raw	전체 XBRL facts (~2MB) 완전한 데이터 분석용

빠른 시작

1. 서비스 상태 확인

curl http://localhost:8000/health

2. 회사 정보 조회

curl "http://localhost:8000/krx/005930/company"

3. 공시 목록 조회

curl "http://localhost:8000/krx/005930/filings?from=2024-01-01"

4. XBRL 재무 데이터 조회 (Summary)

curl "http://localhost:8000/krx/005930/filings/.../Q2/xbrl"

핵심 지표 + 400+개 라벨 목록 (~17KB)

5. XBRL 필터링 (Filter)

curl "http://localhost:8000/krx/005930/filings/.../Q2/xbrl/filter?label_ko=자산총계"

특정 계정과목만 조회

6. OpenAPI 문서 (ReDoc)

curl "http://localhost:8000/schema/redoc"

또는 Swagger UI: /schema/swagger

AI 에이전트 활용 예시

구조화된 데이터로 재무 분석 자동화

질문: "삼성전자의 2024년 상반기 실적은 어땠어?"

에이전트가 자동으로 탐색하고 답변을 생성합니다

회사 식별
공시 검색
문서 확보
재무 분석 (다단계)
종합 답변

📊 XBRL Summary 구조

{
  "available_labels": ["매출액", ...],
  "income_statement": {
    "revenue": {
      "label_ko": "수익 합계",
      "value": 145983903000000
    }
  },
  "balance_sheet": { ... },
  "cash_flow": { ... }
}

✅ 핵심 지표 + 400+개 라벨

🔍 다단계 탐색 전략

1. Summary로 전체 개요 확인

2. Filter로 상세 분석

3. Raw는 필요시만

✅ 99%+ 데이터 절약

🔍 한글 라벨 검색

# 한글 계정과목명으로 검색
for fact in facts:
    if fact["label_ko"] == "매출액":
        print(f'{fact["value"]:,}원')

    if "이익" in fact["label_ko"]:
        profits.append(fact)

초기 설정

최초 1회

1. corpCode 인덱스 갱신

uv run litestar --app dart_box.app:create_app refresh-corp-index

회사 코드 인덱스를 최신으로 업데이트합니다

2. 택소노미 라벨 갱신

uv run litestar --app dart_box.app:create_app refresh-taxonomy

XBRL 재무 데이터에 한글/영문 라벨 제공 (6개월마다 갱신 권장)

추가 정보

자세한 내용은 GitHub 저장소를 확인하세요