手册定位：「数据底座手册」第 4 篇。财务数据是质量/成长/估值因子的源头——本篇把资产负债表、利润表、现金流量表、主要指标、股本表的取数端点、字段映射、关键衍生指标（ROE/毛利率/资产负债率）一次性讲透，拿来就能算因子。
接口路径取自智兔数服官网文档页已验证路径，未虚构。

1. 你将得到什么

读完本篇，你能直接拿到：

• 一只股票最新一期（或全部历史报告期）的三大报表数据，字段含义清楚；
• 把原始接口返回整理成 pandas DataFrame 的标准函数；
• 用三大表算 ROE、毛利率、资产负债率、经营现金流/营收 等衍生指标的代码；
• 北交所股票的报表端点（与沪深同构，仅域名前缀不同）；
• 5 个真实踩过的坑（单位、报告期、合并/母公司、缺失、字段名漂移）。

2. 取数约定

真实调用把 TOKEN 换成你的 token；本手册示例用 _MOCK=True 内置演示数据，逻辑与真实取数完全一致，先跑通再替换。

3. 端点分组地图

北交所其余报表（ratios/capital）端点与沪深同构，仅把 /hs/ 换 /bj/，本文不复列。

4. 核心模板函数（自包含可跑）

import time, requests, pandas as pd

BASE = "https://api.zhituapi.com"
TOKEN = "你的token"
_MOCK = False  # 演示模式：True 时用内置数据，不发起网络请求


def _hit_key(path):
    return "%s%s?token=%s" % (BASE, path, TOKEN)


def _get(path, default=None, tries=3):
    url = _hit_key(path)
    for i in range(tries):
        try:
            if _MOCK:
                return default
            r = requests.get(url, timeout=8)
            r.raise_for_status()
            return r.json()
        except Exception:
            if i == tries - 1:
                return default
            time.sleep(0.5 * (i + 1))


def fetch_balance(code, market="SH"):
    return _get("/hs/fin/balance/%s.%s" % (code, market), default=[])


def fetch_income(code, market="SH"):
    return _get("/hs/fin/income/%s.%s" % (code, market), default=[])


def fetch_cashflow(code, market="SH"):
    return _get("/hs/fin/cashflow/%s.%s" % (code, market), default=[])


def fetch_ratios(code, market="SH"):
    return _get("/hs/fin/ratios/%s.%s" % (code, market), default=[])


def to_frame(raw):
    """接口返回 -> DataFrame（兼容 list[dict] 与 dict 两种形态）。"""
    if isinstance(raw, dict):
        rows = [dict(报告期=k, **v) for k, v in raw.items()]
    else:
        rows = list(raw or [])
    return pd.DataFrame(rows)


def latest_row(df):
    if df is None or df.empty:
        return None
    date_col = "报告期" if "报告期" in df.columns else df.columns[0]
    return df.sort_values(date_col).iloc[-1].to_dict()


def run_check():
    global _MOCK
    _MOCK = True
    bal = [{"报告期": "2025-12-31", "总资产": 1.20e11, "总负债": 4.0e10, "归属母公司股东权益": 7.5e10},
           {"报告期": "2024-12-31", "总资产": 1.10e11, "总负债": 3.8e10, "归属母公司股东权益": 6.9e10}]
    inc = [{"报告期": "2025-12-31", "营业总收入": 1.50e10, "营业总成本": 9.0e9, "净利润": 3.5e9},
           {"报告期": "2024-12-31", "营业总收入": 1.30e10, "营业总成本": 8.2e9, "净利润": 3.0e9}]
    cf = [{"报告期": "2025-12-31", "经营活动现金流量净额": 4.0e9},
          {"报告期": "2024-12-31", "经营活动现金流量净额": 3.6e9}]
    b = latest_row(to_frame(bal)); i = latest_row(to_frame(inc)); c = latest_row(to_frame(cf))
    roe = b["归属母公司股东权益"] and i["净利润"] / b["归属母公司股东权益"]
    mgn = 1 - i["营业总成本"] / i["营业总收入"]
    leverage = b["总负债"] / b["总资产"]
    ocf_ratio = c["经营活动现金流量净额"] / i["净利润"]
    assert 0 < roe < 1 and 0 < mgn < 1 and 0 < leverage < 1
    print("校验通过 | ROE=%.3f 毛利率=%.3f 资产负债率=%.3f 经营现金流/净利润=%.3f"
          % (roe, mgn, leverage, ocf_ratio))
    _MOCK = False


if __name__ == "__main__":
    run_check()

5. 跑通示例

把 TOKEN 换成你的 token、_MOCK=False 后：

df_bal = to_frame(fetch_balance("600519", "SH"))
df_inc = to_frame(fetch_income("600519", "SH"))
print(df_bal.head())
print("最新一期净资产：", latest_row(df_bal)["归属母公司股东权益"])

输出即一张按报告期排列的报表，直接 merge 成因子表。

6. 坑与注意事项

1. 单位不一致：金额多为「元」，但部分科目是「万元」，先 print 一行确认再除/乘，别直接当元用。
2. 报告期合并：同一股票多年报/季报混在列表里，算因子前务必按 报告期 排序取最新，别取错期。
3. 合并报表 vs 母公司：报表通常默认合并报表，做行业对比要统一口径，别拿母公司的和别人合并的比。
4. 字段名漂移：不同端点字段名可能是中文（净利润）也可能英文（net_profit），先 print(resp.json()[0]) 看一行再写映射。
5. 缺失与空值：新股/ST 可能缺某一期，计算衍生指标前 dropna() 或做空值兜底，避免因子表出现 NaN 污染回测。

7. 小结与下一篇预告

本篇把三大报表 + 主要指标 + 股本表的取数、字段映射、衍生指标算法定了下来，是模块二（选股因子）的数据底座。下一篇讲资金流向——主力净流入与北向资金全字段，是资金面因子的来源。

下一篇预告：《【Python量化实战全攻略 #05】资金流向接口手册：主力净流入·北向资金全字段（附代码）》

8. 免责声明

本文所有接口路径均来自官方文档，示例数据为演示用途，不构成任何投资建议。实盘使用前请自行核对字段与单位。

关于数据来源：本文接口来自智兔数服（www.zhituapi.com）官方文档，覆盖沪深A股、指数、基金、可转债等 200+ 已验证接口路径，注册可领免费 token 做研究测试。
更多实战手册见技术博客：zhituapi.com/blog.html。
本系列《Python量化实战全攻略》共 32 篇，下一篇讲资金流向接口。