DART OpenAPI 재무제표 — 백테스트가 45일 앞서 본다

이 글은 백테스트 미래참조 편향 편에서 재무데이터 한 갈래만 떼어 낸 글입니다. 가격 쪽 누수(리샘플링·지표 시프트·체결 가정)는 그쪽을 보십시오.

1. 회계기간 말일 vs 접수일 — 45일과 90일

퀀트 팩터에서 가장 조용하게 성과를 부풀리는 실수가 이것입니다. ROE·부채비율·영업이익률을 계산해 놓고 그 값을 회계기간이 끝나는 날에 붙입니다 — 2025년 3분기 재무제표라면 2025-09-30 입니다. 그런데 그 시점의 시장은 그 숫자를 모릅니다. 제출 기한이 법으로 정해져 있기 때문입니다.

즉 분기 데이터는 최대 45일, 연간 데이터는 최대 90일 늦게 나옵니다. 회계기간 말일에 붙인 팩터로 백테스트를 돌리면 그만큼의 미래를 미리 본 것이고, 실적 발표 직후의 가격 반응을 발표 전에 잡아낸 것처럼 기록됩니다.

2. OpenDART 에서 쓰는 엔드포인트 3개

금융감독원 OpenDART 의 API 그룹은 DS001 공시정보부터 DS006 증권신고서 주요정보까지 6개입니다. 팩터를 만들 때 실제로 쓰는 것은 세 개입니다.

첫 관문이 corpCode.xml 입니다. OpenDART 는 종목코드가 아니라 8자리 corp_code 로 조회하고, 이 엔드포인트는 전체 회사 목록 XML 이 든 ZIP 파일을 내려 줍니다. 상장사만 stock_code 에 6자리 종목코드가 채워져 있습니다.

# corpCode.xml — ZIP 안의 XML 을 풀어 종목코드 → corp_code 맵을 만든다
import io, zipfile, requests
import pandas as pd
import xml.etree.ElementTree as ET

CRTFC_KEY = "발급받은_40자리_인증키"   # 절대 코드에 하드코딩하지 말 것 (환경변수로)

r = requests.get("https://opendart.fss.or.kr/api/corpCode.xml",
                 params={"crtfc_key": CRTFC_KEY}, timeout=30)
zf = zipfile.ZipFile(io.BytesIO(r.content))
root = ET.fromstring(zf.read(zf.namelist()[0]).decode("utf-8"))

rows = []
for e in root.iter("list"):
    stock = (e.findtext("stock_code") or "").strip()
    if not stock:          # 비상장사는 stock_code 가 비어 있다
        continue
    rows.append({"corp_code": e.findtext("corp_code").strip(),
                 "corp_name": e.findtext("corp_name").strip(),
                 "stock_code": stock,
                 "modify_date": e.findtext("modify_date").strip()})

corp = pd.DataFrame(rows)
print(len(corp), "개 상장사")

3. fnlttSinglAcntAll 응답 실물 — 필드가 왜 이렇게 많나

단일회사 전체 재무제표는 GET https://opendart.fss.or.kr/api/fnlttSinglAcntAll.json 이고 필수 파라미터가 5개입니다.

2015년 이후라는 제약이 중요합니다 — 재무 팩터의 시작점이 여기서 잘립니다. 기간을 늘리려고 다른 출처를 섞으면 항목 정의가 어긋나므로, 표본 기간을 이 제약에 맞춰 잡는 편이 낫습니다.

응답은 계정 항목마다 한 줄씩 나오는 납작한 배열입니다.

{
  "status": "000",
  "message": "정상",
  "list": [
    {
      "rcept_no": "20251114000000",
      "reprt_code": "11014",
      "bsns_year": "2025",
      "corp_code": "00126380",
      "sj_div": "BS",
      "sj_nm": "재무상태표",
      "account_id": "ifrs-full_Assets",
      "account_nm": "자산총계",
      "account_detail": "-",
      "thstrm_nm": "제 57 기 3분기말",
      "thstrm_amount": "000000000000",
      "frmtrm_nm": "제 56 기말",
      "frmtrm_amount": "000000000000",
      "ord": "12",
      "currency": "KRW"
    }
  ]
}

금액은 자리수만 표시했습니다 — 실제 값은 직접 호출해 확인하십시오. 필드를 성격별로 묶으면 세 덩어리입니다.

• 출처 — rcept_no(접수번호 14자리) · reprt_code · bsns_year · corp_code
• 계정 위치 — sj_div(BS 재무상태표 · IS 손익계산서 · CIS 포괄손익 · CF 현금흐름표 · SCE 자본변동표) · account_id(XBRL 표준계정ID) · account_nm · ord
• 금액 — 당기 thstrm_amount·thstrm_add_amount / 전기 frmtrm_amount·frmtrm_q_amount·frmtrm_add_amount / 전전기 bfefrmtrm_amount(사업보고서만) · currency

