外汇牌价查询接口接入教程：实时牌价 / 汇率换算 / 历史牌价调用实践

说明：本文基于公开接口文档整理，未对每个接口做真实请求实测，接口可用性、额度与更新节奏以控制台与官方文档为准，集成前请自行发请求验证。

一、技术简介

外汇牌价类接口用于获取银行体系公布的外汇牌价，并为上层业务提供币种字典、实时牌价、币种间换算与历史牌价回溯四类能力。典型返回覆盖：币种代码与中文名、现汇买入/卖出价、现钞买入/卖出价、中行折算价、发布日期与时间，以及历史区间内的中间价、买入价、卖出价与现钞买卖价等字段。

文章按「能力概览 → 适用场景 → 接入流程 → 调用示例与返回结构 → 在线调试 → 限制与规范 → 能力边界 → 错误码 → 技术 FAQ → 小结」展开，代码示例覆盖 Python / Java / PHP / Node.js 四种语言。

二、能力概览

三、适用场景

• 外汇比价工具：按币种拉取牌价，展示现汇、现钞的买入卖出价，为用户估算换汇成本提供参考。
• 跨境结算系统：按业务口径选定牌价字段计算应收/应付金额，并配合历史牌价做月结复核。
• 金融资讯平台：展示外汇牌价表与历史走势，附上数据发布时间，避免把延迟数据当成实时成交价。
• 汇率监控预警：定时抓取数据，当某币种牌价突破设定阈值时触发告警，同时做好空值与超时处理。

四、接入流程

1. 开通与取凭证：在控制台开通对应服务，获取 APPCODE 调用凭证，仅保存在服务端环境变量或配置中心。
2. 组请求：按能力选择入参，使用 Authorization: APPCODE <appcode> 请求头发起调用，调用地址以控制台显示为准。
3. 两层状态判断：先判系统级状态字段，再判业务级状态字段，二者均成功才解析业务数据。
4. 解析与兜底：牌价字段为字符串且可能为空，参与计算前先转数值并判空；按业务口径选择现汇或现钞字段。
5. 工程加固：补充入参前置校验、超时与失败重试、结果缓存、熔断降级与监控告警，避免上游抖动拖垮主流程。

五、调用示例与返回结构

5.1 请求参数

实时牌价查询的主要入参：

汇率换算必填入参：fromCode（源币种）、toCode（目标币种）、money（金额）。历史牌价入参：code / name / month（yyyyMM）与 startDate / endDate（yyyyMMdd）互斥，日期区间最大 90 天。

5.2 完整返回结构（实时牌价查询）

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

字段含义：

5.3 多语言调用示例

以下示例均使用 APPCODE 请求头，调用地址以控制台为准；响应体结构中的 showapi_res_code 为系统级状态，showapi_res_body 为业务数据容器。

Python

import requests

APPCODE = "你的APPCODE"
URL = "调用地址（控制台获取）"

resp = requests.post(
    URL,
    headers={
   "Authorization": f"APPCODE {APPCODE}"},
    data={
   "code": "USD"},
    timeout=5,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
    raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
    raise RuntimeError("业务调用失败")
for item in body["list"]:
    print(item["code"], item["hui_in"], item["hui_out"])

Java

import java.net.http.*;
import java.net.URI;

public class RateQuery {
   
    public static void main(String[] args) throws Exception {
   
        String appcode = "你的APPCODE";
        String url = "调用地址（控制台获取）";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "APPCODE " + appcode)
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString("code=USD"))
            .build();
        HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

PHP

<?php
$appcode = "你的APPCODE";
$url = "调用地址（控制台获取）";
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: APPCODE $appcode", "Content-Type: application/x-www-form-urlencoded"],
    CURLOPT_POSTFIELDS => "code=USD",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
]);
$body = curl_exec($ch);
curl_close($ch);
echo $body;

Node.js

const https = require("https");

const appcode = "你的APPCODE";
const url = "调用地址（控制台获取）";
const data = "code=USD";

const req = https.request(
  url,
  {
   
    method: "POST",
    headers: {
   
      Authorization: `APPCODE ${
     appcode}`,
      "Content-Type": "application/x-www-form-urlencoded",
      "Content-Length": Buffer.byteLength(data),
    },
  },
  (res) => {
   
    let buf = "";
    res.on("data", (c) => (buf += c));
    res.on("end", () => console.log(buf));
  }
);
req.write(data);
req.end();

