> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 版本管理

> 选择 REST API 契约，并固定集成使用的请求与响应格式

向 `https://api.qfex.com` 发起请求时，通过 `api_version` 查询参数选择接口契约。契约定义请求字段、校验规则及响应格式。日期标识一个已发布契约，而不是选择历史市场数据。

## 选择版本

| 请求 | 行为 |
| - | - |
| 不提供 `api_version` | 使用最新已发布契约。 |
| `api_version=latest` | 使用最新已发布契约。 |
| `api_version=2026-10-29` | 将请求固定到 `2026-10-29` 契约。 |

对于需要稳定格式的集成，请在每次请求中发送明确日期。不指定日期的请求会自动跟随未来契约变更。

```sh theme={null}
curl -i 'https://api.qfex.com/md/contracts?api_version=2026-10-29'
```

保持接口路径不变。如果 URL 已有查询参数，则追加 `&api_version=2026-10-29`。各版本的身份认证要求相同。

`Qfex-Api-Version` 响应头标明实际选中的契约，包括省略参数或发送 `latest` 的情况。

## 支持的契约

| 契约 | 参考说明 | OpenAPI |
| - | - | - |
| `2026-10-29` | [契约指南](https://docs.qfex.com/cn/api-reference/versions/2026-10-29.md) | [JSON](https://api.qfex.com/contracts/2026-10-29/openapi.json) · [YAML](https://api.qfex.com/contracts/2026-10-29/openapi.yaml) |

只接受已发布的日期。空值、重复、格式错误或不支持的 `api_version` 返回 HTTP `400`；API 不会将日期自动取整或匹配至邻近版本。

## 浏览与试用契约

在顶部版本下拉菜单选择 **Latest** 或已发布日期，然后打开 API 参考标签页。**Latest** 跟随当前公开规范；日期版本加载对应契约规范，并有独立的参考文档 URL。

> [!WARNING]
>
> 选择文档版本不会自动为 API 请求添加版本。使用交互式调试器或复制请求时，必须将 `api_version` 显式设置为正在阅读的日期。留空会请求最新版本。

[最新 OpenAPI 规范](https://api.qfex.com/openapi.yaml)会随新版本更新。针对特定契约生成客户端时，请使用上表中带日期的 OpenAPI 链接。生成的客户端也必须在请求中发送该日期。

## 升级集成

1. 阅读 [API 更新日志（英文）](https://docs.qfex.com/websocket/changelog.md)及目标契约参考文档。
2. 按目标契约更新请求构造和响应解析。
3. 使用目标 `api_version` 测试请求，包括校验和错误处理。
4. 检查通过后，修改集成中固定的日期。

版本管理保留所选的线上传输契约。响应仍反映当前市场及账户状态，请求也仍执行当前业务逻辑。

## 适用范围

此参数适用于 `api.qfex.com` 的 REST API。`banker.qfex.com` 上的[出入金 API](https://docs.qfex.com/cn/api-reference/programmatic-funding.md)和 [WebSocket API](https://docs.qfex.com/cn/websocket/main.md)具有独立接口，不使用该版本选择器。健康检查及带日期的契约元数据 URL 不属于基于查询参数的契约选择范围。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.