# 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。 - **返回结构**（成功）： ```json { "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 快速探活 ```bash curl "http://127.0.0.1:8765/health" # => {"status":"ok"} ``` ### 4.2 财务摘要 ```bash # 单季度 (只需代码) —— 适合拿季度经营数据 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 主营构成 ```bash # 按产品分类 (中文参数需要 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 三张财务报表 ```bash 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 财务指标（四大分析 + 杜邦） ```bash 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 分红 ```bash 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 股东数据 ```bash 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 参数，返回全量） ```bash 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 管理层讨论与分析 ```bash curl "http://127.0.0.1:8765/fin/mda?stocks=603233.SH&years=5" # 年报/中报索引: REPORT_NAME/TITLE/PAGE ``` ### 4.10 重大事项（并购 / 股权激励 / 诉讼 / 关联交易 / 违规 / 担保） ```bash 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` |