# EMWeb API 接口文档

> 东方财富 CHOICE 数据抓取服务 HTTP 接口使用说明。对应目前已实现的功能，随版本更新。

## 基本信息

| 项 | 值 |
|---|---|
| 服务名称 | EMWeb API |
| 版本 | 0.1.0 |
| 默认地址 | `http://127.0.0.1:8765` |
| 数据源 | 东方财富 CHOICE 公开接口（无需登录/cookie） |
| Swagger | `http://127.0.0.1:8765/docs` |

启动：

```bash
uv run python api.py   # 监听 0.0.0.0:8765
```

## 通用说明

### 返回结构

所有 `/fin/*` 接口成功时返回统一结构：

```json
{
  "success": true,
  "count": 10,
  "columns": ["SECUCODE", "REPORT_DATE", "..."],
  "data": [ { "SECUCODE": "603233.SH", "..." }, "..." ],
  "codes_requested": ["603233.SH"],
  "years": 3
}
```

| 字段 | 说明 |
|---|---|
| `success` | 是否成功 |
| `count` | 数据行数 |
| `columns` | 数据列名（与上游接口返回一致，不做翻译） |
| `data` | 数据行数组；空值/NaN/NaT/±inf 统一转 `null` |
| 其余字段 | 回显本次请求参数，便于排查 |

### 错误

| HTTP 状态 | 场景 |
|---|---|
| `400` | 参数不合法（如 `stocks` 为空） |
| `404` | 请求成功但无数据（`success: false`，`data: []`） |
| `5xx` | 上游接口异常（超时、返回失败等） |

### 股票代码格式

统一使用 `代码.市场`，如 `603233.SH`（上交所）/ `000001.SZ`（深交所）。多只股票用英文逗号分隔。

---

## 1. GET /health — 健康检查

**参数**：无

**响应**：

```json
{ "status": "ok" }
```

---

## 2. GET /fin/summary — 财务摘要（报告期）

拉取多只股票的财务摘要指标（报告期口径，单季度数据请用 `/fin/quarterly-summary`）。

**参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票列表。两种写法：① 仅代码 `603233.SH`（自动查 ORG_CODE，不稳定）；② `代码:ORG_CODE`，如 `603233.SH:10500736`（推荐，最稳） |
| `years` | int | | `10` | 拉取多少年历史（1~20） |
| `date_type_codes` | string | | `1,5,6` | 报告期代码，逗号分隔：`1`=一季报，`5`=中报，`6`=年报 |
| `is_newest` | bool | | `true` | 是否只要最新合并报表 |

**示例**

```bash
curl "http://127.0.0.1:8765/fin/summary?stocks=603233.SH:10500736&years=5&date_type_codes=1,5,6"
```

**说明**

- ORG_CODE 无法从公开接口稳定自动获取，推荐在抓包时记录（如大参林 `603233.SH` → `10500736`）。
- 只传代码时自动查询失败会返回 `400` 并提示改用 `代码:ORG_CODE` 格式。

---

## 3. GET /fin/quarterly-summary — 财务摘要（单季度）

拉取多只股票的季度财务摘要，数据按 `SECUCODE + REPORT_DATE` 去重并倒序排列。

**参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH,600519.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `3` | 未传 `report_dates` 时，拉取最近多少年的季度数据（1~20） |
| `report_dates` | string | | 无 | 可选，逗号分隔的报告期 `YYYY-MM-DD`，如 `2025-03-31,2024-12-31`；传入时精确筛选 |

**示例**

```bash
# 最近 3 年全部季度
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&years=3"

# 精确指定报告期
curl "http://127.0.0.1:8765/fin/quarterly-summary?stocks=603233.SH&report_dates=2025-03-31,2024-12-31"
```

---

## 4. GET /fin/main-business — 主营构成（按产品 / 按地区）

拉取多只股票的主营构成，可分别按产品分类或按地区分类。

