【Python量化实战宝典 #04】财务三表接口手册：资产负债表、利润表、现金流字段映射（Python 可跑）
手册定位：「数据底座手册」第 4 篇。财务数据是质量/成长/估值因子的源头——本篇把资产负债表、利润表、现金流量表、主要指标、股本表的取数端点、字段映射、关键衍生指标（ROE/毛利率/资产负债率）一次性讲透，拿来就能算因子。
接口路径取自官网文档页已验证路径，未虚构。
1. 你将得到什么
读完本篇，你能直接拿到：
- 一只股票最新一期（或全部历史报告期）的三大报表数据，字段含义清楚；
- 把原始接口返回整理成 pandas DataFrame 的标准函数；
- 用三大表算ROE、毛利率、资产负债率、经营现金流/营收等衍生指标的代码；
- 北交所股票的报表端点（与沪深同构，仅域名前缀不同）；
- 5 个真实踩过的坑（单位、报告期、合并/母公司、缺失、字段名漂移）。
2. 取数约定
| 项 | 值 |
|---|---|
| 基础域名 | https://api.zhituapi.com |
| 鉴权 | 所有请求带?token=你的token |
| 股票代码格式 | 600519.SH（沪）/000001.SZ（深）/920547.BJ（北交所） |
| 返回 | JSON，多数报表为「按报告期」的列表 |
真实调用把
TOKEN换成你的 token；本手册示例用_MOCK=True内置演示数据，逻辑与真实取数完全一致，先跑通再替换。
3. 端点分组地图
| 分组 | 端点（GET） | 说明 |
|---|---|---|
| 资产负债表 | /hs/fin/balance/{代码}.{市场} | 资产/负债/权益各科目，按报告期 |
| 利润表 | /hs/fin/income/{代码}.{市场} | 营收/成本/利润各科目 |
| 现金流量表 | /hs/fin/cashflow/{代码}.{市场} | 经营/投资/筹资现金流 |
| 财务主要指标 | /hs/fin/ratios/{代码}.{市场} | ROE/毛利率/净利率等汇总指标 |
| 公司股本表 | /hs/fin/capital/{代码}.{市场} | 总股本/流通股本 |
| 北交所·资产负债表 | /bj/fin/balance/{代码}.BJ | 同构，前缀bj |
| 北交所·利润表 | /bj/fin/income/{代码}.BJ | 同构 |
| 北交所·现金流量表 | /bj/fin/cashflow/{代码}.BJ | 同构 |
北交所其余报表（
ratios/capital）端点与沪深同构，仅把/hs/换/bj/，本文不复列。
4. 核心模板函数（自包含可跑）
importtime,requests,pandasaspd 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)foriinrange(tries):try:if_MOCK:returndefault r=requests.get(url,timeout=8)r.raise_for_status()returnr.json()exceptException:ifi==tries-1:returndefault time.sleep(0.5*(i+1))deffetch_balance(code,market="SH"):return_get("/hs/fin/balance/%s.%s"%(code,market),default=[])deffetch_income(code,market="SH"):return_get("/hs/fin/income/%s.%s"%(code,market),default=[])deffetch_cashflow(code,market="SH"):return_get("/hs/fin/cashflow/%s.%s"%(code,market),default=[])deffetch_ratios(code,market="SH"):return_get("/hs/fin/ratios/%s.%s"%(code,market),default=[])defto_frame(raw):"""接口返回 -> DataFrame（兼容 list[dict] 与 dict 两种形态）。"""ifisinstance(raw,dict):# 有的端点返回 {报告期: {...}}，统一成列表rows=[dict(报告期=k,**v)fork,vinraw.items()]else:rows=list(rawor[])returnpd.DataFrame(rows)deflatest_row(df):ifdfisNoneordf.empty:returnNonedate_col="报告期"if"报告期"indf.columnselsedf.columns[0]returndf.sort_values(date_col).iloc[-1].to_dict()defrun_check():global_MOCK _MOCK=True# 演示数据：真实调用替换为上面的 fetch_* 即可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["归属母公司股东权益"]andi["净利润"]/b["归属母公司股东权益"]mgn=1-i["营业总成本"]/i["营业总收入"]leverage=b["总负债"]/b["总资产"]ocf_ratio=c["经营活动现金流量净额"]/i["净利润"]assert0<roe<1and0<mgn<1and0<leverage<1print("校验通过 | ROE=%.3f 毛利率=%.3f 资产负债率=%.3f 经营现金流/净利润=%.3f"%(roe,mgn,leverage,ocf_ratio))_MOCK=Falseif__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. 坑与注意事项
- 单位不一致：金额多为「元」，但部分科目是「万元」，先
print一行确认再除/乘，别直接当元用。 - 报告期合并：同一股票多年报/季报混在列表里，算因子前务必按
报告期排序取最新，别取错期。 - 合并报表 vs 母公司：报表通常默认合并报表，做行业对比要统一口径，别拿母公司的和别人合并的比。
- 字段名漂移：不同端点字段名可能是中文（
净利润）也可能英文（net_profit），先print(resp.json()[0])看一行再写映射。 - 缺失与空值：新股/ST 可能缺某一期，计算衍生指标前
dropna()或做空值兜底，避免因子表出现 NaN 污染回测。
7. 小结与下一篇预告
本篇把三大报表 + 主要指标 + 股本表的取数、字段映射、衍生指标算法定了下来，是模块二（选股因子）的数据底座。下一篇讲资金流向——主力净流入与北向资金全字段，是资金面因子的来源。
下一篇预告：《【Python量化实战宝典 #05】资金流向接口手册：主力净流入·北向资金全字段（Python 可跑）》
8. 免责声明
本文所有接口路径均来自官方文档，示例数据为演示用途，不构成任何投资建议。实盘使用前请自行核对字段与单位。
