corp_code부터 filing 원문까지 DART 수집 파이프라인 설계

OpenDART를 처음 붙일 때 많은 사람이 같은 실수를 한다. 필요한 endpoint를 하나씩 호출하면 결국 수집기가 완성될 것이라고 생각하는 것이다. 처음 며칠은 실제로 그렇게 보인다. corp_code를 받고, 공시검색을 하고, 재무 API를 호출하면 뭔가 돌아가는 것처럼 보이기 때문이다.

하지만 운영 단계로 넘어가면 곧 흔들린다.

• 회사 식별자와 문서 식별자가 섞인다
• 검색 결과에서 어떤 문서를 기준으로 잡아야 할지 애매해진다
• JSON 숫자는 모였는데 원문과 연결이 끊긴다
• 정정공시가 나오면 기존 데이터를 어떻게 교체할지 불분명해진다

즉 좋은 DART 수집기는 API 호출 모음이 아니라 식별자 -> 검색 -> 기준 문서 선택 -> rcept_no 추적 -> 원문 파일 연결 -> 정정 재결합 구조를 가져야 한다.

이 글은 바로 그 바깥 프레임을 정리한다. 이벤트 감시는 OpenDART로 주요사항보고서 읽는 법, 재무/XBRL/주석 쪽 깊은 레이어는 XBRL 재무제표 원문과 주석 다운로드 파이프라인에서 다뤘다. 이번 글은 그 둘을 묶는 수집기 설계의 중심 축에 집중한다.

왜 corp_code가 파이프라인의 시작점인가

종목코드는 사람이 익숙하게 보는 식별자다. 하지만 OpenDART 수집기 관점에서 첫 기준점은 종목코드가 아니라 corp_code다. 공식 개발가이드도 고유번호 파일을 먼저 받아 회사 식별 테이블을 구성하는 흐름을 전제로 한다.

문제는 많은 수집기가 이 단계를 너무 가볍게 본다는 점이다. 종목코드만 저장해도 당장은 검색이 된다. 하지만 회사 메타데이터를 안정적으로 관리하려면 결국 corp_code가 필요해진다.

실전에서는 네 축을 분리해서 들고 가는 편이 가장 안전하다.

이 구조가 없으면 나중에 두 가지 문제가 생긴다. 첫째, 회사 단위 스케줄링은 되는데 문서 단위 추적이 끊긴다. 둘째, 문서 데이터는 모였는데 어떤 회사의 어떤 버전인지 설명이 사라진다.

좋은 수집기의 첫 단계는 단순하다.

1. 고유번호 파일에서 회사 마스터를 만든다.
2. 종목코드, 회사명, corp_code를 한 테이블에 묶는다.
3. 이후 모든 OpenDART 호출은 corp_code 기준으로 진행한다.

이 단계를 먼저 해두면 OpenDART, 솔직한 리뷰에서 설명한 API 범위 차이도 훨씬 명확해진다. 회사 식별이 안정되면 검색, 이벤트, 재무, 원문 다운로드를 같은 파이프라인 안에서 연결할 수 있기 때문이다.

검색 결과에서 기준 문서를 고르는 법

회사 식별이 끝났다고 바로 데이터를 저장하면 안 된다. 그다음 병목은 어떤 문서를 기준으로 잡을 것인가다.

초보 수집기는 보통 최신 문서 한 건만 잡는다. 하지만 실전에서는 “최신”보다 질문에 맞는 기준 문서가 더 중요하다. 연간 재무 구조를 보고 싶으면 사업보고서, 분기 추적이 목적이면 분기보고서, 사건 탐지가 목적이면 주요사항보고서를 먼저 잡아야 한다.

가장 단순한 기준표는 아래처럼 잡을 수 있다.

여기서 중요한 것은 검색 결과 자체를 저장 레이어로 바꾸는 것이다. 좋은 수집기는 검색 결과에서 아래 정보를 함께 남긴다.

