# REST API 契约

本 Skill 内置契约是“同花顺金融数据服务”的 REST API 文档入口，面向 HTTP 调用者、SDK/CLI 维护者和 AI Agent。接口正文从文档源确定性同步，按业务域与模块定位接口。

查找具体接口优先使用本地业务路由。

## 通用约定

以下约定适用于本目录接口；具体参数、字段单位和业务限制以接口页为准。实际请求前读取本节一次。

| 项目 | 契约 |
| --- | --- |
| Base URL | `https://fuyao.aicubes.cn` |
| 方法 | 当前公开数据端点均为 `GET` |
| 认证 | HTTP Header `X-api-key: <API_KEY>` |
| 成功判断 | HTTP 200 且响应 `code == 0` |
| 响应信封 | `{code, message, request_id, data}` |
| 标的代码 | 完整 `thscode`，例如 `600519.SH`；不要猜交易所后缀 |
| 时间戳 | 毫秒 Unix 时间戳；具体日期字符串格式以端点页为准 |
| 时区 | 日期和交易日窗口按 `Asia/Shanghai` 解释 |
| 空值 | `null` 表示未披露或上游无值，不得自动补零 |

`data` 字段始终存在：成功时承载端点数据，业务错误时为 `null`。历史及财报批量接口按代码返回有效目标组，合法空组保留 `timestamp:null,item:[]`；部分无效目标省略其组且外层 `code=0`。调用方应检查外层 `code` 并使用返回的有效组。

响应记录中的同花顺代码（如 `thscode`）无法确定时可为 `null`。调用方应保留代码字段、原记录、业务值、顺序与分页信息。

获取统一 API Key：<https://fuyao.aicubes.cn/admin/>。用户可以把 Key 提供给 Agent 上下文以便代配；Agent 不复述，并提示聊天平台可能保留消息记录。Key 不得写入代码、日志、公开配置或 Git 提交。

最小请求：

```bash
curl 'https://fuyao.aicubes.cn/api/meta/tickers/search?q=600519&limit=1' \
  -H 'X-api-key: <API_KEY>'
```

## 按业务选择接口

- [公共基础数据](api/meta/README.md)：标的目录与搜索、交易日历和交易时段。
- 股票数据
  - [A 股](api/a-share/README.md)：股票价格、财务、估值、竞价与特色数据。指数走势进入指数域，基金净值进入基金域。
  - [港股](api/hk-share/README.md)：新股递表、认购与上市日历、发行价格区间及每手股数。
- [指数与板块](api/index/README.md)：指数和板块目录、成分股、行情。先目录或搜索，再查成分与价格。
- [公募基金](api/fund/README.md)：净值与场内成交价格分别进入业绩与行情；最新披露与历史持仓分别选择对应接口。
- [期货](api/futures/README.md)：先确定品种或合约，再查询持仓、仓单、基差、交易日程与行情。
- [期权](api/options/README.md)：期权品种、合约与行情；按完整合约代码定位。
- [资讯事件](api/news/README.md)：资讯详情、快讯、公告解读、热门专题、日期范围异动解读与个股分时新闻；事件检索按端内范围使用。

[全市场数据导出](api/market-dumps.md)

## 端内能力说明

标记为“端内专用”的数据能力已内置于同花顺AI客户端，可在客户端中免配置使用；这些接口不作为公开 REST API、MCP、CLI 或 Python SDK 的接入入口。

- 接口文档可用于理解参数与字段；API Key 不赋予端内专用能力的调用权限。
- 用户需要端内数据时，说明公开接入边界，并提供[同花顺AI客户端入口](https://lumi.10jqka.com.cn/?channel=Hithink-API)。
- 选择公开替代接口时，先确认其数据范围、频率与时间覆盖满足需求。

## 错误处理

所有响应先检查 `code`。HTTP 200 不代表业务成功。

| `code` | 含义 | 调用方处理 |
| --- | --- | --- |
| `0` | 成功 | 使用 `data` |
| `1001` | 缺少必填参数 | 补齐参数，不重试原请求 |
| `1002` | 参数格式无效 | 规范化代码、枚举、日期或时间戳 |
| `1003` | 参数超出范围 | 缩小分页或拆分允许拆分的时间窗口 |
| `1004` | 参数冲突 | 按端点互斥规则重组参数 |
| `2001` | 未认证 | 检查 `X-api-key` 是否存在且格式正确 |
| `2003` | 无权限或 Key 无效 | 前往 API Key 管理页检查授权或重新签发 |
| `2004` | 当前凭据未获该能力授权 | 按接口使用范围选择可用能力，保留请求标识供排查 |
| `3001` | 标的不存在 | 先通过元信息端点消歧并核对资产类别与 `thscode` |
| `3002` | 数据尚未准备 | 保留 `request_id` 与口径，稍后再查，不得补零或使用模拟数据 |
| `3004` | 目标类型不支持该能力 | 选择适用于该资产类型的端点，不重试原请求 |
| `4001` | 限流 | 指数退避，最多重试 3 次 |
| `5001`/`5002`/`5003` | 服务端或上游异常 | 退避重试；持续失败时保留 `request_id` |

`1xxx` 和 `2xxx` 属于调用方可修复错误，不应无条件重试。网络错误、`4001` 和 `5xxx` 可在有界次数内退避重试。

## 大结果规则

全市场、分页全集、多标的或多年数据必须落盘。调用者只在终端或对话中报告文件路径、行数、时间窗口和摘要，不展开原始结果。全市场历史建库优先使用 [Market Dumps](api/market-dumps.md)，不要逐标的请求多年 REST 数据。

## 维护规则

接口正文随源文档同步更新，业务索引负责选路，各接入方式按需链接接口页。Market Dumps 的 API Key 下载契约由本项目维护。
