Vibe-Trading 港股基本面数据实战：Tushare hk_balancesheet 资产负债表接口完整指南

本文围绕 Vibe-Trading 仓库中 Tushare 数据源技能所收录的港股资产负债表接口（hk_balancesheet）展开，系统讲解该接口的权限要求、输入输出参数、Python 调用方式与数据解读方法，并结合仓库内港股财务数据接口系列（利润表、现金流量表、财务指标）给出可落地的量化研究用法。读完本文，你将能够独立通过 Tushare Pro 拉取任意港股上市公司的资产负债表全科目数据，并在此基础上构建财务健康度分析流程。

接口概述

hk_balancesheet 是 Tushare 提供的港股上市公司资产负债表数据接口，归属于港股财务三大报表数据（利润表 hk_income、资产负债表 hk_balancesheet、现金流量表 hk_cashflow）之一。在 Vibe-Trading 仓库中，该接口被完整收录于 Tushare 数据源技能文档，分类为"港股数据"，接口 ID 为 390，描述为"获取港股上市公司资产负债表"。

使用该接口前需要明确以下约束：

• 权限：需单独开通权限或账户积分达到 15000 分方可调用；
• 提取方式：当前接口按单只股票（ts_code）获取其历史数据，单次请求最大返回 10000 行；
• 循环提取：由于单次返回有上限，历史数据较多时可借助 start_date / end_date 参数分段循环提取；
• 数据格式：接口返回为长表（Tidy Data）结构，即每个财务科目（ind_name）占一行，配合 ind_value 记录科目金额，而非传统宽表结构。

环境准备：Token 配置

在 Vibe-Trading 项目中使用 Tushare 接口，token 有两种配置途径。参照仓库内 股票数据获取示例脚本 的写法：

import os
import tushare as ts
from src.config.accessor import get_env_config

# 方式一：从 Vibe-Trading 环境配置中读取（推荐）
token = get_env_config().data.tushare_token or ts.get_token()

# 方式二：直接读取环境变量
token = os.getenv('TUSHARE_TOKEN') or ts.get_token()

# 初始化 pro 接口实例
pro = ts.pro_api(token)

环境变量的定义位于仓库的 环境变量 Schema：

tushare_token: str = Field(alias="TUSHARE_TOKEN", default="")

即通过设置环境变量 TUSHARE_TOKEN 即可完成配置：

export TUSHARE_TOKEN=your_token

仓库内 Tushare 备用适配器 还展示了 token 的校验逻辑：当 token 为空字符串或 your-tushare-token 占位符时，会抛出 TushareFallbackUnavailable 异常提示"TUSHARE_TOKEN is not configured"；同理，调用 hk_balancesheet 前也应确保 token 真实有效且积分满足权限要求。

输入参数详解

hk_balancesheet 共支持 5 个输入参数，其中仅 ts_code 为必选：

名称	类型	必选	描述
ts_code	str	Y	股票代码（如 00700.HK）
period	str	N	报告期（格式：YYYYMMDD，如 20241231）
ind_name	str	N	指标名（如：应收帐款）
start_date	str	N	报告期开始日期（格式：YYYYMMDD）
end_date	str	N	报告期结束日期（格式：YYYYMMDD）

参数组合的使用建议：

• ts_code + period：精确提取某只股票某个报告期的完整资产负债表（一次性返回该报告期全部科目）；
• ts_code + ind_name：纵向提取某只股票某个科目（如"应收帐款"）的历史序列，用于科目趋势分析；
• ts_code + start_date + end_date：按报告期区间批量拉取，配合单次 10000 行上限做循环分页。

港股股票代码统一采用 XXXXX.HK 格式（如腾讯控股为 00700.HK）。股票代码与名称的对应关系可通过 港股基础信息接口文档（hk_basic）查询，该接口还可获取上市/退市状态、交易单位、ISIN 代码、货币代码等基础信息，便于先构建港股代码清单再逐个拉取财报。

输出参数详解

接口返回 pandas DataFrame，输出字段如下：

名称	类型	默认显示	描述
ts_code	str	Y	股票代码
name	str	Y	股票名称
end_date	str	Y	报告期
ind_name	str	Y	财务科目名称
ind_value	float	Y	财务科目值

这里需要特别说明两点：

1. 长表结构：同一 ts_code + end_date 组合下会有数十行记录，每行是一个独立的资产负债表科目。例如腾讯控股 2024 年报资产负债表一次返回超过 50 个科目；
2. 单位：ind_value 为 float 类型，数据样例中腾讯控股 2024 年末"总资产"为 1.780995e+12，即约 1.78 万亿（港元口径，以接口实际返回为准）。在做跨公司或跨报告期比较时，务必统一货币与计量单位；
3. 空值：部分科目可能为 NaN（如样例中的"股本"行），处理前需做缺失值清洗。

接口用法示例

文档给出两个最核心的调用场景，可直接运行：

import tushare as ts

pro = ts.pro_api()

# 场景一：获取港股腾讯控股 00700.HK 2024 年度的资产负债表数据
df = pro.hk_balancesheet(ts_code='00700.HK', period='20241231')

# 场景二：获取港股腾讯控股 00700.HK 历年"应收帐款"指标数据
df = pro.hk_balancesheet(ts_code='00700.HK', ind_name='应收帐款')

循环提取全部历史报告期

考虑到单次请求最多返回 10000 行、且按单只股票提取的约束，批量场景建议按报告期分页循环：

import tushare as ts

pro = ts.pro_api()

# 按年度区间循环提取，规避单次 10000 行上限
for year in range(2015, 2026):
    df = pro.hk_balancesheet(
        ts_code='00700.HK',
        start_date=f'{year}0101',
        end_date=f'{year}1231',
    )
    print(f"{year}: {df.shape[0]} 行科目数据")
    # 此处可追加到本地存储或入库

