# dsh-tool-ths 协议与数据格式

本文档记录两个数据通道的协议细节与字段格式，全部经过实测验证（2026-08 环境）。
实现代码见 `lib/public.js` 与 `lib/ifind.js`；如需对接其他语言或自行调试，以
本文档为准。

## 1. public 通道 — 同花顺公开行情（免登录）

### 1.1 请求要求

- 域名：`http://d.10jqka.com.cn`（明文 HTTP；偶发 502，插件已重试）。
- 必须携带浏览器伪装请求头，否则会被拒绝/限流：

```
User-Agent: Mozilla/5.0 ... Chrome/124.0.0.0 Safari/537.36
Referer:    http://stockpage.10jqka.com.cn/
Cookie:     v=AAAAAAAAAAAA; hexin-v=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
```

- 响应为 JSONP：`callbackName({...})`，解析时取第一个 `(` 到最后一个 `)` 之间
  的 JSON。

### 1.2 K线接口

```
GET /v6/line/{market}_{code}/{period}/last.js
```

| 路径段 | 取值 | 说明 |
| --- | --- | --- |
| `market` | `hs`（沪深）/ `sz`（深）/ `bj`（北） | 见代码映射 |
| `code` | 6 位数字 | 如 `600519`、`000001`、`399001` |
| `period` | `01` 日线 / `11` 周线 / `12` 月线 / `41` 分钟线 | 插件仅开放 01/11/12 |

响应结构：

```json
{
  "year": { "2001": 86, "...": "..." },
  "total": "5985",
  "num": 140,
  "rt": "0930-1130,1300-1500",
  "start": "20010827",
  "name": "贵州茅台",
  "data": "20260120,1351.48,1353.56,1344.03,1345.53,3648443,5021900800.00,0.291,,,0;20260121,..."
}
```

`data` 每行 12 个字段，`;` 分隔：

| 序号 | 字段 | 单位 | 说明 |
| --- | --- | --- | --- |
| 1 | date | — | `YYYYMMDD` |
| 2-5 | open/high/low/close | 元 | 开高低收 |
| 6 | volume | **股** | 成交量（不是手） |
| 7 | amount | 元 | 成交额 |
| 8 | turnoverRate | % | 换手率 |
| 9 | — | — | 恒为空 |
| 10 | — | — | 特殊值（如大单量），非通用 |
| 11 | flag | — | 标志位，非通用 |

要点：

- 日线窗口约 **140 根**（最近 N 个交易日），周/月线约 **1260 根**；服务端固定，
  不可翻页/改数量。
- **当日 K 线在收盘后才落库**：盘中请求时最后一根是上一交易日，因此实时行情
  的当日 OHLC 不能取这里的最后一根（见 1.4）。
- 个别远古周线行存在坏值（如负价），`parseLineRows` 会丢弃 OHLC 非正的脏行。
- 沪市指数（`hs_999999` 等）返回 502，公开通道不支持；深市指数
  `sz_399001`（深证成指）、`sz_399006`（创业板指）可用。

### 1.3 分时接口

```
GET /v6/time/{market}_{code}/last.js
```

```json
{
  "hs_600519": {
    "name": "贵州茅台",
    "open": 0, "stop": 0, "isTrading": 0,
    "rt": "0930-1130,1300-1500,1505-1530",
    "tradeTime": ["0930-1130", "1300-1500", "1505-1530"],
    "pre": "1297.99",
    "date": "20260819",
    "data": "0930,1300.00,40950000,1300.000,31500;0931,1306.19,...;1530,1307.88,2484972,1298.828,1900.00"
  }
}
```

`data` 每行 5 个字段（**逐分钟**，非累计）：

| 序号 | 字段 | 说明 |
| --- | --- | --- |
| 1 | time | `HHMM` |
| 2 | price | 该分钟价格 |
| 3 | amount | **该分钟**成交额（元） |
| 4 | avgPrice | 截至该分钟的均价 |
| 5 | volume | **该分钟**成交量（股） |

顶层：`pre` 昨收、`date` 数据日期、`isTrading` 是否交易中。

### 1.4 实时行情合成规则（PublicClient.quote）

1. 昨收 = `pre`；最新价/均价 = 最后一分钟行的 price/avgPrice；
2. **当日 OHLC = 分时首分钟价 / 最高 / 最低 / 末分钟价**（盘中即当日实时值）；
3. **全日成交量/成交额 = 各分钟行求和**（盘中为截至当前累计）；
4. 涨跌/涨跌幅由「最新价 − 昨收」计算；
5. 日线仅用于兜底（分时为空时）与名称。

## 2. ifind 通道 — 官方 iFinD HTTP API