• corp_code
• 보고서명
• 제출일
• 보고서 유형
• rcept_no
• 정정 여부 또는 최종본 판단 정보

이 정보가 남아야 나중에 “왜 이 문서를 기준으로 썼는가”를 설명할 수 있다. 특히 동일한 연도에도 사업보고서, 정정사업보고서, 첨부정정이 섞여 나올 수 있기 때문에 기준 문서 선택 규칙을 코드로 고정해두는 편이 낫다.

rcept_no를 중심으로 원문 파일을 추적하는 구조

corp_code가 회사 식별자라면, rcept_no는 문서 식별자다. 수집기가 흔들리는 가장 큰 이유 중 하나는 이 번호를 중간 단계에서 버리는 것이다.

예를 들어 재무 API 결과만 남기고 rcept_no를 잃어버리면 곧 아래 문제가 생긴다.

• 어떤 보고서를 기준으로 숫자를 받았는지 모른다
• 원문 HTML이나 첨부 파일을 다시 열기 어렵다
• XBRL 원문과 JSON 숫자를 연결하기 힘들다
• 정정공시가 나오면 무엇을 교체해야 할지 모른다

그래서 설계는 단순해야 한다. 모든 하위 레이어는 corp_code + rcept_no 쌍 위에 올라가야 한다.

이 구조를 잡아두면 XBRL 재무제표 원문과 주석 다운로드 파이프라인에서 설명한 XBRL/주석 레이어를 자연스럽게 파이프라인 뒤쪽에 붙일 수 있다. 반대로 rcept_no가 없다면 XBRL과 주석은 단순 파일 뭉치가 되고, 운영 가치가 급격히 떨어진다.

실전에서는 “먼저 검색 결과를 문서 원장으로 만들고, 그 원장 아래에 원문/XBRL/주석을 매단다”라고 생각하면 빠르다. JSON API는 빠른 조회 레이어일 뿐, 문서 추적의 중심축은 아니다.

정정공시를 어떻게 다시 묶을까

정정공시는 수집기를 가장 쉽게 망가뜨리는 영역이다. 같은 회사, 같은 회계연도, 비슷한 보고서명이 반복되기 때문에 단순 overwrite 방식으로는 거의 항상 문제가 생긴다.

실전에서는 아래 세 가지를 같이 저장하는 편이 안전하다.

좋은 규칙은 “정정이 나오면 최신 것만 남긴다”가 아니다. 더 정확한 규칙은 최신 유효본을 운영 뷰로 채택하되, 이전 문서와 연결 관계는 남긴다다.

이 차이가 중요하다.

• 운영 API나 대시보드는 최신 유효본만 써도 된다
• 감사용 로그나 품질 점검은 이전 버전 비교가 필요하다
• 숫자가 왜 바뀌었는지 설명하려면 문서 체인이 남아 있어야 한다

정정공시는 숫자 문제만의 영역도 아니다. 제출기한, 첨부 구조, 계약 조건, 공시 제목까지 바뀔 수 있다. 그래서 “정정이 나왔는가”를 검색 결과 레이어에서 먼저 잡고, 그다음 원문/XBRL/이벤트 레이어를 다시 연결하는 편이 안전하다.

기업 단위 watch와 batch 설계

수집기는 보통 두 종류의 운영 흐름을 동시에 가져간다.

1. 특정 회사나 관심 목록을 자주 보는 watch
2. 전체 종목군을 주기적으로 도는 batch

둘을 같은 설계로 밀어붙이면 성능과 품질이 같이 흔들린다.

이때 OpenDART로 주요사항보고서 읽는 법은 watch 흐름에 가깝고, XBRL 재무제표 원문과 주석 다운로드 파이프라인은 batch 뒤쪽의 심화 레이어에 가깝다. 031의 역할은 그 둘을 같은 지도 안에 놓는 것이다.

실전 운영 규칙은 아래처럼 단순화할 수 있다.

