银行历史汇率查询与汇率转换接口接入指南｜按月份或日期区间取牌价，含币种间金额换算

本文档面向需要获取银行外汇牌价、做币种间金额换算、以及回溯历史牌价的开发者，介绍接口的接入方式、参数设计、返回结构与工程实践。全文为技术视角，聚焦接入与工程实践。

图1：四接入点能力概览

一、技术简介

银行汇率查询接口面向需要银行外汇牌价与汇率换算能力的业务系统，对外提供四类能力：

外汇牌价币种列表：返回接口支持的全部外币代码与名称，用于下拉渲染与代码合法性校验。
中国银行 / 十大银行延迟汇率：返回常见货币对人民币的现汇买入价、现钞买入价、现汇卖出价、现钞卖出价、中行折算价。
汇率转换：将指定金额从源币种换算到目标币种，返回换算后金额。
查询历史汇率：按月份或日期区间回溯逐日历史牌价，数据自 2009 年起。

接口以 JSON 形式返回，业务数据统一封装在 showapi_res_body 对象内。返回的字段值均为字符串类型，数据存在数分钟延迟，适用于对账、走势分析、金额换算等工程场景，不作为实时交易判定依据。

二、能力概览

接入点	路径（商品页为准）	调用方法	关键入参	返回核心字段	典型用途
外汇币种列表	`/waihui-list`	GET / POST	无	`code`、`name`、`flag`	渲染货币下拉、校验代码
中国银行 / 十大银行延迟汇率	`/bank-cnc`、`/bank-huob`	GET / POST	`code`	`hui_in`、`chao_in`、`hui_out`、`chao_out`、`zhesuan`	页面展示牌价
汇率转换	`/lsspeed`	GET / POST	`fromCode`、`toCode`、`money`	`money`	金额跨币种换算
查询历史汇率	`/lshistory`	GET / POST	`code`/`name`，`month` 或 `startDate`+`endDate`	`list[]` 逐日牌价	对账、走势分析

鉴权方式：请求头 Authorization: APPCODE <appcode>，<appcode> 为控制台获取的调用凭证。
返回格式：JSON。通用封装字段见第五章。
调用地址与接入点路径：以云市场商品页 / 控制台显示为准。本文以历史汇率接入点（商品页路径示例 /lshistory）作为主示例，其余接入点路径示例：币种列表 /waihui-list、银行延迟汇率 /bank-cnc 与 /bank-huob、汇率转换 /lsspeed；示例中的 <调用地址> 请替换为商品页提供的实际地址。

三、适用场景

落到具体业务，以下场景可直接复用上述能力：

跨境电商定价：商品页展示「$29.99 ≈ ¥215」，调用银行延迟汇率做本币换算与展示。
留学 / 差旅缴费：按目标币种换算学费、保证金、住宿费等金额。
财务对账留痕：每笔换汇按当日牌价留底，事后用历史汇率接入点回溯核对。
汇率走势分析：按月份或日期区间取历史牌价，计算波动与均值。
货币代码校验：用币种列表校验用户输入的货币代码是否在支持范围内。

四、接入流程

开通与取凭证：在云市场开通对应商品，进入控制台获取 APPCODE。
阅读接口说明：从商品页确认调用地址、各接入点路径与参数约束。
组装请求：按接入点填入 Query / Form 参数，并带上 Authorization: APPCODE <appcode> 请求头。
解析响应：先判系统级 showapi_res_code，再判业务级 ret_code，最后读取 showapi_res_body 中的业务字段。
工程处理：对延迟数据做结果缓存、对空字段做容错、对配额超限做退避重试。

图2：接入流程时序

五、调用示例与返回结构

5.1 请求参数

外汇牌价币种列表（无必填参数）

参数	位置	类型	必填	说明
`content-type`	Header	String	否	POST 时建议 `application/x-www-form-urlencoded`

中国银行 / 十大银行延迟汇率

参数	位置	类型	必填	说明
`code`	Query/Form	String	否	货币简码，如 `USD`；不传则返回全部货币

汇率转换

