> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/rest-api/http-endpoints/post-kline-archive-download.md).

# POST 下载 K 线月归档

按市场、K线周期和月份获取历史K线ZIP归档下载链接，并查询当日剩余下载请求次数。

### 接口说明

按市场和 K 线周期，一次请求一个或多个月份的 ZIP 归档下载链接。每个月返回一条短时有效链接；成功响应同时给出当日剩余成功请求次数和距离配额重置的秒数。

任一月份不在权限范围内或归档包不存在时，整次请求失败。可查询时间范围内的月份仍需已有归档包才能下载。

### 接口地址

```http
POST https://data.infoway.io/kline/archive/download
```

### 请求头

| 参数             | 类型     | 必填 | 描述                 |
| -------------- | ------ | -- | ------------------ |
| `apiKey`       | String | 是  | 套餐 API Key         |
| `Content-Type` | String | 是  | `application/json` |

### 请求参数

| 参数          | 类型             | 必填 | 描述                                                        |
| ----------- | -------------- | -- | --------------------------------------------------------- |
| `market`    | String         | 是  | 市场代码，见下表                                                  |
| `klineType` | Integer        | 是  | `1` 1分钟；`2` 5分钟；`3` 15分钟；`4` 30分钟；`5` 1小时；`6` 2小时；`7` 4小时 |
| `yyyyMM`    | Array\<String> | 是  | 月份列表，格式 `yyyyMM`，去重后最多 36 个月，例如 `["202609","202608"]`     |

| 市场代码     | 市场               | 判定自然月的时区           |
| -------- | ---------------- | ------------------ |
| `us`     | 美股               | `America/New_York` |
| `hk`     | 港股               | `Asia/Shanghai`    |
| `cn`     | A 股              | `Asia/Shanghai`    |
| `common` | 外汇、能源、商品、贵金属、期货等 | `UTC`              |
| `crypto` | 加密货币             | `UTC`              |
| `in`     | 印度               | `Asia/Kolkata`     |
| `jp`     | 日本               | `Asia/Tokyo`       |
| `kr`     | 韩国               | `Asia/Seoul`       |
| `tw`     | 台湾               | `Asia/Taipei`      |

本接口支持分钟和小时周期（1–7）。每次请求指定一个市场和一个周期，月份列表可包含多个月。月份会去除首尾空白、忽略空项，并按首次出现顺序去重；去重后列表必须非空。

```json
{
  "market": "crypto",
  "klineType": 1,
  "yyyyMM": ["202609", "202608"]
}
```

### 套餐和月份权限

* API Key 必须对应正常且未到期的套餐。Free 套餐不支持月归档下载。
* Basic、Premium、Professional、Custom 可请求各市场归档，仍受套餐历史年限限制。
* 市场专属套餐仅能下载对应市场：AllUSStocks 对应 `us`，AllHongKongStocks 对应 `hk`，AllA-ShareStocks 对应 `cn`，India/Japan/Korea/Taiwan 分别对应 `in`/`jp`/`kr`/`tw`。
* 按上述市场时区判定月份，只允许早于本月的月份。最早可下载月取当前时间减去套餐允许历史月数后所在的自然月，该月整月允许。实际可下载内容以归档包是否存在为准。

### 次数限制和链接有效期

本接口与其他 HTTP 接口共用[请求频率限制](https://docs.infoway.io/getting-started/api-limitation/http.md)，并有独立的归档成功请求额度：

* 每个 API Key 每个 UTC 自然日最多成功请求 **5 次**，各市场共用。UTC 00:00（北京时间 08:00）重置。
* 一次成功请求多个包只计 **1 次**。成功取得链接即计数；实际下载 ZIP 无需再次调用此接口。
* 参数错误、权限不足或包不存在时，不扣成功请求次数。
* 每条链接有效期 **3 分钟**，到期时间见 `expireAt`。

### 成功响应

以下数据仅展示响应格式，示例下载地址不可用于下载。

```json
{
  "ret": 200,
  "msg": "success",
  "traceId": "example-trace-id",
  "data": {
    "remaining": 4,
    "refreshInSeconds": 3600,
    "items": [
      {
        "yyyyMM": "202609",
        "archiveKey": "kline_1_202609",
        "downloadUrl": "https://example.invalid/crypto-202609.zip",
        "expireAt": 1791878580
      },
      {
        "yyyyMM": "202608",
        "archiveKey": "kline_1_202608",
        "downloadUrl": "https://example.invalid/crypto-202608.zip",
        "expireAt": 1791878580
      }
    ]
  }
}
```

| 字段                      | 类型      | 描述                                   |
| ----------------------- | ------- | ------------------------------------ |
| `data.remaining`        | Integer | 本次请求成功后，当日剩余成功请求次数                   |
| `data.refreshInSeconds` | Long    | 距离下一个 UTC 00:00 的秒数                  |
| `data.items`            | Array   | 每个月对应一条下载信息，顺序与去重后的请求月份一致            |
| `items[].yyyyMM`        | String  | 对应月份                                 |
| `items[].archiveKey`    | String  | 归档标识，格式 `kline_<klineType>_<yyyyMM>` |
| `items[].downloadUrl`   | String  | 对应月包的短时下载 URL                        |
| `items[].expireAt`      | Long    | 下载链接过期时间，Unix **秒**时间戳               |

取得链接后，用 GET 请求对应 `downloadUrl` 下载文件。保留链接完整内容，并在过期前使用。

### 错误响应

以下数字为响应 JSON 的业务码 `ret`；HTTP 状态及通用说明见 [HTTP 错误码](https://docs.infoway.io/getting-started/error-codes/http.md)。

| `ret` | 情形                                                       |
| ----- | -------------------------------------------------------- |
| `404` | 任一请求月份的归档包不存在：`Archive not found: kline_<type>_<yyyyMM>` |
| `502` | 当日 5 次成功请求额度已耗尽                                          |
| `506` | 不支持的市场/周期、非法月份或月份数量超过上限                                  |
| `507` | 缺少必填参数，或月份列表为空                                           |
| `509` | 套餐已到期                                                    |
| `513` | 本月、未来月份或超出套餐历史范围：`Month not allowed: <yyyyMM>`           |
| `514` | 账户状态不允许、Free 套餐或没有对应市场权限                                 |

配额耗尽时，响应仍提供重置倒计时：

```json
{
  "ret": 502,
  "msg": "Request frequency for the day upper limit：5",
  "traceId": "example-trace-id",
  "data": {
    "remaining": 0,
    "refreshInSeconds": 3600
  }
}
```