字段选择与数据处理

接口不支持 fields 参数裁剪列，返回固定五列。拿到长表数据后，可借助 pandas 将其重塑为按"报告期 × 科目"排列的宽表，便于后续计算：

import pandas as pd

df = pro.hk_balancesheet(ts_code='00700.HK', start_date='20200101', end_date='20241231')

# 透视：行=报告期，列=财务科目，值=科目金额
wide = df.pivot_table(index='end_date', columns='ind_name', values='ind_value', aggfunc='first')
print(wide[['总资产', '总负债', '净资产', '现金及等价物']])

数据样例解读

以文档中的真实返回数据（腾讯控股 00700.HK，20241231 报告期）为例，资产负债表科目可归为几大类，理解这些科目分组是正确解读财报的基础：

类别	代表科目	样例数值（腾讯控股 2024 年报）
非流动资产	物业厂房及设备、无形资产、联营公司权益、投资物业、递延税项资产	非流动资产合计 1.284815e+12
流动资产	应收帐款、预付款项、现金及等价物、短期存款、存货	流动资产合计 4.961800e+11
资产合计	总资产	1.780995e+12
流动负债	应付帐款、应付票据、短期贷款、递延收入(流动)	流动负债合计 3.969090e+11
非流动负债	长期贷款、应付票据(非流动)、递延税项负债	总负债 7.270990e+11
权益	股本、股本溢价、保留溢利、库存股、少数股东权益	净资产 1.053896e+12、股东权益 9.735480e+11

样例中几个值得注意的观测点：

• 总资产 = 总权益及总负债：两行数值完全一致（1.780995e+12），符合会计恒等式，可作为数据完整性的自校验手段；
• 净流动资产（9.927100e+10）= 流动资产 − 流动负债，反映短期偿债能力；
• 库存股为负值（-3.597000e+09），表示公司回购股份，属于权益抵减项；
• 股本科目返回 NaN，提醒我们在计算股东权益构成时需做空值处理；
• 应收帐款（4.820300e+10）与 现金流量表接口文档 中"应收帐款减少 -1.048000e+09"可相互印证，用于交叉核验收入与回款质量。

与港股财务接口系列的联动

资产负债表只是港股财务分析的起点。Vibe-Trading 的 Tushare 技能在 港股数据目录 下完整收录了港股财务数据接口族：

接口	文档	数据内容
hk_balancesheet	港股资产负债表	资产负债科目
hk_income	港股利润表	营业额、经营溢利、股东应占溢利等
hk_cashflow	港股现金流量表	经营/投资/融资现金净额
hk_fina_indicator	港股财务指标数据	预计算好的财务比率

三张报表接口的输入参数结构完全一致（ts_code 必选，period / ind_name / start_date / end_date 可选），可以共用同一套调用与循环分页代码。典型的三表联动分析流程如下：

import tushare as ts

pro = ts.pro_api()
ts_code, period = '00700.HK', '20241231'

bs = pro.hk_balancesheet(ts_code=ts_code, period=period)  # 资产负债表
inc = pro.hk_income(ts_code=ts_code, period=period)        # 利润表
cf = pro.hk_cashflow(ts_code=ts_code, period=period)       # 现金流量表

# 交叉合成基本面指标
bs_map = dict(zip(bs['ind_name'], bs['ind_value']))
inc_map = dict(zip(inc['ind_name'], inc['ind_value']))

# 资产负债率 = 总负债 / 总资产
debt_ratio = bs_map.get('总负债', 0) / bs_map.get('总资产', 1)

# 净资产收益率 = 股东应占溢利 / 净资产
roe = inc_map.get('股东应占溢利', 0) / bs_map.get('净资产', 1)

# 流动比率 = 流动资产 / 流动负债
current_ratio = bs_map.get('流动资产合计', 0) / bs_map.get('流动负债合计', 1)
print(f"资产负债率: {debt_ratio:.2%} | ROE: {roe:.2%} | 流动比率: {current_ratio:.2f}")

如果需要更便捷的比率数据，可直接调用 hk_fina_indicator 获取平台预计算的财务指标（该接口单次最多返回 200 条，需按日期多次请求）。

使用注意事项

1. 权限与积分：hk_balancesheet 需要单独开通权限或 15000 积分，调用前请确认账户状态，否则会返回权限错误；
2. 数据量约束：单次请求最大 10000 行，按单只股票提取；港股大型上市公司单期资产负债表约 50~60 个科目，单次请求通常可容纳多年数据，但跨多公司批量提取时务必设计循环分页；
3. 报告期口径：period、start_date、end_date 均严格使用 YYYYMMDD 格式（如 20241231），且 end_date 语义为"报告期结束日期"，与行情接口的交易日区间含义不同；
4. 科目名称：ind_name 使用港股报表原始科目命名（如"应收帐款""保留溢利(累计亏损)"），与 A 股财报科目命名存在差异，跨市场对比时需做科目映射；
5. NaN 与单位：返回数据中可能混有 NaN，金额单位为港元原始口径（不区分报告币种差异），做横截面比较前需先清洗与单位对齐。

总结

hk_balancesheet 是 Vibe-Trading Tushare 数据源技能中港股基本面数据的重要一环，它以长表结构返回港股上市公司资产负债表全科目数据，配合 period、ind_name 与日期区间参数，可以灵活支撑单期截面分析、单科目历史趋势与多报告期批量提取三类场景。结合仓库内 SKILL.md 数据接口列表 中同族的利润表、现金流量表、财务指标接口，即可在 Vibe-Trading 环境中搭建完整的港股上市公司财务分析管线。