mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

hon2be ca6d560227

✨ feat: add k-dart skill for DART OpenAPI financial disclosures (#147 )

* ✨ feat: add k-dart skill for DART OpenAPI financial disclosures

금감원 전자공시시스템(DART) 14개 endpoint 조회 스킬 추가.
공시검색, 기업개황, 재무제표, 배당, 증자/감자, 전환사채, 소송 등.
API_K_DART 환경변수로 직접 호출하며 프록시 불필요.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 📝 docs(k-dart): remove redundant korean-stock-search dependency

corpCode.xml 자체에 회사명·종목코드·고유번호가 모두 포함되어 있으므로
korean-stock-search 스킬 연계 절차 제거

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 📝 docs: add k-dart to README feature table

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 📝 docs: add k-dart feature guide and fix README link format

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* 🐛 fix(k-dart): correct status code 013, remove invalid corp_name filter, update daily limit

3개 critical 정확성 오류 수정:

1. 상태코드 013은 "조회된 데이터 없음"이며 "접근 권한 없음"이 아님 (012=접근 불가 IP).
   상태코드 표를 공식 명세 기준으로 재정리하고 누락된 014/021 코드 추가.
2. list.json은 corp_name 파라미터를 검색 필터로 지원하지 않음. SKILL.md의
   잘못된 진술과 corp_name을 사용한 misleading example을 제거하고, corp_code
   확보 절차를 거치도록 명시.
3. DART 일일 한도는 키당 10,000건이 아닌 20,000건이며 분당 약 1,000회
   throttle도 별도로 존재함. SKILL.md 및 docs/features/k-dart.md 모두 정정.

추가로 status: "013" 발생 시 사용자 안내 정책을 Response policy에 추가하고,
오픈API 이용현황 페이지 링크를 Notes에 추가함.

* 🐛 fix(k-dart): correct pifricDecsn endpoint, list.json corp_code optional, add empSttus, soften throttle claim

Codex adversarial review에서 식별된 4건의 추가 정확성 이슈 수정:

1. endpoint #8 유무상증자 결정이 잘못된 API에 연결됨. piicDecsn.json은
   유상증자 결정 (apiId=2020023)이며, 유무상증자 결정은 pifricDecsn.json
   (apiId=2020025)이 맞음. endpoint를 정정하고 piicDecsn (유상증자) 및
   fricDecsn (무상증자)와의 차이를 주의문으로 추가.

2. list.json의 corp_code 는 사실 선택사항이며, 미지정 시 검색 기간이
   3개월 이내로 제한될 뿐임. 이전 commit의 "corp_code 필수" 표현을
   정정하고, 두 가지 호출 패턴(corp_code 지정/미지정)을 Example
   requests에 모두 추가.

3. "분당 약 1,000회 throttle"은 공식 공개 가이드에 근거 없음
   (apiUsageStatusView.do 는 로그인 게이트). 공식 가이드가 명시한
   "일반적으로 20,000건 이상 요청 시 020 발생"만 유지하고 분당
   throttle 주장을 제거. 상태코드 표·Response policy도 일관되게 정리.

4. docs/features/k-dart.md가 "직원 현황" 기능을 광고하지만 SKILL.md
   에는 endpoint가 누락됨. empSttus.json (apiGrpCd=DS002,
   apiId=2019011)을 endpoint #8로 추가하고 example도 함께 등록.
   기존 endpoint 9~14는 10~15로 재번호.

* 🐛 fix(k-dart): align list.json signature and 020 caveat with official spec

Codex 2nd-round review에서 식별된 정확성 이슈 2건 수정:

1) list.json 요청 인자 signature가 공식 가이드(DS001/2019001)와 정확히
   일치하도록 재작성. crtfc_key 외 모든 파라미터가 선택사항임을 분명히
   하고, 각 파라미터의 default 동작과 pblntf_ty 값(A/B/C/D/E)도 명시.
   "corp_code 지정 시 기간 제한 없음" 표현은 공식 가이드가 보장하지
   않으므로 제거. corp_name이 공식 파라미터에 "존재하지 않는다"는
   사실로 수정 (이전: "지원하지 않는다").
   "corp_code 미지정 시 3개월 제한"은 외부 사용 사례에서 관찰된
   동작으로 약화 (공식 가이드에 별도 명시 없음).

