KIS 재무비율 API 7종 — ROE·부채비율로 팩터 만들기

팩터는 개념이고, 숫자는 어디서 오나

퀄리티 팩터는 ROE로, 밸류 팩터는 PBR로, 안정성은 부채비율로 잰다 — 팩터가 무엇인지는 이미 여러 번 설명된 이야기입니다. 막히는 곳은 그다음입니다. 그 숫자를 매일 아침 봇이 어디서 받아 오느냐.

주가 데이터는 선택지가 많습니다. pykrx·FinanceDataReader·KIS API로 시세와 거래량은 어렵지 않게 받습니다. 그런데 재무 데이터로 넘어가면 이야기가 달라집니다. 증권사 API에 재무제표가 들어 있다는 사실 자체를 모르고, DART 크롤링부터 알아보는 경우가 많습니다.

재무 API 7종 전수표

공식 저장소 examples_llm/domestic_stock/ 아래 finance_로 시작하는 예제 7개에서 tr_id·API_URL·문서 번호를 그대로 뽑은 표입니다.

FHKST66430700과 문서 번호 084는 비어 있습니다. 예제 목록에 해당 항목이 없어서 무엇이 빠졌는지는 소스만으로 확인되지 않습니다. 번호가 연속일 것이라 가정하고 700을 찍어 보는 코드를 짜지 마십시오.

공통 파라미터는 세 개뿐이라 호출 자체는 단순합니다.

함정 1 — 같은 파라미터의 대소문자가 갈린다

7개를 하나의 공통 함수로 묶는 것이 자연스러운 설계입니다. 파라미터가 같으니까요. 그런데 예제 소스의 params 딕셔너리를 나란히 놓고 보면 표기가 일치하지 않습니다.

# finance_financial_ratio.py  (FHKST66430300)
params = {
    "FID_DIV_CLS_CODE": fid_div_cls_code,        # ← 대문자
    "fid_cond_mrkt_div_code": fid_cond_mrkt_div_code,
    "fid_input_iscd": fid_input_iscd,
}

# finance_stability_ratio.py  (FHKST66430600)
params = {
    "fid_input_iscd": fid_input_iscd,
    "fid_div_cls_code": fid_div_cls_code,        # ← 소문자
    "fid_cond_mrkt_div_code": fid_cond_mrkt_div_code,
}

가장 안전한 대응은 두 표기를 모두 보내는 것이 아니라 TR별로 어느 표기를 쓰는지 표로 들고 있는 것입니다. 아래 코드에서 그렇게 처리합니다.

함정 2 — PER·PBR은 여기 없다

밸류 팩터를 만들려고 재무비율 FHKST66430300을 호출하면 기대했던 필드가 없습니다. 응답에 들어오는 것은 eps(EPS) · bps(BPS) · sps(주당매출액)까지입니다.

이유는 단순합니다. PER·PBR은 분모에 현재가가 들어가는 주가 배수라서 재무제표 API가 돌려줄 성질의 값이 아닙니다. 직접 계산해야 합니다.

# PBR = 현재가 / BPS,  PER = 현재가 / EPS
# 현재가는 시세 API에서 따로 받는다 (FHKST01010100 → stck_prpr)

bps = float(ratio_row["bps"])          # 재무비율 FHKST66430300
price = float(quote_row["stck_prpr"])  # 현재가 FHKST01010100

pbr = price / bps if bps else None

# ⚠ 두 값의 기준 시점이 다르다는 것을 반드시 같이 기록한다.
record = {
    "stck_shrn_iscd": code,
    "pbr": pbr,
    "bps_stac_yymm": ratio_row["stac_yymm"],  # 재무 결산 년월
    "price_asof": today,                       # 시세 조회 일자
}

현재가를 받는 쪽은 KIS API 현재가 조회 편에 정리돼 있습니다. 그리고 7종 API는 모두 종목코드를 하나씩만 받기 때문에, 유니버스 전체를 돌리려면 종목 마스터 파일에서 종목 목록을 먼저 만들어 두어야 합니다.

어느 지표가 어느 TR에 있나

예제의 column_mapping을 그대로 옮긴 것입니다. 필드명은 전부 소문자입니다.

7종을 한 종목에 모으기

대소문자 차이를 표로 가두고, 필요한 TR만 골라 부르는 구조입니다.

import os, time, requests

BASE = "https://openapi.koreainvestment.com:9443"
FIN  = "/uapi/domestic-stock/v1/finance/"