**参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `classify_type` | string | | `产品` | 分类方式：`产品` 或 `地区` |
| `years` | int | | `3` | 拉取最近多少年数据（1~20） |

**示例**

```bash
# 按产品分类（中文参数建议 URL 编码：产品=%E4%BA%A7%E5%93%81）
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E4%BA%A7%E5%93%81&years=3"

# 按地区分类（地区=%E5%9C%B0%E5%8C%BA）
curl "http://127.0.0.1:8765/fin/main-business?stocks=603233.SH&classify_type=%E5%9C%B0%E5%8C%BA&years=3"
```

**返回数据常见列**

| 列名 | 说明 |
|---|---|
| `SECUCODE` | 股票代码 |
| `CLASSIFY_TYPE` | 分类方式（产品/地区） |
| `STD_REPORT_NAME` | 分类名（如产品名/地区名，含"合计"行） |
| `ReportDate` | 报告期（`YYYY-MM-DD HH:MM:SS`） |
| `MAIN_BUSINESS_INCOME` | 主营业务收入 |
| `MAIN_BUSINESS_COST` | 主营业务成本 |
| `MAIN_BUSINESS_RPOFIT` | 主营业务利润 |
| `GROSS_RPOFIT_RATIO` | 毛利率（%） |
| `MBI_RATIO` | 占主营业务收入比（%） |
| `MBR_RATIO` | 占主营业务利润比（%） |
| `IS_MAXREPORTDATE` | 是否最新报告期（`1`=是） |

---

## 5. 财务报表（资产负债表 / 利润表 / 现金流量表）

**公共参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `3` | 拉取最近多少年的数据（1~20） |

**示例**

```bash
# 资产负债表
curl "http://127.0.0.1:8765/fin/balance?stocks=603233.SH&years=3"

# 利润表
curl "http://127.0.0.1:8765/fin/income?stocks=603233.SH&years=3"

# 现金流量表
curl "http://127.0.0.1:8765/fin/cashflow?stocks=603233.SH&years=3"
```

**说明**：数据为按报告期的明细科目，列数较多（资产负债表约 160+ 列，利润表约 80+ 列，现金流量表约 140 列），列名与上游接口一致（如 `TOTAL_ASSETS`、`TOTAL_OPERATE_INCOME`、`SALES_SERVICES`）。

---

## 6. 财务分析指标（盈利能力 / 资本结构 / 营运能力 / 成长能力 / 杜邦）

**公共参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `3` | 拉取最近多少年的数据（1~20） |

**示例**

```bash
# 盈利能力与收益质量 (ROE/ROA/毛利率等)
curl "http://127.0.0.1:8765/fin/profitability?stocks=603233.SH&years=3"

# 资本结构与偿债能力 (资产负债率/流动比率等)
curl "http://127.0.0.1:8765/fin/capital-structure?stocks=603233.SH&years=3"

# 营运能力 (周转天数/周转率等)
curl "http://127.0.0.1:8765/fin/operate-ability?stocks=603233.SH&years=3"

# 成长能力 (营收/净利同比等)
curl "http://127.0.0.1:8765/fin/growth?stocks=603233.SH&years=3"

# 杜邦分析 (ROE 拆解)
curl "http://127.0.0.1:8765/fin/dupont?stocks=603233.SH&years=3"
```

**各接口常见列**

| 接口 | 常见列 |
|---|---|
| 盈利能力 | `ROE_AVERAGE`（平均净资产收益率）、`ROE_DILUTED`（摊薄）、`ROA`、`ROIC`、`SALE_GPR`（毛利率）等 |
| 资本结构 | `DEBT_ASSET_RATIO`（资产负债率）、`CURRENT_RATIO`（流动比率）、`SPEED_RATIO`（速动比率）等 |
| 营运能力 | `OPERATE_CYCLE`（营业周期）、`INVENTORY_DAYS`（存货周转天数）、`ACCOUNTS_RECE_DAYS` 等 |
| 成长能力 | `BASICEPS_YOY`、`TOTAL_OPERATEINCOME_YOY`（营收同比）、`PARENT_NETPROFIT_YOY`（净利同比）等 |
| 杜邦 | `ROE`、`NETPROFIT`、`TOTAL_ASSETS`、`EQUITY_MULTIPLIER`（权益乘数）、`NETPROFIT_TOI` 等 |

