EMWebApi/SKILLS.md

SKILLS.md — EMWeb API 使用说明书

本工具是一个 HTTP 财务数据服务，聚合了东方财富 CHOICE 的财务数据抓取能力。 无鉴权、无 cookie、无 key，直接 GET 即可调用，返回结构化 JSON。 适合任何需要 A 股上市公司财务数据/股东/分红信息的 agent 使用。

---

1. 基本信息

项	值
Base URL	http://<服务地址>:8765
鉴权	无
数据覆盖	A 股财务三表、财务指标、主营构成、分红、股东数据
Swagger	http://<服务地址>:8765/docs（可视化调试）

2. 通用约定

• 股票代码格式：代码.市场，如 603233.SH（上交所）、000001.SZ（深交所）。多只用英文逗号分隔：603233.SH,600519.SH。
• years 参数：拉取最近 N 年数据，范围 1~20。
• 返回结构（成功）：

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

• 错误情况：
  • HTTP 400：参数不合法（如 stocks 为空）。
  • HTTP 404 + success: false：请求成功但无数据（股票代码写错、或该股无此数据）。此时 data 为 []，不要重试。
  • HTTP 5xx：上游接口异常，可稍后重试。
  • 空值（NaN/NaT/±inf）在 JSON 中统一为 null。

3. 接口总览

类别	路径	一句话说明
健康	GET /health	探活
财务摘要	GET /fin/summary	财务摘要（报告期口径，需 ORG_CODE）
财务摘要	GET /fin/quarterly-summary	财务摘要（单季度，只需代码）
主营	GET /fin/main-business	主营构成（按产品 / 按地区）
报表	GET /fin/balance	资产负债表
报表	GET /fin/income	利润表
报表	GET /fin/cashflow	现金流量表
指标	GET /fin/profitability	盈利能力与收益质量
指标	GET /fin/capital-structure	资本结构与偿债能力
指标	GET /fin/operate-ability	营运能力
指标	GET /fin/growth	成长能力
指标	GET /fin/dupont	杜邦分析（ROE 拆解）
分红	GET /fin/dividend-detail	分红明细（方案/除权日等）
分红	GET /fin/dividend-statics	分红统计（按年汇总）
股东	GET /fin/free-holders	十大流通股东
股东	GET /fin/holders	十大股东明细
股东	GET /fin/holder-num	股东户数

4. 接口详情

4.1 快速探活

curl "http://127.0.0.1:8765/health"
# => {"status":"ok"}

4.2 财务摘要

# 单季度 (只需代码) —— 适合拿季度经营数据
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&years=3"

# 报告期口径 (推荐带 ORG_CODE, 否则可能查不到, 详见第 5 节)
curl "http://127.0.0.1:8765/fin/summary?stocks=603233.SH:10500736&years=5"

4.3 主营构成

# 按产品分类 (中文参数需要 URL 编码: 产品=%E4%BA%A7%E5%93%81, 地区=%E5%9C%B0%E5%8C%BA)
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E4%BA%A7%E5%93%81&years=3"

关键列：STD_REPORT_NAME（产品/地区名，含"合计"行）、MAIN_BUSINESS_INCOME、MAIN_BUSINESS_RPOFIT、GROSS_RPOFIT_RATIO（毛利率）。

4.4 三张财务报表

curl "http://127.0.0.1:8765/fin/balance?stocks=603233.SH&years=3"    # 资产负债表, 列含 TOTAL_ASSETS 等
curl "http://127.0.0.1:8765/fin/income?stocks=603233.SH&years=3"     # 利润表, 列含 TOTAL_OPERATE_INCOME 等
curl "http://127.0.0.1:8765/fin/cashflow?stocks=603233.SH&years=3"   # 现金流量表, 列含 SALES_SERVICES 等

4.5 财务指标（四大分析 + 杜邦）

curl "http://127.0.0.1:8765/fin/profitability?stocks=603233.SH"     # ROE/ROA/毛利率
curl "http://127.0.0.1:8765/fin/capital-structure?stocks=603233.SH" # 资产负债率/流动比率
curl "http://127.0.0.1:8765/fin/operate-ability?stocks=603233.SH"   # 周转率/周转天数
curl "http://127.0.0.1:8765/fin/growth?stocks=603233.SH"            # 营收/净利同比增速
curl "http://127.0.0.1:8765/fin/dupont?stocks=603233.SH"            # ROE 三因素拆解

4.6 分红

curl "http://127.0.0.1:8765/fin/dividend-detail?stocks=603233.SH&years=5"   # 明细: IMPL_PLAN_PROFILE(方案)/EX_DIVIDEND_DATE(除权日)
curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"  # 统计: GXL(股息率)/AUALACCMDIV_ARD(每股股利)

4.7 股东数据

curl "http://127.0.0.1:8765/fin/free-holders?stocks=603233.SH&years=3"   # 十大流通股东: HOLDER_NAME/HOLD_RATIO
curl "http://127.0.0.1:8765/fin/holders?stocks=603233.SH&years=3"        # 十大股东明细: RANK/HOLDER_NAME/DIRECTION
curl "http://127.0.0.1:8765/fin/holder-num?stocks=603233.SH&years=3"     # 股东户数: HOLDER_TOTAL_NUM/户数增减

5. 使用注意事项

1. 只有 /fin/summary 需要 ORG_CODE：格式 代码:ORG_CODE（如 603233.SH:10500736）。ORG_CODE 是东财内部机构编码，只传代码时服务会尝试自动查询但不稳定；如果 400 报错提示 ORG_CODE，请改用 代码:ORG_CODE 格式，或换用 /fin/quarterly-summary。
2. 中文参数要 URL 编码：仅 classify_type（产品/地区）一处，浏览器或 curl 请编码后传。
3. 一次可查多只：stocks 用逗号分隔，返回多股合并数据（每行带 SECUCODE 区分）。
4. 列名不翻译：columns 与上游东财接口一致（英文大写，如 REPORT_DATE、TOTAL_ASSETS），data 每行是键值对象，值可能为 null。
5. 报告期：财务数据按报告期返回，REPORT_DATE/END_DATE 字段为 YYYY-MM-DD 格式（JSON 中是字符串）。
6. 频率：接口为实时抓取，没有缓存；高频批量调用请控制节奏。

6. 常见组合场景

任务	推荐调用
快速体检一家公司	quarterly-summary + main-business + profitability
深度财务分析	balance + income + cashflow + dupont
成长性判断	growth + quarterly-summary
分红投资	dividend-detail + dividend-statics
股东结构/筹码分析	holders + free-holders + holder-num