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	股东户数
资料	GET /fin/company-info	公司介绍（基本资料）
资料	GET /fin/industry	所属行业
资料	GET /fin/equity	股本结构（全量历史）
指数	GET /fin/index-classif	所属指数分类
指数	GET /fin/belong-index	纳入指数统计
指数	GET /fin/index-membership	指数成分权重
文本	GET /fin/mda	管理层讨论与分析（年报/中报索引）
重大事项	GET /fin/acquisitions	并购事件
重大事项	GET /fin/equity-incentive	股权激励
重大事项	GET /fin/litigation	诉讼仲裁
重大事项	GET /fin/related-transaction	关联交易
重大事项	GET /fin/violation	违规处罚
重大事项	GET /fin/guarantee	对外担保

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/户数增减

4.8 公司资料 / 股本 / 指数（无 years 参数，返回全量）

curl "http://127.0.0.1:8765/fin/company-info?stocks=603233.SH"      # 公司介绍(每只1行): ORG_NAME/CHAIRMAN/REG_CAPITAL
curl "http://127.0.0.1:8765/fin/industry?stocks=603233.SH"           # 所属行业: INDUSTRY_NAME
curl "http://127.0.0.1:8765/fin/equity?stocks=603233.SH"             # 股本结构: TOTAL_SHARES/CHANGE_REASON
curl "http://127.0.0.1:8765/fin/index-classif?stocks=603233.SH"      # 指数分类: INDEX_CLASSIF
curl "http://127.0.0.1:8765/fin/belong-index?stocks=603233.SH"       # 纳入指数统计: INDEX_NUM
curl "http://127.0.0.1:8765/fin/index-membership?stocks=603233.SH"   # 指数成分权重: INDEX_NAME_ABBR/WEIGHT

4.9 管理层讨论与分析

curl "http://127.0.0.1:8765/fin/mda?stocks=603233.SH&years=5"   # 年报/中报索引: REPORT_NAME/TITLE/PAGE

4.10 重大事项（并购 / 股权激励 / 诉讼 / 关联交易 / 违规 / 担保）

curl "http://127.0.0.1:8765/fin/acquisitions?stocks=603233.SH"          # 并购: NAME_OBJ/DEAL_AMT
curl "http://127.0.0.1:8765/fin/equity-incentive?stocks=603233.SH"      # 股权激励(部分股票无记录→404)
curl "http://127.0.0.1:8765/fin/litigation?stocks=603233.SH"            # 诉讼: CASE_NAME/CASE_AMOUNT
curl "http://127.0.0.1:8765/fin/related-transaction?stocks=603233.SH"   # 关联交易: RELATED_PARTY/TRADE_AMT
curl "http://127.0.0.1:8765/fin/violation?stocks=603233.SH"             # 违规: VIOLATE_TYPE/PUNISH_AMT
curl "http://127.0.0.1:8765/fin/guarantee?stocks=603233.SH"             # 担保(部分股票无记录→404)

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. 频率：接口为实时抓取，没有缓存；高频批量调用请控制节奏。
7. 无 years 的接口：company-info / industry / equity / index-classif / belong-index / index-membership 只收 stocks，返回全量。
8. 部分股票可能查不到：股权激励、担保等记录并非所有股票都有，此类接口对该股返回 404（success:false）是正常现象，不代表接口故障。

6. 常见组合场景

任务	推荐调用
快速体检一家公司	quarterly-summary + main-business + profitability
深度财务分析	balance + income + cashflow + dupont
成长性判断	growth + quarterly-summary
分红投资	dividend-detail + dividend-statics
股东结构/筹码分析	holders + free-holders + holder-num
公司底细	company-info + industry + equity + mda
风险排查	litigation + violation + guarantee + related-transaction
指数/权重	index-classif + belong-index + index-membership