参数	位置	类型	必填	说明
`fromCode`	Query/Form	String	是	源货币代码，如 `GBP`
`toCode`	Query/Form	String	是	目标货币代码，如 `EUR`
`money`	Query/Form	String	是	待换算金额，单位元

查询历史汇率

参数	位置	类型	必填	说明
`code`	Query/Form	String	否	货币简码，如 `USD`
`name`	Query/Form	String	否	货币名称；`code` 与 `name` 至少传一个
`month`	Query/Form	String	否	查询年月 `yyyyMM`，与 `startDate`/`endDate` 互斥
`startDate`	Query/Form	String	否	起始日 `yyyyMMdd`，与 `endDate` 配合使用，区间上限 90 天
`endDate`	Query/Form	String	否	结束日 `yyyyMMdd`

5.2 返回结构

所有接入点均使用如下系统级封装，业务数据位于 showapi_res_body：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "example-res-id",
  "showapi_res_body": {
    }
}

中国银行 / 十大银行延迟汇率返回示例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "example-res-id",
  "showapi_res_body": {
   
    "ret_code": 0,
    "listSize": 26,
    "list": [
      {
   
        "name": "美元",
        "code": "USD",
        "hui_in": "663.94",
        "chao_in": "658.62",
        "hui_out": "666.6",
        "chao_out": "666.6",
        "zhesuan": "664.96",
        "day": "2016-07-01",
        "time": "11:58:01"
      }
    ]
  }
}

list 元素字段含义：

字段	类型	说明
`name`	String	货币名称
`code`	String	货币简码
`hui_in`	String	现汇买入价
`chao_in`	String	现钞买入价
`hui_out`	String	现汇卖出价
`chao_out`	String	现钞卖出价
`zhesuan`	String	中行折算价
`day`	String	发布日期 `yyyy-MM-dd`
`time`	String	发布时间 `HH:mm:ss`
`ret_code`	Number	业务码，`0` 为成功
`listSize`	Number	返回条数

注意：部分货币（如印尼卢比、印度卢比、巴西里亚尔、新台币、林吉特等）的 hui_in / chao_in 可能为空字符串，解析时需做空值判断。

汇率转换返回示例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "example-res-id",
  "showapi_res_body": {
   
    "ret_code": 0,
    "money": "120.2054"
  }
}

查询历史汇率返回示例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "example-res-id",
  "showapi_res_body": {
   
    "ret_code": 0,
    "currency_code": "USD",
    "currency_name": "美元",
    "startDate": "20260801",
    "endDate": "20260831",
    "month": "202608",
    "remark": "查询成功!",
    "list": [
      {
   
        "day": "2026-08-31",
        "hui_in": "663.94",
        "chao_in": "658.62",
        "hui_out": "666.6",
        "chao_out": "666.6",
        "zhesuan": "664.96"
      }
    ]
  }
}

外汇牌价币种列表返回示例

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "example-res-id",
  "showapi_res_body": {
   
    "ret_code": 0,
    "exchange_list": [
      {
    "name": "英镑", "code": "GBP", "flag": "https://res-showapi.oss-cn-hangzhou.aliyuncs.com/exchange/英国国旗.png" }
    ]
  }
}

exchange_list 元素字段含义：name 货币名称、code 货币简码、flag 旗帜图地址。

图3：返回结构字段树

5.3 多语言调用示例（历史汇率接入点）

以下示例查询 2026 年 8 月美元历史牌价，四种语言写法一致，仅替换 <调用地址> 与 <appcode> 即可运行。

Python

import requests

API_BASE = "https://<调用地址>"   # 替换为云市场商品页提供的调用地址
APPCODE = "<appcode>"            # 替换为控制台获取的 APPCODE

headers = {
   "Authorization": f"APPCODE {APPCODE}"}
params = {
   
    "code": "USD",
    "month": "202608",          # month 与 startDate/endDate 二选一
    # "startDate": "20260801", "endDate": "20260831",
}