协议依据官方《iFinD HTTP API 用户手册》（版本号体现在 URL 中），主域
`quantapi.51ifind.com`（备用 `ft.10jqka.com.cn`），端口 80/443。

### 2.1 鉴权

**refresh_token**（长期，有效期同账号）：仅用于换取 access_token。获取途径：
iFinD 超级命令客户端「工具 → refresh_token 查询/更新」，或网页版超级命令
「账号详情」页。刷新 refresh_token 会使所有旧 token 失效。

**access_token**（短期，7 天）：用于取数。单个 access_token 最多绑定 20 个 IP。

```
POST https://quantapi.51ifind.com/api/v1/get_access_token
Headers: { "Content-Type": "application/json", "refresh_token": "<refresh_token>" }
Body:    {}（需有 Content-Length，否则服务端返回 "No Content Length"）

响应: { "data": { "access_token": "..." } }   （errorcode 非 0 表示失败）
```

- `update_access_token` 用于强制轮换（作废旧 token），插件不使用；
- 插件在内存缓存 access_token 至「7 天 − 1 小时」，失效自动重新换取；
- 每日换取次数有限（`-1305`），因此插件不会频繁登录。

### 2.2 取数请求

```
POST https://quantapi.51ifind.com/api/v1/{endpoint}
Headers: { "Content-Type": "application/json", "access_token": "<access_token>" }
Body:    JSON（字段见下）
```

统一响应：

```json
{
  "errorcode": 0,          // 0 成功；非 0 见错误码表
  "errmsg": "",
  "tables": [ { "thscode": "300033.SZ", "table": [["11.44", "11.62", ...]] } ],
  "datatype": "...",
  "inputParams": "...",
  "perf": "...",
  "dataVol": "..."
}
```

- `tables[].table` 每行是**字符串数组**，列顺序与请求的 indicators 一致；
  历史行情类的行首通常多一列日期（`rowsToObjects` 自动识别：行数 = 指标数 + 1
  且首字段不是日期字段时，把首列当作 `date`）。
- 通用成功/失败：`errorcode === 0`。token 相关错误码（-1010/-1003/-1300/
  -1301/-1302）触发插件自动重登 + 重试一次。

### 2.3 端点与参数

**real_time_quotation（实时行情）**

```json
{ "codes": "300033.SZ,600030.SH", "indicators": "open,high,latest,changeRatio" }
```

股票指标（部分）：`tradeDate` 交易日期、`tradeTime` 交易时间、`preClose` 前收、
`open/high/low/latest` 开高低最新、`avgPrice` 均价、`change/changeRatio` 涨跌
/幅、`totalShares` 总股本、`totalCapital` 总市值、`mv` 流通市值、`pe_ttm` 市盈
率TTM、`pb` 市净率、`pbr_lf` 市净率LF、`swing` 振幅、`vol_ratio` 量比、
`committee` 委比、`commission_diff` 委差、`riseDayCount` 连涨天数、
`suspensionFlag` 停牌、`tradeStatus` 交易状态、`lastest_price` 最新成交价、
`af_backward` 后复权因子。
⚠️ 本端点**没有** volume/amount/turnoverRatio；指数/基金/港股/期货期权另有专用
指标。**无成交量/成交额/换手率**。

**cmd_history_quotation（历史行情）**

```json
{
  "codes": "300033.SZ,600030.SH",
  "indicators": "open,close,volume",
  "startdate": "2024-08-25",
  "enddate": "2025-08-25",
  "functionpara": { "Interval": "W", "CPS": "3", "Currency": "RMB", "Fill": "Blank" }
}
```

- indicators 含：`preClose/open/high/low/close/avgPrice/change/changeRatio/
  volume/amount/turnoverRatio/transactionAmount/totalShares/totalCapital/
  floatSharesOfAShares/floatCapitalOfAShares/pe_ttm/pe/pb/ps/pcf/
  ths_trading_status_stock/ths_up_and_down_status_stock/ths_af_stock/...`
- functionpara：`Interval`（D日/W周/M月/Q季/S半年/Y年）、`SampleInterval` 抽样
  周期、`CPS` 复权（1 不复权 / 2 前复权分红再投 / 3 后复权分红再投 / 4 全流通
  前复权 / 5 全流通后复权 / 6 前复权现金分红 / 7 后复权现金分红）、`PriceType`
  债券全价/净价、`Fill` 非交易日处理（Previous/Blank/数值/Omit）、`BaseDate`
  复权基点、`Currency`（MHB/GHB/RMB/YSHB）。
