You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
185 lines
9.1 KiB
185 lines
9.1 KiB
# 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` |
|
|
|