resp = requests.get(f"{API_BASE}/lshistory", headers=headers, params=params, timeout=15)
data = resp.json()
body = data.get("showapi_res_body", {
   })
if data.get("showapi_res_code") == 0 and body.get("ret_code") == 0:
    for item in body.get("list", []):
        print(item.get("day"), item.get("zhesuan"))
else:
    print("err:", data.get("showapi_res_error"))

Java

import java.net.http.*;
import java.net.URI;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class FxHistory {
   
  public static void main(String[] args) throws Exception {
   
    String base = "https://<调用地址>";      // 替换为商品页调用地址
    String appcode = "<appcode>";            // 替换为 APPCODE
    String q = "code=" + URLEncoder.encode("USD", StandardCharsets.UTF_8)
             + "&month=" + URLEncoder.encode("202608", StandardCharsets.UTF_8);
    HttpRequest req = HttpRequest.newBuilder()
        .uri(URI.create(base + "/lshistory?" + q))
        .header("Authorization", "APPCODE " + appcode)
        .GET().build();
    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.statusCode());
    System.out.println(res.body());
  }
}

PHP

<?php
$base = "https://<调用地址>";     // 替换为商品页调用地址
$appcode = "<appcode>";           // 替换为 APPCODE
$url = $base . "/lshistory?code=" . urlencode("USD") . "&month=" . urlencode("202608");
$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: APPCODE " . $appcode],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
curl_close($ch);
echo $body;

Node.js

const https = require("https");

const base = "https://<调用地址>";   // 替换为商品页调用地址
const appcode = "<appcode>";         // 替换为 APPCODE
const url = `${
     base}/lshistory?code=${
     encodeURIComponent("USD")}&month=${
     encodeURIComponent("202608")}`;

https.get(url, {
    headers: {
    Authorization: `APPCODE ${
     appcode}` } }, (res) => {
   
  let data = "";
  res.on("data", (c) => (data += c));
  res.on("end", () => console.log(data));
}).on("error", (e) => console.error(e));

六、在线调试实录

在控制台调试模块选择对应接入点后，按如下要点操作：

汇率查询 / 历史汇率：填 code=USD，点发起请求；成功时 ret_code=0 且 showapi_res_code=0，否则读取 showapi_res_error 定位原因。
汇率转换：填 fromCode、toCode、money 三个参数，返回 money 为换算后金额。
币种列表：无需参数，直接发起请求即可拿到全部外币代码。

常见调试坑：

空字段：部分币种的 hui_in / chao_in 为空字符串，调试时若页面展示异常，先在代码中打印原始 JSON 确认字段存在性。
时间参数互斥：历史查询 month 与 startDate+endDate 不能同时传，二选一。
区间上限：文档标注历史区间上限 90 天；超长时接口最多返回 90 条，实际区间以返回 list 首尾日期为准。
延迟数据：返回值为延迟数据，调试时不要以「与银行实时屏幕不一致」误判为接口异常。

图6：在线调试实录示意

七、调用限制与规范

请求方式：支持 GET 与 POST；POST 时建议设置 content-type: application/x-www-form-urlencoded。
参数约束：历史查询 code 与 name 至少传一个；month(yyyyMM) 与 startDate+endDate(yyyyMMdd) 二选一。
配额与频控：调用档位与配额以控制台显示为准，超出后接口会返回错误，调用侧需实现退避重试。
结果缓存：由于数据为延迟数据且更新频率有限，调用侧应做结果缓存并设置合理 TTL，避免重复请求放大配额消耗。
超时设置：建议客户端读超时与连接超时均设为 15 秒量级，并对网络异常做捕获。

八、能力边界与免责声明

数据延迟：数据源自公开渠道，存在数分钟延迟，仅供参考，不作为交易、结算、风控的唯一依据。
合规责任：接口不存储调用明细以外的敏感信息；调用方对传入与展示的数据承担合规责任。
禁止用途：不得将接口用于违法违规场景（如规避外汇管制、虚假报价、误导性展示）。
货币范围：覆盖货币以商品页说明为准（二十余种常见货币，含 USD、EUR、GBP、JPY 等），历史数据自 2009 年起。
字段可用性：部分币种特定买卖价可能为空，使用前需确认字段可用性并做容错。
口径说明：牌价以每 100 单位外币兑人民币为口径；银行延迟汇率约每 10 秒更新中行公布值，历史牌价每日更新前一自然日。