파싱의 열쇠는 account_id 입니다. account_nm 은 회사마다 표기가 달라지지만 account_id 는 XBRL 표준계정ID 라 ifrs-full_ 로 시작하는 공통 체계를 씁니다. 표준계정에 매핑되지 않는 회사 고유 항목은 - 로 오기도 하므로 표준계정ID 로 먼저 잡고 없으면 계정명으로 대체하십시오.

4. 함정 ① reprt_code 와 thstrm_add_amount

thstrm_amount(당기)와 thstrm_add_amount(당기누적)가 같은 응답에 함께 옵니다. 손익계산서(sj_div가 IS·CIS)에서 둘은 다른 값입니다.

첫째, thstrm_amount 만 쓰면 분기마다 3개월치가 됩니다. 그대로 자산총계로 나누면 ROA 가 연율의 4분의 1로 나오고, 같은 종목의 사업보고서 구간(11011)에서는 연간값이 들어와 시계열에 4배 점프가 생깁니다 — 리밸런싱 시점마다 종목이 갈립니다.

둘째, 재무상태표는 누적 개념이 없습니다. sj_div 가 BS 인 항목은 시점 잔액이라 thstrm_add_amount 가 의미를 갖지 않습니다. 즉 표마다 다른 규칙이 필요합니다.

import pandas as pd

FLOW_SJ = {"IS", "CIS", "CF"}      # 기간 발생 항목 → 누적, 그 밖(BS·SCE) → 당기

def pick_amount(row):
    v = (row.get("thstrm_add_amount") or row.get("thstrm_amount")
         if row["sj_div"] in FLOW_SJ else row.get("thstrm_amount"))
    if v in (None, "", "-"):
        return pd.NA
    return int(str(v).replace(",", ""))   # 금액은 콤마 포함 문자열로 온다

df["amount"] = df.apply(pick_amount, axis=1)

5. 함정 ② fs_div — CFS 와 OFS 를 섞으면 비교가 무너진다

fs_div 는 필수입니다 — CFS 연결재무제표, OFS 개별(별도) 재무제표.

문제는 연결재무제표가 없는 회사입니다. 종속회사가 없어 연결을 작성하지 않는 회사에 fs_div=CFS 로 요청하면 status 가 013(조회된 데이타가 없습니다)으로 돌아옵니다 — 코스닥 소형주를 포함한 유니버스에서는 흔합니다. 그래서 대부분 CFS 먼저, 없으면 OFS 로 대체하는데, 여기서 반드시 같이 해야 하는 일이 있습니다 — 어느 쪽에서 왔는지를 컬럼으로 남기는 것입니다.

import requests

BASE = "https://opendart.fss.or.kr/api/fnlttSinglAcntAll.json"

def fetch_fs(corp_code, bsns_year, reprt_code, crtfc_key):
    """CFS 먼저, 013(데이터 없음)이면 OFS 로 대체하고 출처를 남긴다."""
    for fs_div in ("CFS", "OFS"):
        r = requests.get(BASE, timeout=20, params={
            "crtfc_key": crtfc_key, "corp_code": corp_code,
            "bsns_year": bsns_year, "reprt_code": reprt_code, "fs_div": fs_div,
        })
        j = r.json()
        status = j.get("status")
        if status == "000":
            for row in j["list"]:
                row["fs_div_used"] = fs_div      # ← 이 컬럼이 없으면 나중에 비교가 무너진다
            return j["list"], status
        if status == "013":
            continue                             # 이 구분엔 자료가 없다 → 다음 구분
        raise RuntimeError(f"OpenDART status={status} msg={j.get('message')}")
    return [], "013"

6. 함정 ③ status 코드 — 013 과 020 은 성격이 다르다

OpenDART 는 HTTP 상태코드가 200 이어도 본문 status 가 실패를 말합니다.

갈리는 지점은 013 과 020 입니다. 013 은 이 조합에 자료가 없다는 정상 응답이라 다음 조합으로 넘어가면 되지만, 020 은 그날의 예산을 다 썼다는 뜻이라 재시도 루프에 넣으면 로그만 쌓입니다. 둘을 같은 except 로 묶은 수집기가 하루 한도를 넘긴 뒤에도 몇 시간씩 돌며 빈 데이터프레임을 만드는 것이 이 때문입니다.

7. 시점 정렬 구현 — rcept_dt 로 사용 가능일을 만든다

이제 1절의 문제를 코드로 막습니다. 핵심은 재무제표 행마다 “이 숫자를 언제부터 알 수 있었나”를 붙이는 것입니다. fnlttSinglAcntAll 응답의 rcept_no(14자리)가 접수일자로 시작하는 체계라 거기서 날짜를 뽑을 수도 있지만, 정정공시 때문에 공시검색 list.json 으로 원본 보고서의 접수일자를 확인하는 편이 안전합니다.

corp_code 를 안 주면 조회 범위가 3개월로 묶이므로, 종목별로 corp_code 를 주고 긴 기간을 한 번에 받는 편이 호출 수를 아낍니다.

# 종목별 정기공시 접수일자 목록 → (사업연도, 보고서) → 사용 가능일 매핑
import re, requests
import pandas as pd