2) 020 (요청 제한 초과) 안내가 일일 20,000건 cap 으로 너무 단정적
   해석되던 표현을 공식 메시지 그대로 보존: "일반적으로 20,000건
   이상 요청 시 발생하며, 키별로 별도 한도가 설정된 경우 다른
   임계치에서도 동일 코드가 반환될 수 있음". 상태코드 표·Response
   policy·Notes·docs/features/k-dart.md 모두 일관되게 정정.

* 🐛 fix(k-dart): mirror official Korean DS001/2019001 list.json spec exactly

Codex 3rd-round review에서 식별된 잔존 정확성 이슈 수정.

영어 가이드(DE001/AE00001)와 한국어 가이드(DS001/2019001)가 list.json
필수여부에서 다르게 표기되어 있어 이전 commit이 영어 가이드를 따랐으나,
한국어 공식 가이드를 직접 확인한 결과(opendart.fss.or.kr/guide/detail.do
?apiGrpCd=DS001&apiId=2019001) 다음이 한국어 공식 spec임을 확인:

- bgn_de, end_de는 Y(필수) (기본값은 명시되어 있으나 표기상 필수)
- corp_code 미지정 시 검색기간 3개월 제한은 공식 spec에 명시된 룰
  (외부 사용 사례 관찰이 아님)
- pblntf_ty는 A~J 전체 enum (정기공시/주요사항보고/발행공시/지분공시/
  기타공시/외부감사관련/펀드공시/자산유동화/거래소공시/공정위공시)
- page_count 기본값 10, 최대값 100
- corp_cls 복수 조건 불가
- last_reprt_at, sort, sort_mth 각 default 동작 명시

list.json 섹션을 공식 가이드 표와 1:1 일치하는 마크다운 표로 재작성.
3개월 제한 표현을 "외부 사례"에서 "공식 spec"으로 정정. Response policy
에 잔존하던 corp_name "지원하지 않는다" 표현도 "공식 파라미터에 존재하지
않는다"로 통일하여 #1 endpoint 섹션과 일관성 확보. docs/features/k-dart.md
도 동일하게 정정.

* 🐛 fix(k-dart): make list.json table 1:1 mirror of DS001/2019001 + unify corp_name wording

Codex 4th-round review가 식별한 잔존 이슈 2건 마무리.

1) list.json 파라미터 표를 공식 가이드 행 순서 그대로(crtfc_key,
   corp_code, bgn_de, end_de, last_reprt_at, pblntf_ty,
   pblntf_detail_ty, corp_cls, sort, sort_mth, page_no, page_count)
   재정리하고 공식 표의 모든 컬럼(요청키/명칭/타입/필수여부/값설명)을
   포함. page_no(1~n) / page_count(1~100, 기본10, 최대100) 범위
   값을 공식 표 그대로 표기. pblntf_detail_ty 값설명도 공식 표
   그대로 "(※ 상세 유형 참조: pblntf_detail_ty)"로 두고, 자주 쓰는
   코드 예시(A001/B001/F001/D001)는 표 아래 별도 단락으로 분리해
   표의 1:1 mirror 성격을 유지.

2) corp_name 관련 canonical 문장 "공식 요청 파라미터 표에
   corp_name 은 존재하지 않는다" 를 다음 3곳 모두 verbatim 일치
   시킴 (이전 commit에서 SKILL.md는 '않는다', docs/features는
   '않음' 으로 어미 차이가 잔존했음):
   - k-dart/SKILL.md #1 endpoint 섹션 주의문
   - k-dart/SKILL.md Response policy
   - docs/features/k-dart.md 에러/제약 섹션

* 🐛 fix(k-dart): unify corp_name canonical sentence verbatim + soften list.json table claim

Codex 5th-round review가 식별한 fine-grained 이슈 마무리.

1) corp_name canonical 문장을 self-contained 형태로 재작성하여
   3곳 모두 byte-for-byte 동일하게 통일:
   "DART OpenAPI list.json 의 공식 요청 파라미터 표에 corp_name 은
   존재하지 않는다."
   - SKILL.md #1 endpoint 섹션 주의문
   - SKILL.md Response policy
   - docs/features/k-dart.md 에러/제약 섹션
   이전에는 SKILL.md는 "위 공식 요청 파라미터 표에"로 docs/features는
   "list.json 공식 요청 파라미터 표에" 로 prefix가 달라 verbatim
   일치하지 않았음.

2) list.json 표 헤더 문구를 "공식 가이드 표를 그대로 옮긴 것"에서
   "공식 가이드 요청 인자 정리 (필수여부·기본값·허용값은 공식 표
   기준, 식별자는 코드 폰트로 표기)"로 약화. 마크다운 backtick 등
   포매팅 차이가 "1:1 mirror" 약속과 모순되지 않게 정확히 표현.

