提供指定货币在特定时间段内的历史汇率数据查询，支持按月或自定义日期区间检索。
请求地址
https://openapi.toolkk.com/v1/aliyunmarket-cmapi00064402-exchange-rate-history
默认限流
60 次/分钟
超时时间
10000 ms
历史汇率查询 API 允许开发者获取特定货币在过去一段时间内的汇率变动情况。通过提供货币编号或名称，以及目标查询月份或自定义的起止日期，接口将返回该时间段内每日的详细汇率数据，包括现汇买入/卖出价、现钞买入/卖出价以及中行折算价。
* **财务结算与审计**：企业在进行跨国交易结算或财务审计时，需核对历史特定日期的汇率。 * **数据分析与趋势预测**：金融分析师或研究人员利用历史汇率数据进行市场趋势分析和模型构建。 * **跨境电商平台**：为用户提供历史订单的汇率参考，或用于内部成本核算。 * **旅游与换汇服务**：展示历史汇率走势，辅助用户制定换汇策略。
**请求参数要点：**
* 需指定查询的货币，可通过 `code` (货币编号，如 USD) 或 `name` (货币名称，如 美元) 传入，两者必填其一。 * 需指定查询时间范围，可通过 `month` (年月，格式 yyyyMM) 或组合使用 `startDate` 和 `endDate` (年月日，格式 yyyyMMdd) 传入。注意：按月查询和按日期区间查询不能同时为空。
**返回结果要点：**
* 返回结果包含状态码 (`code`)、描述信息 (`msg`) 和唯一请求号 (`taskNo`)。 * 核心数据位于 `data` 对象中，包含查询的货币信息和时间范围。 * `list` 数组中包含了指定时间段内每日的汇率详情，具体字段包括： * `publish_time`：发布日期。 * `middle_rate`：中行折算价。 * `buying_rate`：现汇买入价。 * `selling_rate`：现汇卖出价。 * `cash_buying_rate`：现钞买入价。 * `cash_selling_rate`：现钞卖出价。
* 建议优先使用货币编号 (`code`) 进行查询，以避免因货币名称 (`name`) 拼写差异导致查询失败。 * 在构建查询请求时，请确保时间参数格式正确 (yyyyMM 或 yyyyMMdd)，并注意按月查询与按日期区间查询的互斥逻辑。 * 对于大范围的历史数据查询，建议在业务低峰期进行，或考虑将查询结果进行本地缓存，以降低接口调用频率和提升响应速度。 * 请注意处理接口返回的非 200 状态码，并根据 `msg` 字段进行相应的错误提示或重试逻辑。
所有接口都建议按 code、message、data 的标准结构进行解析。
{ code, message, data }
curl --request POST \
--url 'https://openapi.toolkk.com/v1/aliyunmarket-cmapi00064402-exchange-rate-history' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "type": "object",\n "properties": {\n "code": {\n "type": "string",\n "description": "货币编号，货币编号或货币名称必须输入其中一个"\n },\n "name": {\n "type": "string",\n "description": "货币名称，货币编号或货币名称必须输入其中一个"\n },\n "month": {\n "type": "string",\n "description": "查询年月（yyyyMM），month和startDate、endDate不能同时为空"\n },\n "startDate": {\n "type": "string",\n "description": "查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空"\n },\n "endDate": {\n "type": "string",\n "description": "查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空"\n }\n }\n}'{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "货币编号，货币编号或货币名称必须输入其中一个"
},
"name": {
"type": "string",
"description": "货币名称，货币编号或货币名称必须输入其中一个"
},
"month": {
"type": "string",
"description": "查询年月（yyyyMM），month和startDate、endDate不能同时为空"
},
"startDate": {
"type": "string",
"description": "查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空"
},
"endDate": {
"type": "string",
"description": "查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空"
}
}
}{
"type": "object",
"properties": {
"msg": {
"type": "string",
"example": "成功",
"description": "code对应的描述"
},
"code": {
"type": "number",
"example": 200,
"description": "返回码，详见code返回码说明"
},
"taskNo": {
"type": "string",
"example": "687882815162227863699691",
"description": "本次唯一请求号"
},
"data": {
"type": "object",
"properties": {
"currencyCode": {
"type": "string",
"example": "USD",
"description": "货币编号"
},
"currencyName": {
"type": "string",
"example": "美元",
"description": "货币名称"
},
"startDate": {
"type": "string",
"example": "20191001",
"description": "开始日期"
},
"endDate": {
"type": "string",
"example": "20191101",
"description": "结束日期"
},
"month": {
"type": "string",
"example": "201910",
"description": "结束日期"
},
"list": {
"type": "array",
"items": {
"type": "object",
"properties": {
"middle_rate": {
"type": "string",
"example": "705.33",
"description": "中行折算价"
},
"selling_rate": {
"type": "string",
"example": "705.55",
"description": "现汇卖出价"
},
"cash_buying_rate": {
"type": "string",
"example": "696.86",
"description": "现钞买入价"
},
"buying_rate": {
"type": "string",
"example": "702.58",
"description": "现汇买入价"
},
"cash_selling_rate": {
"type": "string",
"example": "705.55",
"description": "现钞卖出价"
},
"publish_time": {
"type": "string",
"example": "2019-10-31",
"description": "发布日期"
}
}
},
"example": [
{
"middle_rate": "705.33",
"selling_rate": "705.55",
"cash_buying_rate": "696.86",
"buying_rate": "702.58",
"cash_selling_rate": "705.55",
"publish_time": "2019-10-31"
},
{
"middle_rate": "705.82",
"selling_rate": "707.26",
"cash_buying_rate": "698.54",
"buying_rate": "704.27",
"cash_selling_rate": "707.26",
"publish_time": "2019-10-30"
}
]
}
}
}
}
}以下字段根据示例 JSON 自动提取，仅作接入参考。
| 字段路径 | 类型 | 示例值 |
|---|---|---|
| type | string | object |
| properties | object | {...} |
| properties.code | object | {...} |
| properties.code.type | string | string |
| properties.code.description | string | 货币编号，货币编号或货币名称必须输入其中一个 |
| properties.name | object | {...} |
| properties.name.type | string | string |
以下字段根据示例 JSON 自动提取，仅作接入参考。
| 字段路径 | 类型 | 示例值 |
|---|---|---|
| type | string | object |
| properties | object | {...} |
| properties.msg | object | {...} |
| properties.msg.type | string | string |
| properties.msg.example | string | 成功 |
| properties.msg.description | string | code对应的描述 |
| properties.code | object | {...} |
| properties.code.type |
| properties.name.description |
| string |
| 货币名称，货币编号或货币名称必须输入其中一个 |
| properties.month | object | {...} |
| properties.month.type | string | string |
| properties.month.description | string | 查询年月（yyyyMM），month和startDate、endDate不能同时为空 |
| properties.startDate | object | {...} |
| properties.startDate.type | string | string |
| properties.startDate.description | string | 查询起始时间yyyyMMdd，month和startDate、endDate不能同时为空 |
| properties.endDate | object | {...} |
| properties.endDate.type | string | string |
| properties.endDate.description | string | 查询结束时间yyyyMMdd，month和startDate、endDate不能同时为空 |
| string |
| number |
| properties.code.example | number | 200 |
| properties.code.description | string | 返回码，详见code返回码说明 |
| properties.taskNo | object | {...} |
| properties.taskNo.type | string | string |
| properties.taskNo.example | string | 687882815162227863699691 |
| properties.taskNo.description | string | 本次唯一请求号 |
| properties.data | object | {...} |
| properties.data.type | string | object |