---

## 7. 分红（明细 / 统计）

**公共参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `5` | 拉取最近多少年的分红数据（1~20） |

**示例**

```bash
# 分红明细 (含方案/股权登记日/除权除息日等)
curl "http://127.0.0.1:8765/fin/dividend-detail?stocks=603233.SH&years=5"

# 分红统计 (按年汇总, 含股息率/分红率等)
curl "http://127.0.0.1:8765/fin/dividend-statics?stocks=603233.SH&years=5"
```

**各接口常见列**

| 接口 | 常见列 |
|---|---|
| 分红明细 | `IMPL_PLAN_PROFILE`（方案）、`ASSIGN_PROGRESS`（进度）、`PRETAX_BONUS_RMB`（每股税前）、`EX_DIVIDEND_DATE`（除权除息日）、`PAY_CASH_DATE` 等 |
| 分红统计 | `AUALACCMDIV_ARD`（每股股利）、`PARENTNETPROFIT`、`GXL`（股息率）、`SUM_AUALACCMDIV_ARD` 等 |

---

## 8. 股东数据（十大流通股东 / 十大股东明细 / 股东户数）

**公共参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `3` | 拉取最近多少年的数据（1~20） |

**示例**

```bash
# 十大流通股东
curl "http://127.0.0.1:8765/fin/free-holders?stocks=603233.SH&years=3"

# 十大股东明细
curl "http://127.0.0.1:8765/fin/holders?stocks=603233.SH&years=3"

# 股东户数
curl "http://127.0.0.1:8765/fin/holder-num?stocks=603233.SH&years=3"
```

**各接口常见列**

| 接口 | 常见列 |
|---|---|
| 十大流通股东 | `HOLDER_NAME`（股东名）、`HOLD_NUM`（持股数）、`HOLD_RATIO`、`FREE_HOLDNUM_RATIO`（占流通股比）、`HOLD_CHANGE` 等 |
| 十大股东明细 | `RANK`（排名）、`HOLDER_NAME`、`HOLD_NUM`、`HOLD_RATIO`、`DIRECTION`（增减持方向）、`NOTICE_DATE` 等 |
| 股东户数 | `HOLDER_TOTAL_NUM`（股东总数）、`HOLDER_TOTAL_NUMCHANGE`（户数增减）、`AVG_TOTAL_SHARES`（户均持股）等 |

---

## 9. 公司资料 / 股本 / 指数

以下接口均只需 `stocks` 参数（无 `years`，返回全量），公司介绍每只 1 行。

**示例**

```bash
# 公司介绍 (基本资料: 注册资本/董事长/行业等)
curl "http://127.0.0.1:8765/fin/company-info?stocks=603233.SH"

# 股本结构 (各报告期末股本变动全量历史)
curl "http://127.0.0.1:8765/fin/equity?stocks=603233.SH"

# 所属行业 (当前生效的行业分类)
curl "http://127.0.0.1:8765/fin/industry?stocks=603233.SH"

# 所属指数分类
curl "http://127.0.0.1:8765/fin/index-classif?stocks=603233.SH"

# 纳入指数统计 (指数/基金数量)
curl "http://127.0.0.1:8765/fin/belong-index?stocks=603233.SH"

# 指数成分权重 (纳入主要指数的权重)
curl "http://127.0.0.1:8765/fin/index-membership?stocks=603233.SH"
```

**各接口常见列**

