opendart-excel

OpenDART 재무제표 Excel 생성 스킬

사용자 요청 예: "삼성전자 2022년 연결재무제표 엑셀로 만들어줘"

원문 처리(다운로드·파싱·Excel 생성·검증)는 MCP 서버가 수행한다. 이 스킬은 접수번호 1건을 찾고, 서버가 반환한 후보 제목 목록에서 문서를 선택한 뒤 결과 파일을 전달한다.

사용 흐름

1. 요청 파싱

• 추출: 회사명, 사업연도, 기간(연간/반기/분기), 범위(연결 consolidated / 별도 separate).
• 회사명이나 사업연도가 없거나 모호하면 사용자에게 확인한다.
• 회사 별칭을 정식 회사명으로 확정할 수 없으면 사용자에게 확인한다.
• 기간이나 연결/별도가 모호하면 사용자에게 확인한다. 임의로 기본값을 선택하지 말 것. 연도만 말했으면 **사업보고서(연간)**로 처리한다.
• Excel 요청인지 불명확하면 출력 형식을 확인한다.
• 여러 항목이 모호하면 한 번에 질문하고, 명확한 항목은 다시 묻지 않는다.

2. corp_code 확인

get_corp_codes로 회사명 또는 종목코드를 검색해 corp_code를 얻는다. 후보가 여러 개면 사용자에게 확인한다.

3. 접수번호 결정

search_disclosures로 요청 기간의 정기보고서를 찾는다. pblntf_ty="A"로 검색하고 report_nm을 직접 대조해 연간·반기·분기를 구분한다.

• 같은 기간 공시가 여러 건이면([기재정정] 등) 최신 1건이면 된다. 정정본은 본문만 재제출하고 첨부는 원본에 남지만, 다음 단계가 공시 계열 전체의 첨부를 돌려주므로 원본 번호를 따로 모을 필요가 없다.
• 결산월이 12월이 아니면 report_nm의 연도가 사업연도와 어긋난다. 3월 결산 회사의 2024 사업연도 3분기는 분기보고서 (2023.12)이다. 확신이 없으면 get_company_info로 acc_mt를 확인하고, 검색 결과 제목을 직접 대조해 고른다.
• 검색 결과 0건이면: pblntf_ty="F"(외부감사관련)로 재검색한다 — 비상장 외감법인은 정기보고서 없이 감사보고서만 단독 공시된다.
• 그래도 0건이면 임의로 다른 연도 공시를 대체하지 말고, 사용자에게 사유 후보와 함께 안내하고 다른 기간을 쓸지 확인한다: 제출 시기 미도래(사업보고서는 결산 후 90일 이내 제출), 신규상장(상장 전 연도), 미제출·제출지연 등.

4. 후보 조회와 선택

list_financial_document_candidates(rcept_no="20250814003075", corp_code="00126380")

반환값에는 candidate_id, rcept_no, date, title만 있으며 원문은 없다. 사용자 요청과 비교해 하나를 고른다.

• 연간: 감사보고서 / 연결감사보고서
• 반기·분기: 제목에 검토보고서가 포함된 문서
• 연결: 제목에 연결이 있는 문서. 별도: 없는 문서
• 같은 종류가 여럿이면 date가 늦은 것
• 감사의감사보고서, 내부회계관리제도운영보고서, 정관, 영업보고서 등 목적이 다른 문서는 제외
• 서버는 공시 계열의 ZIP XML을 먼저 검사하고, OpenDART ZIP에서 빠진 반기·분기 첨부만 DART 내부 문서 조회로 보완한다.
• 기본 호출은 감사·검토보고서만 반환한다. 첨부가 실제로 없으면 confirmation_required가 나온다.
• 후보의 rcept_no가 3단계에서 넘긴 번호와 다를 수 있다. 정정 공시의 첨부가 원본 공시에 남아 있는 정상적인 경우다. candidate_id를 그대로 쓰면 된다.

5. 워크북 생성

create_financial_workbook(
    candidate_id="<선택한 candidate_id>",
    scope="consolidated",
    output_dir="<현재 작업의 쓰기 가능한 워크스페이스 경로>",
    output_name="SK하이닉스_2024_연결재무제표.xlsx"
)