九、错误码与排查

现象	可能原因	处理建议
`showapi_res_code` 非 0	系统级异常	读取 `showapi_res_error`，核对调用地址与鉴权
`ret_code` 非 0	业务参数错误	检查 `code`/`name`、时间参数组合
历史查询无数据	`code` 与 `name` 均未传，或 `month` 与区间同时传	至少传一个货币参数；时间参数二选一
部分字段为空	该币种无对应买卖价	解析时做空值判断与降级展示
HTTP 401	`APPCODE` 缺失或错误	检查 `Authorization` 请求头
HTTP 403 / 429	配额耗尽或频率超限	退避重试，确认控制台档位余量

十、技术 FAQ

Q：银行延迟汇率与历史牌价的数据口径是否一致？
A：均以每 100 单位外币兑人民币为口径。银行延迟汇率约每 10 秒更新中行公布值，历史牌价每日更新前一自然日。

Q：转换接口返回的金额是按现汇还是现钞？
A：接口按实时中间折算价换算，返回 money 为换算后金额，不区分现汇 / 现钞。若业务需区分，请结合银行延迟汇率的 hui_out / chao_out 等字段自行计算。

Q：历史查询一次能取多长区间？
A：文档区间上限 90 天；超长时接口最多返回 90 条，实际区间以返回 list 首尾日期为准。

Q：接口能否用于终端实时报价展示？
A：数据为延迟数据，不建议用于需要实时精度的交易终端展示；在页面应注明「数据有延迟，以银行实际交易汇率为准」。

Q：币种列表是否包含人民币？
A：币种列表返回外币全集（不含 CNY）；银行延迟汇率不传 code 时返回含 CNY 的全集。

十一、内容小结

本文介绍了银行汇率查询接口的四类能力及其接入方式：

四接入点共享同一套鉴权与返回封装，仅路径与参数不同；
银行延迟汇率返回五类牌价字段（现汇 / 现钞买卖价与中行折算价），部分币种存在空字段需容错；
汇率转换以 fromCode、toCode、money 三点入参返回换算金额；
历史汇率支持按月份或日期区间回溯逐日牌价，时间参数互斥且区间上限 90 天。

工程建议：解析时对空字段做容错、对延迟数据做结果缓存与免责标注、配额超限做退避重试、对关键业务场景保留历史牌价留痕以便对账。接入前请于控制台确认调用地址、凭证与档位配额，并按业务需要设计参数校验与异常处理。

图4：场景案例-跨境电商金额换算

图5：场景案例-财务对账历史留痕

银行历史汇率查询与汇率转换接口接入指南｜获取逐日历史牌价，含币种间金额换算

银行历史汇率查询与汇率转换接口接入指南｜按月份或日期区间取牌价，含币种间金额换算

一、技术简介

二、能力概览

三、适用场景

四、接入流程

五、调用示例与返回结构

5.1 请求参数

5.2 返回结构

5.3 多语言调用示例（历史汇率接入点）

六、在线调试实录

七、调用限制与规范

八、能力边界与免责声明

九、错误码与排查

十、技术 FAQ

十一、内容小结

云市场头条

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

银行历史汇率查询与汇率转换接口接入指南｜获取逐日历史牌价，含币种间金额换算

银行历史汇率查询与汇率转换接口接入指南｜按月份或日期区间取牌价，含币种间金额换算

一、技术简介

二、能力概览

三、适用场景

四、接入流程

五、调用示例与返回结构

5.1 请求参数

5.2 返回结构

5.3 多语言调用示例（历史汇率接入点）

六、在线调试实录

七、调用限制与规范

八、能力边界与免责声明

九、错误码与排查

十、技术 FAQ

十一、内容小结

云市场头条

热门文章

最新文章

相关电子书