LIST_URL = "https://opendart.fss.or.kr/api/list.json"

REPRT_BY_NAME = {           # report_nm 에서 보고서 종류를 역판정
    "사업보고서": "11011",
    "반기보고서": "11012",
}

def regular_filings(corp_code, bgn_de, end_de, crtfc_key):
    j = requests.get(LIST_URL, timeout=20, params={
        "crtfc_key": crtfc_key, "corp_code": corp_code,
        "bgn_de": bgn_de, "end_de": end_de,
        "pblntf_ty": "A",           # 정기공시만
        "last_reprt_at": "Y",       # 정정 반영된 최종보고서
        "page_no": "1", "page_count": "100",   # total_page 만큼 올려 반복
    }).json()
    if j.get("status") == "013":    # 해당 구간에 정기공시가 없음
        return pd.DataFrame()
    if j.get("status") != "000":
        raise RuntimeError(f"list.json status={j.get('status')}")

    rows = []
    for f in j["list"]:
        nm = f["report_nm"]
        code = REPRT_BY_NAME.get(nm.split("(")[0].strip())
        if code is None:                      # 분기보고서는 기준월로 1Q/3Q 를 가른다
            m = re.search(r"\((\d{4})\.(\d{2})\)", nm)
            if not m or "분기보고서" not in nm:
                continue
            code = "11013" if m.group(2) == "03" else "11014" if m.group(2) == "09" else None
            if code is None:
                continue
        rows.append({"corp_code": corp_code, "reprt_code": code,
                     "rcept_no": f["rcept_no"], "rcept_dt": f["rcept_dt"],
                     "report_nm": nm})
    return pd.DataFrame(rows)

붙일 때는 회계기간 말일이 아니라 rcept_dt 를 키로 씁니다. 공시는 장중에도 올라오므로 접수일 다음 거래일부터 쓰는 쪽이 보수적입니다.

# 가격(일봉)에 재무 팩터를 붙일 때: 접수일 다음 거래일부터 유효
import pandas as pd

fs = fs.copy()
fs["rcept_dt"] = pd.to_datetime(fs["rcept_dt"], format="%Y%m%d")
fs["valid_from"] = fs["rcept_dt"] + pd.Timedelta(days=1)   # 장중 공시 대비 1일 지연
fs = fs.sort_values("valid_from")

px = px.sort_values("date")

merged = pd.merge_asof(
    px, fs,
    left_on="date", right_on="valid_from",
    by="stock_code",
    direction="backward",        # 그 날짜 이전에 이미 공시된 것만
    allow_exact_matches=True,
)
# 검증: 회계기간 말일보다 앞선 valid_from 이 하나라도 있으면 누수다
assert (merged["valid_from"] >= merged["period_end"]).all(), "미래참조 누수 발견"

참고로 한국투자증권 KIS API 의 재무비율 계열에는 이 rcept_dt 에 해당하는 접수일자 필드가 없습니다. 그래서 라이브에서 오늘 지표를 볼 때는 KIS 가 간단하고, 과거를 검증하는 백테스트에는 OpenDART 가 필요합니다. 두 경로를 섞을 때는 항목 정의와 연결·개별 구분을 먼저 대조하십시오 — 정의가 다르면 백테스트에서 통과한 임계값이 라이브에서 다른 종목을 고릅니다.

8. 자주 묻는 질문

Q. 회계기간 말일에 붙이면 왜 안 되나요?

그 날에는 아무도 그 숫자를 몰랐습니다. 자본시장법 제159조가 사업보고서를 90일 이내, 제160조가 반기·분기보고서를 45일 이내에 제출하게 하기 때문입니다. list.json 의 rcept_dt 기준으로 사용 시점을 미뤄야 합니다.

Q. thstrm_amount 는 누적인가요 당기인가요?

둘이 따로 옵니다. 11014 3분기보고서의 thstrm_amount 는 7~9월, thstrm_add_amount 는 1~9월입니다. 손익계산서에서만 갈리고 재무상태표(sj_div: BS)는 시점 잔액이라 누적 개념이 없습니다.

Q. fs_div 를 CFS 로 했는데 데이터가 안 옵니다.

연결재무제표가 없는 회사라 status: "013" 이 옵니다. OFS 로 재시도하되 어느 쪽에서 왔는지를 컬럼으로 남기십시오. 연결과 개별을 섞으면 종목 간 비교가 무의미해집니다.

Q. 호출 한도는 얼마인가요?

020 은 요청 제한 초과(안내상 일 20,000건 이상), 021 은 조회 회사 최대 100건 초과입니다. 조합마다 1건이라 2,900종목 10년 분기면 수만 건이 되므로 로컬 캐시가 필수입니다. 현재 한도는 금융감독원 공식 안내에서 확인하십시오.

Q. KIS 재무비율 API 가 있는데 왜 DART 를 쓰나요?

KIS 쪽에는 언제부터 공개돼 있었나를 알려 주는 접수일자 필드가 없습니다. 백테스트에서는 그게 없으면 미래참조를 막을 방법이 없습니다.