• watch는 빠른 탐지와 우선순위 판별이 목표다
• batch는 누락 없이 기준 문서를 정리하는 것이 목표다
• 원문/XBRL/주석은 항상 후순위의 무거운 레이어로 본다
• 모든 단계는 corp_code와 rcept_no를 잃지 않는 방향으로 설계한다

이 구조를 지키면 “먼저 가볍게 감지하고, 필요한 문서만 깊게 내려가는” 비용 분리도 가능해진다.

실패하는 수집기의 공통 패턴

대부분의 실패는 고급 알고리즘이 아니라 기본 키 설계에서 나온다.

1. corp_code를 별도 마스터로 관리하지 않는다

처음에는 편하지만, 회사 식별과 문서 추적이 섞이기 시작한다.

2. 검색 결과를 일회성 응답으로만 쓴다

검색은 조회 도구이면서 동시에 기준 문서 원장이다. 저장하지 않으면 나중에 선택 근거가 사라진다.

3. rcept_no를 숫자 API 뒤에서 버린다

그 순간 원문, XBRL, 정정공시, 첨부 파일이 전부 느슨해진다.

4. 정정공시를 단순 overwrite로 처리한다

운영 뷰는 최신본을 쓸 수 있어도, 문서 체인은 남겨야 한다.

5. 모든 회사에 무거운 다운로드를 한 번에 태운다

검색과 기준 문서 정리 없이 원문/XBRL/주석을 먼저 받으면 비용만 커지고 품질은 오히려 떨어진다.

결국 좋은 파이프라인은 복잡한 기술보다 무엇을 먼저 고정해야 하는가를 분명히 아는 구조다. DART에서는 그 답이 대체로 corp_code -> 검색 결과 -> rcept_no -> 원문/XBRL -> 정정 재결합 순서다.

체크리스트

• 고유번호 파일을 기준으로 corp_code 마스터를 먼저 만들었는가
• 검색 결과를 기준 문서 원장처럼 저장하고 있는가
• 모든 하위 레이어가 rcept_no를 끝까지 들고 가는가
• 원문, XBRL, 주석 파일이 같은 문서 축에 연결되는가
• 정정공시가 나오면 최신 유효본과 이전 버전 체인을 같이 남기는가
• watch와 batch를 같은 비용 구조로 처리하지 않는가

FAQ

종목코드만 저장하면 안 되나

사용자 입력 단계에서는 가능하지만, OpenDART 파이프라인의 기준 식별자는 corp_code다. 회사 마스터를 안정적으로 운영하려면 결국 corp_code가 필요하다.

rcept_no만 잘 저장하면 원문과 XBRL은 자동으로 해결되나

자동으로 해결되지는 않는다. 다만 rcept_no가 있어야 공시 원문, XBRL, 주석 파일을 같은 문서 축으로 연결할 수 있다.

정정공시는 최신 문서 하나만 남기면 충분한가

운영 화면만 보면 그럴 수 있다. 하지만 품질 검증과 변경 추적을 하려면 이전 문서와의 연결 관계도 함께 남겨야 한다.

watch와 batch를 왜 굳이 나눠야 하나

목표가 다르기 때문이다. watch는 빠른 탐지와 우선순위 판별이 중요하고, batch는 누락 없는 문서 정리와 안정적 동기화가 중요하다.

031을 읽은 뒤에는 무엇을 붙이면 좋은가

이벤트 감시를 강화하려면 OpenDART로 주요사항보고서 읽는 법, 재무/XBRL/주석 쪽을 깊게 붙이려면 XBRL 재무제표 원문과 주석 다운로드 파이프라인, API 범위 자체를 먼저 정리하려면 OpenDART, 솔직한 리뷰를 이어서 보는 편이 좋다.

참고한 공식 자료

• OpenDART 개발가이드 - 고유번호
• OpenDART 개발가이드 - 공시서류원본파일
• OpenDART 개발가이드 메인
• DART 소개 - 보고서정보