- 日期支持 `YYYYMMDD` / `YYYY-MM-DD` / `YYYY/MM/DD` 三种。
- 区间限制（错误码 -4308~-4316）：免费/试用账号对区间跨度、数据量有上限。

**basic_data_service（基础财务数据）**

```json
{
  "codes": "300033.SZ,600030.SH",
  "indipara": [
    { "indicator": "ths_roe_stock", "indiparams": ["20241231"] },
    { "indicator": "ths_total_equity_atoopc_stock", "indiparams": [""] }
  ]
}
```

**get_trade_dates（交易日历）**

```json
{
  "marketcode": "212001",
  "functionpara": { "mode": "1", "dateType": "0", "period": "D", "dateFormat": "0" },
  "startdate": "2025-09-10",
  "enddate": "2025-09-10"
}
```

- marketcode：212001 上交所 / 212100 深交所 / 212200 港交所 / 212020001 中金所 /
  212020002 上金所 / 212020003 郑商所 / 212020004 大商所 / 212020008 上期所 /
  212010 纽交所 / 212011 NASDAQ 等。
- functionpara：`mode` 1 区间日期 / 2 区间日期数目；`dateType` 0 交易日 /
  1 日历日；`dateFormat` 0 `YYYY-MM-DD` / 1 `YYYY/MM/DD` / 2 `YYYYMMDD`；
  `period` D/W/M/Q/S/Y；`periodnum` 周期内偏移。

**report_query（公告）**

```json
{
  "codes": "300033.SZ,600000.SH",
  "functionpara": { "reportType": "901", "keyWord": "半年度报告" },
  "beginrDate": "2024-09-10",
  "endrDate": "2025-09-10",
  "outputpara": "reportDate:Y,thscode:Y,secName:Y,ctime:Y,reportTitle:Y,pdfURL:Y,seq:Y"
}
```

- reportType：903 全部 / 901002004 上市公告书 等；functionpara 还可按发布时间
  （begincTime/endcTime）、seq（beginSeq/endSeq）筛选。
- outputpara 字段：reportDate 公告日期 / thscode / secName 简称 / ctime 发布
  时间 / reportTitle 标题 / pdfURL 公告 PDF 链接 / seq 唯一标号。

**get_thscode（代码转换）**

```json
{ "seccode": "300033",
  "functionpara": { "mode": "seccode", "sectype": "", "market": "", "tradestatus": "0", "isexact": "0" } }
```

`mode` 为 `seccode`（行情代码）或 `secname`（证券简称）；`isexact` 0 模糊 /
1 精确。

### 2.4 常用错误码（官方手册摘录）

| 错误码 | 含义 | 处理建议 |
| --- | --- | --- |
| -1010 | token 已失效 | 插件自动重登重试 |
| -1300/-1301/-1302 | refresh/access token 无效 | 重新获取 refresh_token；更新后旧 token 全部作废 |
| -1303 | access_token 绑定超过 20 个 IP | 用 update_access_token 重置绑定 |
| -1305 | 当日换取 token 次数超限 | 等待次日；插件缓存 token 避免频繁换取 |
| -1202/-1203 | 参数错误/解析失败 | 检查 indicators 与参数格式 |
| -4203/-4204 | 请求格式/时间格式错误 | 检查日期与 JSON 结构 |
| -4206 | 含有错误的同花顺代码 | 用 ths_code 确认代码 |
| -4209 | 快照命令起止日期须同日 | 修正区间 |
| -4211 | 区间内无交易日 | 换区间 |
| -4212 | 区间早于上市日 | 换区间 |
| -4301/-4302/-4303 | 周数据量超限（基础/行情/EDB） | 减小取数范围 |
| -4305/-4306/-4312 | 单条命令数据量过大 | 减小范围/代码数 |
| -4308~-4316 | 区间跨度超限（3月/6月/1年/3年） | 缩小区间 |
| -4317/-4318 | 周/月数据量超限 | 等额度恢复 |
| -4320 | 账户须使用对应客户端 | 按提示使用对应客户端 |
| -4321/-4319/-4322 | 免费账号单次/单条限制 | 升级或缩小范围 |
| -4400 | 每分钟请求超 600 条 | 降频 |

## 3. 与官方 SDK 的差异说明

- 官方 Windows/Linux SDK（iFinDPy / ThsJDI）走本地动态库 + 超级命令客户端，
  HTTP 接口是其无 SDK 的替代方案，鉴权模型相同（refresh_token 体系）。
- 本插件的 iFinD 实现为纯 HTTP（无本地依赖），与官方「HTTP 接口使用说明」
  一致；指标名与 SDK 兼容（`ths_*` 前缀指标均可在 basic_data_service 使用）。