# TR ID → (엔드포인트, 기간구분 파라미터 표기)
# ★ 대소문자가 TR마다 다르다. 표로 들고 있는 편이 안전하다.
FINANCE_TR = {
    "balance_sheet":    ("FHKST66430100", "balance-sheet",      "FID_DIV_CLS_CODE"),
    "income_statement": ("FHKST66430200", "income-statement",   "FID_DIV_CLS_CODE"),
    "financial_ratio":  ("FHKST66430300", "financial-ratio",    "FID_DIV_CLS_CODE"),
    "profit_ratio":     ("FHKST66430400", "profit-ratio",       "FID_DIV_CLS_CODE"),
    "other_ratios":     ("FHKST66430500", "other-major-ratios", "fid_div_cls_code"),
    "stability_ratio":  ("FHKST66430600", "stability-ratio",    "fid_div_cls_code"),
    "growth_ratio":     ("FHKST66430800", "growth-ratio",       "fid_div_cls_code"),
}

def fetch_finance(kind: str, code: str, token: str, yearly: bool = True):
    tr_id, path, div_key = FINANCE_TR[kind]
    params = {
        div_key: "0" if yearly else "1",   # 0=연간 1=분기
        "fid_cond_mrkt_div_code": "J",
        "fid_input_iscd": code,
    }
    headers = {
        "authorization": f"Bearer {token}",
        "appkey":    os.environ["KIS_APP_KEY"],     # 키는 환경변수로
        "appsecret": os.environ["KIS_APP_SECRET"],
        "tr_id":     tr_id,
    }
    r = requests.get(BASE + FIN + path, headers=headers, params=params, timeout=10)
    r.raise_for_status()
    return r.json().get("output", [])

def quality_snapshot(code: str, token: str) -> dict:
    """ROE·부채비율·성장률은 재무비율 하나로 끝난다."""
    rows = fetch_finance("financial_ratio", code, token)
    if not rows:
        return {}
    latest = rows[0]                       # 최근 결산부터 내려온다
    return {
        "code":       code,
        "stac_yymm":  latest.get("stac_yymm"),    # ★ 결산 년월을 반드시 같이 남긴다
        "roe":        latest.get("roe_val"),
        "debt_ratio": latest.get("lblt_rate"),
        "eps":        latest.get("eps"),
        "bps":        latest.get("bps"),
        "sales_grow": latest.get("grs"),
    }

# 유니버스를 돌 때는 호출 간격을 둔다
for code in ["005930", "000660", "035420"]:
    print(quality_snapshot(code, TOKEN))
    time.sleep(0.2)

time.sleep(0.2)를 넣은 이유는 7종 API가 종목 하나씩만 받기 때문입니다. 코스피·코스닥 전 종목을 돌면 호출 수가 수천 건이 됩니다. 유량 제한에 걸릴 때의 대응은 앞서 언급한 에러코드 정리에 그대로 적용되고, 조건에 맞는 종목을 먼저 좁히는 방법은 스크리너 편을 참고하십시오.

팩터로 쓰기 전에 알아야 할 두 가지 편향

여기까지가 데이터를 받는 방법입니다. 받은 숫자를 백테스트에 넣는 순간부터는 다른 문제가 시작됩니다. 재무 데이터 특유의 편향 두 가지는 둘 다 성과를 좋아 보이게 만드는 방향으로 작용합니다.

1. 룩어헤드 편향 — stac_yymm은 공시일이 아니다

응답의 stac_yymm은 결산 년월입니다. 그 숫자가 시장에 공개된 날짜가 아닙니다. 12월 결산 수치는 이듬해 봄에야 공시되는데, 백테스트에서 1월 1일부터 그 값을 쓰면 당시에는 알 수 없던 정보로 매매한 것이 됩니다. 최소한 결산월로부터 충분한 지연을 두고 반영해야 하며, 정확히 하려면 실제 공시일을 별도로 확보해야 합니다.

2. 생존편향 — API는 지금 살아 있는 종목만 준다

재무 API는 현재 상장된 종목에 대해 응답합니다. 상장폐지된 회사는 조회되지 않습니다. 과거 시점의 유니버스를 지금 종목 목록으로 구성하면 망한 회사가 전부 빠진 표본이 됩니다. 같은 문제를 백테스트 엔진 차원에서 다룬 이야기는 KIS 공식 백테스터 편에 정리돼 있습니다.

성과를 재는 쪽은 샤프지수·MDD 계산과 매매비용 반영을 같이 보셔야 숫자가 현실에 가까워집니다. 비용을 빼지 않은 팩터 백테스트는 거의 예외 없이 좋게 나옵니다.

정리

• ROE·부채비율·성장률은 FHKST66430300 한 번 — roe_val·lblt_rate·grs
• 재무 TR은 FHKST66430100부터 7개, 700과 문서 084는 비어 있다
• fid_div_cls_code는 4개가 대문자, 3개가 소문자 — 틀려도 에러가 안 난다
• PER·PBR은 없다 — eps·bps를 현재가로 나눠야 한다
• stac_yymm은 결산월이지 공시일이 아니다 — 지연 없이 쓰면 룩어헤드