EMWebApi/docs/api_manual.md

EMWeb API 接口文档

东方财富 CHOICE 数据抓取服务 HTTP 接口使用说明。对应目前已实现的功能，随版本更新。

基本信息

项	值
服务名称	EMWeb API
版本	0.1.0
默认地址	http://127.0.0.1:8765
数据源	东方财富 CHOICE 公开接口（无需登录/cookie）
Swagger	http://127.0.0.1:8765/docs

启动：

uv run python api.py   # 监听 0.0.0.0:8765

通用说明

返回结构

所有 /fin/* 接口成功时返回统一结构：

{
  "success": true,
  "count": 10,
  "columns": ["SECUCODE", "REPORT_DATE", "..."],
  "data": [ { "SECUCODE": "603233.SH", "..." }, "..." ],
  "codes_requested": ["603233.SH"],
  "years": 3
}

字段	说明
success	是否成功
count	数据行数
columns	数据列名（与上游接口返回一致，不做翻译）
data	数据行数组；空值/NaN/NaT/±inf 统一转 null
其余字段	回显本次请求参数，便于排查

错误

HTTP 状态	场景
400	参数不合法（如 stocks 为空）
404	请求成功但无数据（success: false，data: []）
5xx	上游接口异常（超时、返回失败等）

股票代码格式

统一使用 代码.市场，如 603233.SH（上交所）/ 000001.SZ（深交所）。多只股票用英文逗号分隔。

---

1. GET /health — 健康检查

参数：无

响应：

{ "status": "ok" }

---

2. GET /fin/summary — 财务摘要（报告期）

拉取多只股票的财务摘要指标（报告期口径，单季度数据请用 /fin/quarterly-summary）。

参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票列表。两种写法：① 仅代码 603233.SH（自动查 ORG_CODE，不稳定）；② 代码:ORG_CODE，如 603233.SH:10500736（推荐，最稳）
years	int		10	拉取多少年历史（1~20）
date_type_codes	string		1,5,6	报告期代码，逗号分隔：1=一季报，5=中报，6=年报
is_newest	bool		true	是否只要最新合并报表

示例

curl "http://127.0.0.1:8765/fin/summary?stocks=603233.SH:10500736&years=5&date_type_codes=1,5,6"

说明

• ORG_CODE 无法从公开接口稳定自动获取，推荐在抓包时记录（如大参林 603233.SH → 10500736）。
• 只传代码时自动查询失败会返回 400 并提示改用 代码:ORG_CODE 格式。

---

3. GET /fin/quarterly-summary — 财务摘要（单季度）

拉取多只股票的季度财务摘要，数据按 SECUCODE + REPORT_DATE 去重并倒序排列。

参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH,600519.SH。仅需代码，不需要 ORG_CODE
years	int		3	未传 report_dates 时，拉取最近多少年的季度数据（1~20）
report_dates	string		无	可选，逗号分隔的报告期 YYYY-MM-DD，如 2025-03-31,2024-12-31；传入时精确筛选

示例

# 最近 3 年全部季度
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&years=3"

# 精确指定报告期
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&report_dates=2025-03-31,2024-12-31"

---

4. GET /fin/main-business — 主营构成（按产品 / 按地区）

拉取多只股票的主营构成，可分别按产品分类或按地区分类。

参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH。仅需代码，不需要 ORG_CODE
classify_type	string		产品	分类方式：产品 或 地区
years	int		3	拉取最近多少年数据（1~20）

示例

# 按产品分类（中文参数建议 URL 编码：产品=%E4%BA%A7%E5%93%81）
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E4%BA%A7%E5%93%81&years=3"

# 按地区分类（地区=%E5%9C%B0%E5%8C%BA）
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E5%9C%B0%E5%8C%BA&years=3"

返回数据常见列

列名	说明
SECUCODE	股票代码
CLASSIFY_TYPE	分类方式（产品/地区）
STD_REPORT_NAME	分类名（如产品名/地区名，含"合计"行）
ReportDate	报告期（YYYY-MM-DD HH:MM:SS）
MAIN_BUSINESS_INCOME	主营业务收入
MAIN_BUSINESS_COST	主营业务成本
MAIN_BUSINESS_RPOFIT	主营业务利润
GROSS_RPOFIT_RATIO	毛利率（%）
MBI_RATIO	占主营业务收入比（%）
MBR_RATIO	占主营业务利润比（%）
IS_MAXREPORTDATE	是否最新报告期（1=是）

---

5. 财务报表（资产负债表 / 利润表 / 现金流量表）

公共参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH。仅需代码，不需要 ORG_CODE
years	int		3	拉取最近多少年的数据（1~20）

示例

# 资产负债表
curl "http://127.0.0.1:8765/fin/balance?stocks=603233.SH&years=3"

# 利润表
curl "http://127.0.0.1:8765/fin/income?stocks=603233.SH&years=3"

# 现金流量表
curl "http://127.0.0.1:8765/fin/cashflow?stocks=603233.SH&years=3"

说明：数据为按报告期的明细科目，列数较多（资产负债表约 160+ 列，利润表约 80+ 列，现金流量表约 140 列），列名与上游接口一致（如 TOTAL_ASSETS、TOTAL_OPERATE_INCOME、SALES_SERVICES）。

---

6. 财务分析指标（盈利能力 / 资本结构 / 营运能力 / 成长能力 / 杜邦）

公共参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH。仅需代码，不需要 ORG_CODE
years	int		3	拉取最近多少年的数据（1~20）

示例

# 盈利能力与收益质量 (ROE/ROA/毛利率等)
curl "http://127.0.0.1:8765/fin/profitability?stocks=603233.SH&years=3"

# 资本结构与偿债能力 (资产负债率/流动比率等)
curl "http://127.0.0.1:8765/fin/capital-structure?stocks=603233.SH&years=3"

# 营运能力 (周转天数/周转率等)
curl "http://127.0.0.1:8765/fin/operate-ability?stocks=603233.SH&years=3"

# 成长能力 (营收/净利同比等)
curl "http://127.0.0.1:8765/fin/growth?stocks=603233.SH&years=3"

# 杜邦分析 (ROE 拆解)
curl "http://127.0.0.1:8765/fin/dupont?stocks=603233.SH&years=3"

各接口常见列

接口	常见列
盈利能力	ROE_AVERAGE（平均净资产收益率）、ROE_DILUTED（摊薄）、ROA、ROIC、SALE_GPR（毛利率）等
资本结构	DEBT_ASSET_RATIO（资产负债率）、CURRENT_RATIO（流动比率）、SPEED_RATIO（速动比率）等
营运能力	OPERATE_CYCLE（营业周期）、INVENTORY_DAYS（存货周转天数）、ACCOUNTS_RECE_DAYS 等
成长能力	BASICEPS_YOY、TOTAL_OPERATEINCOME_YOY（营收同比）、PARENT_NETPROFIT_YOY（净利同比）等
杜邦	ROE、NETPROFIT、TOTAL_ASSETS、EQUITY_MULTIPLIER（权益乘数）、NETPROFIT_TOI 等

---

7. 分红（明细 / 统计）

公共参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH。仅需代码，不需要 ORG_CODE
years	int		5	拉取最近多少年的分红数据（1~20）

示例

# 分红明细 (含方案/股权登记日/除权除息日等)
curl "http://127.0.0.1:8765/fin/dividend-detail?stocks=603233.SH&years=5"

# 分红统计 (按年汇总, 含股息率/分红率等)
curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"

各接口常见列

接口	常见列
分红明细	IMPL_PLAN_PROFILE（方案）、ASSIGN_PROGRESS（进度）、PRETAX_BONUS_RMB（每股税前）、EX_DIVIDEND_DATE（除权除息日）、PAY_CASH_DATE 等
分红统计	AUALACCMDIV_ARD（每股股利）、PARENTNETPROFIT、GXL（股息率）、SUM_AUALACCMDIV_ARD 等

---

8. 股东数据（十大流通股东 / 十大股东明细 / 股东户数）

公共参数

参数	类型	必填	默认	说明
stocks	string	✅	—	逗号分隔股票代码，如 603233.SH。仅需代码，不需要 ORG_CODE
years	int		3	拉取最近多少年的数据（1~20）

示例

# 十大流通股东
curl "http://127.0.0.1:8765/fin/free-holders?stocks=603233.SH&years=3"

# 十大股东明细
curl "http://127.0.0.1:8765/fin/holders?stocks=603233.SH&years=3"

# 股东户数
curl "http://127.0.0.1:8765/fin/holder-num?stocks=603233.SH&years=3"

各接口常见列

接口	常见列
十大流通股东	HOLDER_NAME（股东名）、HOLD_NUM（持股数）、HOLD_RATIO、FREE_HOLDNUM_RATIO（占流通股比）、HOLD_CHANGE 等
十大股东明细	RANK（排名）、HOLDER_NAME、HOLD_NUM、HOLD_RATIO、DIRECTION（增减持方向）、NOTICE_DATE 等
股东户数	HOLDER_TOTAL_NUM（股东总数）、HOLDER_TOTAL_NUMCHANGE（户数增减）、AVG_TOTAL_SHARES（户均持股）等

---

接口一览

路径	功能	数据来源报表
/health	健康检查	—
/fin/summary	财务摘要（报告期）	RPT_CUSTOM_ORGF9_FIN_SUMMARY
/fin/quarterly-summary	财务摘要（单季度）	RPT_HSF9_FIN_SUMMARYQUARTERNEW
/fin/main-business	主营构成（产品/地区）	ZYGC_AFLZS → RPT_HSF9_FN_MAINOPBUSINESS
/fin/balance	资产负债表	CWSJ_ZCFZB → RPT_CUSTOM_HSF9_FINA_GBALANCE
/fin/income	利润表	CWSJ_LRB → RPT_CUSTOM_HSF9_FINA_GINCOMESYN
/fin/cashflow	现金流量表	CWSJ_XJLLB → RPT_CUSTOM_HSF9_FINA_GCASHFLOW
/fin/profitability	盈利能力与收益质量	CWFX_YLNLYSYZL → RPT_HSF9_FINA_PROFITEARNING
/fin/capital-structure	资本结构与偿债能力	CWFX_ZBJGYCZNL → RPT_HSF9_FINA_CAPPAYAB
/fin/operate-ability	营运能力	RPT_HSF9_FINA_OPERATEABILITY
/fin/growth	成长能力	CWFX_CZNL → RPT_HSF9_FINA_GROWTH
/fin/dupont	杜邦分析	RPT_HSF9_FINA_DUPONT
/fin/dividend-detail	分红明细	RPT_HSF9_ASSIGNPLAN_DETAIL
/fin/dividend-statics	分红统计	RPT_HSF9_ASSIGNPLAN_STATICS
/fin/free-holders	十大流通股东	RPT_F10_EH_FREEHOLDERS
/fin/holders	十大股东明细	RPT_DMSK_HOLDERS
/fin/holder-num	股东户数	RPT_F10_EH_HOLDERNUM

测试

uv run pytest tests/ -q   # 冒烟测试: 连真实接口验证各模块能取到数据 (30 用例)