六、在线调试实录

在控制台调试面板中填写入参时，建议先以单个币种（如 USD）验证链路：

1. 在请求头填入 Authorization: APPCODE <appcode>，确认凭证有效。
2. 实时牌价查询先传 code=USD，观察是否返回包含 hui_in / hui_out 等字段的单条记录。
3. 不传 code 时返回全部币种，listSize 表示列表长度，可作为数据完整性的快速校验。
4. 历史牌价建议先用 month=201901 这类单月参数，确认返回区间与字段后再扩展到日期区间。
5. 任何异常先看系统级状态字段，再查业务级状态字段，避免把错误响应当成空数据。

七、调用限制与规范

• 入参约束：汇率换算三个参数均为必填；历史牌价 month 与日期区间互斥，区间最大 90 天。
• 字段口径：实时牌价用 hui_in / hui_out / chao_in / chao_out / zhesuan，历史牌价用 middle_rate / buying_rate / selling_rate / cash_buying_rate / cash_selling_rate，两套字段名不同，解析时分开处理。
• 类型与空值：牌价均为字符串，部分币种个别字段可能为空字符串或缺失，计算前先转数值并判空。
• 配额与频率：具体额度与限流以控制台档位为准，上线前确认自身账号的调用档次。
• 工程规范：设置合理超时、失败重试、结果缓存与监控；入参做前置校验，避免无效请求放大配额消耗。

八、能力边界与免责声明

• 数据为延迟数据，仅供参考，实际交易汇率以当地银行柜台为准。
• 接口定位为数据分析参考，非投资建议，请勿将其作为结汇、投资或风控的唯一判定依据。
• 历史牌价每日更新，属回溯用途，不可替代实时行情。
• 调用方应自行做好数据合规与用途管控，不将接口用于违规场景，不长期存储敏感明细。
• 本文档基于公开文档整理，未做真实请求实测，字段、额度与更新节奏以控制台与官方文档为准。

九、错误码与排查

十、技术 FAQ

1. 问：一次能拿全部币种的牌价吗？

答：实时牌价查询的 code 参数不传即返回全部，listSize 表示列表长度。

2. 问：牌价多久更新一次？

答：实时牌价类能力按公布节奏刷新；历史牌价类每日更新，属回溯用途。具体节奏以官方文档与控制台为准。

3. 问：历史牌价能查到多早的数据？

答：文档口径通常覆盖多年区间，涵盖美元、欧元、英镑等常见货币，单位为 100 外币兑人民币，具体起点以控制台为准。

4. 问：现汇买入价和现汇卖出价有什么区别？

答：hui_in 是现汇买入价、hui_out 是现汇卖出价，chao_in / chao_out 对应现钞买入价与现钞卖出价；具体用哪个取决于业务是结汇、购汇还是展示。

5. 问：汇率换算必传哪些参数？

答：fromCode（源币种）、toCode（目标币种）、money（金额）三个均为必填，换算结果在响应体的金额字段中。

6. 问：查历史牌价时 month 和 startDate 能同时传吗？

答：不能。month（yyyyMM）与 startDate / endDate（yyyyMMdd）互斥，且日期区间最大 90 天。

7. 问：APPCODE 应该放在哪里？

答：作为 Authorization: APPCODE <appcode> 请求头传入；仅保存在服务端环境变量或配置中心，不要写进前端代码或公开仓库。

8. 问：返回的牌价是数字还是字符串？

答：牌价字段为字符串，参与计算前建议转 Decimal 并先判空。

9. 问：为什么有些字段是空字符串？

答：个别币种的某些牌价字段可能为空或缺失，属需要兼容的数据形态，解析时按可空处理即可。

10. 问：这些牌价能直接用于结汇或投资建议吗？

答：不能。数据为延迟数据，仅供参考，实际交易以当地银行柜台为准，接口定位为数据分析参考，非投资建议。

十一、内容小结

外汇牌价类接口把「币种字典 / 实时牌价 / 汇率换算 / 历史牌价」四类能力拆开，接入时按业务动作选对应能力即可。工程上重点在于：用 APPCODE 请求头做鉴权、做两层状态判断、对字符串牌价字段先做空值与类型兜底、历史与实时两套字段分开解析。配合入参校验、超时重试、缓存与监控，能在控制配额消耗的同时拿到稳定可用的牌价数据。