# API 接口参考

## 认证

所有 API 请求需要在 Header 中携带 API Key：

```
X-API-Key: sk_live_xxx
```

## 响应格式

**成功响应**：
```json
{
  "code": 0,
  "msg": "success",
  "data": { ... }
}
```

**错误响应**：
```json
{
  "code": 40001,
  "msg": "错误信息",
  "data": { ... }
}
```

## 错误码

| 错误码 | HTTP 状态 | 说明 |
|--------|----------|------|
| 0 | 200 | 成功 |
| 40001 | 400 | 参数错误 |
| 40101 | 401 | API Key 无效 |
| 40102 | 401 | API Key 已过期 |
| 42901 | 429 | 超出每分钟请求限制 |
| 42902 | 429 | 超出每日配额 |
| 50001 | 500 | 服务器内部错误 |
| 50201 | 502 | 上游服务错误 |

---

## 资讯搜索

按关键词、来源和时间范围搜索新闻资讯。

### 请求

```
POST /v1/news/search
```

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| keywords | string | 是 | - | 搜索关键词，多个以空格分隔 |
| makeDateStart | string | 是 | - | 开始时间，格式：YYYY-MM-DD HH:mm:ss |
| makeDateEnd | string | 否 | - | 结束时间，格式：YYYY-MM-DD HH:mm:ss |
| source | string | 否 | - | 资讯来源，多个以空格分隔 |
| limit | int | 否 | 20 | 返回数量 |

### 请求示例

```json
{
  "keywords": "贵州茅台 茅台",
  "makeDateStart": "2026-03-20 00:00:00",
  "makeDateEnd": "2026-03-23 23:59:59",
  "source": "财联社 证券时报",
  "limit": 50
}
```

### 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| count | int | 实际返回数量 |
| items | NewsItem[] | 资讯列表 |
| truncated | bool | 是否被截断（可选，仅截断时出现） |

**NewsItem 对象**：

| 字段 | 类型 | 说明 |
|------|------|------|
| title | string | 资讯标题 |
| makeDate | string | 发布时间 |
| source | string | 来源 |
| url | string | 原文链接 |
| summary | string | 摘要 |

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "count": 15,
    "items": [
      {
        "title": "贵州茅台发布年度业绩预告",
        "makeDate": "2026-03-22 18:30:00",
        "source": "财联社",
        "url": "https://www.cls.cn/article/123456",
        "summary": "贵州茅台预计2025年实现营业收入1800亿元，同比增长15%..."
      }
    ]
  }
}
```

> **注意**：当响应中包含 `truncated: true` 时，表示可能有更多数据未返回。建议调整 `limit` 或缩小查询范围。

---

## 研报搜索

按发布日期和摘要关键词搜索研究报告。

### 请求

```
POST /v1/news/reports
```

### 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| keywords | string | 是 | - | 摘要关键词，多个以空格分隔 |
| declareDateStart | string | 是 | - | 发布日期起始，格式：YYYY-MM-DD HH:mm:ss |
| limit | int | 否 | 20 | 返回数量 |

### 请求示例

```json
{
  "keywords": "人工智能 大模型",
  "declareDateStart": "2026-03-01 00:00:00",
  "limit": 30
}
```

### 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| count | int | 实际返回数量 |
| items | ReportItem[] | 研报列表 |
| truncated | bool | 是否被截断（可选，仅截断时出现） |

**ReportItem 对象**：

| 字段 | 类型 | 说明 |
|------|------|------|
| declareDate | string | 发布日期 |
| orgName | string | 研究机构名称 |
| title | string | 研报标题 |
| abstract | string | 研报摘要 |

### 响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "count": 8,
    "items": [
      {
        "declareDate": "2026-03-20 00:00:00",
        "orgName": "中信证券",
        "title": "人工智能行业深度报告：大模型开启新纪元",
        "abstract": "本报告深入分析了人工智能行业的发展趋势..."
      }
    ]
  }
}
```

> **注意**：当响应中包含 `truncated: true` 时，表示可能有更多数据未返回。建议调整 `limit` 或缩小查询范围。

---

## 资讯来源列表

以下是常用的资讯来源：

| 来源 | 类型 | 说明 |
|------|------|------|
| 财联社 | 财经媒体 | 实时财经快讯，时效性强 |
| 金十数据 | 财经媒体 | 金融市场快讯 |
| 证券时报 | 官方媒体 | 权威财经报道 |
| 中国证券报 | 官方媒体 | 权威财经报道 |
| 上海证券报 | 官方媒体 | 权威财经报道 |
| 证券日报 | 官方媒体 | 权威财经报道 |

### 来源筛选示例

```bash
# 只看财联社和金十数据
--source="财联社 金十数据"

# 只看官方媒体
--source="证券时报 中国证券报 上海证券报 证券日报"
```

---

## 时间格式

所有时间参数使用统一格式：

```
YYYY-MM-DD HH:mm:ss
```

示例：
- `2026-03-20 00:00:00` - 2026年3月20日零点
- `2026-03-23 23:59:59` - 2026年3月23日最后一秒

### 时间范围建议

| 场景 | 建议时间范围 |
|------|-------------|
| 追踪热点事件 | 1-3 天 |
| 公司动态跟踪 | 7-14 天 |
| 行业研究 | 30-90 天 |
| 历史事件回顾 | 按需设置 |

---

## 最佳实践

### 1. 关键词设置

- 使用**空格分隔**多个关键词
- 关键词之间是**OR关系**（匹配任一即可）
- 建议包含公司名称的不同写法（如"贵州茅台 茅台"）

### 2. 时间范围

- 时间范围越大，返回结果越多
- 建议根据需求设置合适的时间范围
- 研报通常按月或季度搜索

### 3. 来源筛选

- 追求时效性：选择"财联社 金十数据"
- 追求权威性：选择官方媒体
- 不指定来源则搜索全部来源