| 接口 | 常见列 |
|---|---|
| 公司介绍 | `ORG_NAME`（公司全称）、`FOUND_DATE`、`REG_CAPITAL`、`LISTING_DATE`、`CHAIRMAN`、`PRESIDENT`、`INDUSTRYCSRC1` 等 |
| 股本结构 | `END_DATE`、`CHANGE_REASON`（变动原因）、`LIMITED_SHARES`（限售股）、`UNLIMITED_SHARES`、`TOTAL_SHARES` 等 |
| 所属行业 | `INDUSTRY_TYPE`（行业类型）、`INDUSTRY_NAME`、`INDUSTRY_CODE`、`ENTRY_DATE` 等 |
| 指数分类 | `INDEX_CLASSIF_CODE`、`INDEX_CLASSIF` |
| 纳入指数统计 | `INDEX_NUM`（指数数量）、`INDEX_FUND_NUM`、`FUND_NUM`、`FUND_TOTAL_SCALE` 等 |
| 指数成分权重 | `INDEX_NAME_ABBR`（指数名）、`INDEX_CLASSIF`、`WEIGHT`（权重）、`NUM`、`INCLUDE_DATE` 等 |

---

## 10. 管理层讨论与分析（MD&A）

年报/中报的董事会报告索引（含标题与页码），默认拉最近 5 年。

**参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH` |
| `years` | int | | `5` | 拉取最近多少年的报告（1~20） |

**示例**

```bash
curl "http://127.0.0.1:8765/fin/mda?stocks=603233.SH&years=5"
```

**常见列**：`REPORT_DATE`、`REPORT_NAME`（年报/中报）、`NOTICE_DATE`、`TITLE`（标题）、`PAGE`（页码）、`RELINFOCODE`（报告关联编码）。

---

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

**公共参数**

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `stocks` | string | ✅ | — | 逗号分隔股票代码，如 `603233.SH`。仅需代码，不需要 ORG_CODE |
| `years` | int | | `3` | 拉取最近多少年的数据（1~20） |

**示例**

```bash
# 并购事件
curl "http://127.0.0.1:8765/fin/acquisitions?stocks=603233.SH&years=3"

# 股权激励 (部分股票可能无数据, 如无记录返回 404)
curl "http://127.0.0.1:8765/fin/equity-incentive?stocks=603233.SH&years=3"

# 诉讼仲裁
curl "http://127.0.0.1:8765/fin/litigation?stocks=603233.SH&years=3"

# 关联交易
curl "http://127.0.0.1:8765/fin/related-transaction?stocks=603233.SH&years=3"

# 违规处罚
curl "http://127.0.0.1:8765/fin/violation?stocks=603233.SH&years=3"

