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.
139 lines
6.2 KiB
139 lines
6.2 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` | 股东户数 |
|
|
|
|
## 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/户数增减
|
|
```
|
|
|
|
## 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` |
|
|
|