---------

Co-authored-by: hon2be <hon2be>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Jeffrey (Dongkyu) Kim <vkehfdl1@gmail.com>

2026-04-22 12:46:42 +09:00

3.6 KiB

Raw Blame History

금감원 DART 전자공시 조회 가이드

이 기능으로 할 수 있는 일

공시검색 (최근 공시 목록, 기업별 공시 이력)
기업개황 (대표자, 업종, 주소, 결산월 등)
재무제표 (매출액, 영업이익, 당기순이익, 자산/부채/자본 등)
배당에 관한 사항
증자(감자) 현황
자기주식 취득 및 처분 현황
회계감사인의 명칭 및 감사의견
직원 현황 (부문별/성별 정규직·계약직 인원)
주요사항보고서: 유무상증자 결정, 소송, 해외 상장/상장폐지, 전환사채, 교환사채, 회사분할합병

먼저 필요한 것

API_K_DART 환경변수에 DART OpenAPI 인증키를 설정해야 한다.

키 발급: https://opendart.fss.or.kr/uss/umt/EgovMberInsertView.do

검색 예시

공시검색:

curl -fsS --get 'https://opendart.fss.or.kr/api/list.json' \
  --data-urlencode "crtfc_key=$API_K_DART" \
  --data-urlencode 'corp_code=00126380' \
  --data-urlencode 'bgn_de=20260101' \
  --data-urlencode 'end_de=20260419' \
  --data-urlencode 'page_count=5'

재무제표 (연결, 사업보고서):

curl -fsS --get 'https://opendart.fss.or.kr/api/fnlttSinglAcntAll.json' \
  --data-urlencode "crtfc_key=$API_K_DART" \
  --data-urlencode 'corp_code=00126380' \
  --data-urlencode 'bsns_year=2024' \
  --data-urlencode 'reprt_code=11011' \
  --data-urlencode 'fs_div=CFS'

응답 해석 팁

status: "000"이 정상. 그 외는 에러 (010=미등록 키, 011=사용 불가 키, 012=접근 불가 IP, 013=조회된 데이터 없음, 020=요청 제한 초과, 100=필드 오류).
재무제표의 thstrm_amount=당기, frmtrm_amount=전기, bfefrmtrm_amount=전전기.
reprt_code: 11011(사업보고서), 11012(반기), 11013(1분기), 11014(3분기).
fs_div: CFS(연결), OFS(개별).

답변 템플릿 권장

회사명 / 시장 / 종목코드
회계연도 / 보고서 종류
핵심 재무 수치 (매출, 영업이익, 순이익, 자산/부채/자본)
마지막 한 줄: 금감원 DART 공시 데이터 기준이며 투자 조언은 아닙니다.

에러/제약

API_K_DART 미설정 시 API 호출 불가 → 키 발급 안내
DART API 요청 한도: 공식 가이드(020 메시지) 기준 "일반적으로 20,000건 이상의 요청"에 대해 020 (요청 제한 초과)이 발생하며, 키별로 별도 한도가 설정된 경우 다른 임계치에서도 동일 코드가 반환될 수 있음. 분당 throttle 등 세부 수치는 공개 가이드에 명시되지 않음. 본인 키의 정확한 사용 현황은 로그인 후 OpenDART 사이트의 오픈API 이용현황 페이지에서 확인 가능.
상장폐지·오래된 비상장 법인은 데이터가 없을 수 있음
DART OpenAPI list.json 의 공식 요청 파라미터 표에 corp_name 은 존재하지 않는다. 회사명 기준으로 좁히려면 corpCode.xml ZIP을 받아 corp_code(8자리 고유번호)를 먼저 확보한 뒤 corp_code 로 호출한다. corp_code 자체는 선택사항(공식 가이드: N)이지만, 공식 spec 기준 미지정 시 bgn_de~end_de 검색 기간이 3개월 이내로 제한된다.

참고 링크

공식 DART OpenAPI: https://opendart.fss.or.kr/intro/main.do
API 목록: https://opendart.fss.or.kr/intro/infoApiList.do

3.6 KiB Raw Blame History

금감원 DART 전자공시 조회 가이드

이 기능으로 할 수 있는 일

먼저 필요한 것

추천 조회 순서

검색 예시

응답 해석 팁

답변 템플릿 권장

에러/제약

참고 링크

3.6 KiB

Raw Blame History