# 对外担保 (部分股票可能无数据)
curl "http://127.0.0.1:8765/fin/guarantee?stocks=603233.SH&years=3"
```

**各接口常见列**

| 接口 | 常见列 |
|---|---|
| 并购 | `PLAN_PROCESS`（进展）、`NAME_OBJ`（标的）、`NAME_BUY`（收购方）、`DEAL_AMT`（交易金额）、`TRANSFER_RATIO` 等 |
| 股权激励 | `PLAN_PROCESS`、`EI_TARGET`（对象）、`EI_WAY`（方式）、`TOTAL_INCENTIVE_SHARES`、`INITIAL_EXERCISE_PRICE`（行权价）等 |
| 诉讼仲裁 | `CASE_NAME`（案件名）、`CASE_PROFILE`、`PLAINTIFF`、`DEFENCE`、`CASE_AMOUNT`（涉诉金额）、`LITIGATION_TYPE` 等 |
| 关联交易 | `RELATED_PARTY`（关联方）、`RELATED_RELATION`（关系）、`TRADE_AMT`（金额）、`TRADE_PROFILE` 等 |
| 违规 | `VIOLATE_TYPE`（违规类型）、`PUNISH_TYPE`（处罚类型）、`PUNISH_AMT`、`SOLVE_ORG`（处理机构）等 |
| 担保 | `GUAR_NAME`（担保方）、`GUARANTEED_NAME`（被担保方）、`GUARANTEE_AMT`、`GUARANTEE_WAY`、`IS_RELATED_TRADE` 等 |

---

## 接口一览

| 路径 | 功能 | 数据来源报表 |
|---|---|---|
| `/health` | 健康检查 | — |
| `/fin/summary` | 财务摘要（报告期） | `RPT_CUSTOM_ORGF9_FIN_SUMMARY` |
| `/fin/quarterly-summary` | 财务摘要（单季度） | `RPT_HSF9_FIN_SUMMARYQUARTERNEW` |
| `/fin/main-business` | 主营构成（产品/地区） | `ZYGC_AFLZS` → `RPT_HSF9_FN_MAINOPBUSINESS` |
| `/fin/balance` | 资产负债表 | `CWSJ_ZCFZB` → `RPT_CUSTOM_HSF9_FINA_GBALANCE` |
| `/fin/income` | 利润表 | `CWSJ_LRB` → `RPT_CUSTOM_HSF9_FINA_GINCOMESYN` |
| `/fin/cashflow` | 现金流量表 | `CWSJ_XJLLB` → `RPT_CUSTOM_HSF9_FINA_GCASHFLOW` |
| `/fin/profitability` | 盈利能力与收益质量 | `CWFX_YLNLYSYZL` → `RPT_HSF9_FINA_PROFITEARNING` |
| `/fin/capital-structure` | 资本结构与偿债能力 | `CWFX_ZBJGYCZNL` → `RPT_HSF9_FINA_CAPPAYAB` |
| `/fin/operate-ability` | 营运能力 | `RPT_HSF9_FINA_OPERATEABILITY` |
| `/fin/growth` | 成长能力 | `CWFX_CZNL` → `RPT_HSF9_FINA_GROWTH` |
| `/fin/dupont` | 杜邦分析 | `RPT_HSF9_FINA_DUPONT` |
| `/fin/dividend-detail` | 分红明细 | `RPT_HSF9_ASSIGNPLAN_DETAIL` |
| `/fin/dividend-statics` | 分红统计 | `RPT_HSF9_ASSIGNPLAN_STATICS` |
| `/fin/free-holders` | 十大流通股东 | `RPT_F10_EH_FREEHOLDERS` |
| `/fin/holders` | 十大股东明细 | `RPT_DMSK_HOLDERS` |
| `/fin/holder-num` | 股东户数 | `RPT_F10_EH_HOLDERNUM` |
| `/fin/mda` | 管理层讨论与分析 | `RPT_BUSINESSANALYSIS` |
| `/fin/equity` | 股本结构 | `RPT_F10_EH_EQUITY` |
| `/fin/company-info` | 公司介绍 | `RPT_HSF9_BASIC_ORGINFO` |
| `/fin/industry` | 所属行业 | `RPT_STOCKF9_INDUSTRY` |
| `/fin/index-classif` | 所属指数分类 | `RPT_HSF9_BELONGINDEX_CLASSIF` |
| `/fin/belong-index` | 纳入指数统计 | `RPT_CUSTOM_HSF9_BELONG_INDEX` |
| `/fin/index-membership` | 指数成分权重 | `RPT_HSF9_BELONG_INDEX` |
| `/fin/acquisitions` | 并购事件 | `RPT_HS_ACQUISITIONS_EVENT` |
| `/fin/equity-incentive` | 股权激励 | `RPT_DMSK_SH_EQUITYINCENTIVE` |
| `/fin/litigation` | 诉讼仲裁 | `RPT_LITIGATION_ARBITRATION_BSINFO` |
| `/fin/related-transaction` | 关联交易 | `RPT_RELATED_TRANSACTION` |
| `/fin/violation` | 违规处罚 | `RPT_HSF9_OP_VIOLATION` |
| `/fin/guarantee` | 对外担保 | `RPT_F9_GUARANTEE` |

## 测试

```bash
uv run pytest tests/ -q   # 冒烟测试: 连真实接口验证各模块能取到数据 (56 用例)
```