银行汇率查询返回字段全解（五大价位 / 两层状态码 / 空值情况）
约 11 分钟 入门银行汇率查询返回字段状态码五大价位
# 银行汇率查询返回字段全解（五大价位 / 两层状态码 / 空值情况）
接口：银行汇率查询（apiCode=105）· 接入点：汇率查询（105-30）· 免费（L0 基础版 100 次/天、1 QPS）· 请求方式：POST / GET · 返回格式：JSON · 适用人群：已接入或即将接入的开发者 · 阅读时间：约 6 分钟 · 最后实测核对：2026-09-18
## 核心要点
- 响应有两层状态码：系统级 `showapi_res_code` 与业务级 `showapi_res_body.ret_code`，两者都为 0 才算成功。
- 牌价的核心是五个价位：`hui_in` 现汇买入价、`chao_in` 现钞买入价、`hui_out` 现汇卖出价、`chao_out` 现钞卖出价、`zhesuan` 中行折算价。
- 五个价位字段全部以字符串返回，且并非每种货币都有值：2026-09-18 实测的 46 条记录里，有 17 种货币存在空字符串价位。
## 两层状态码先判断，再读字段
一次调用的返回值分成内外两层。外层是 ShowAPI 统一封装，字段固定四个：`showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num`。内层是 `showapi_res_body`，业务数据都在里面。
| 字段 | 层级 | 取值 | 含义 |
|------|------|------|------|
| `showapi_res_code` | 系统级 | 0 表示通道正常 | 请求是否被平台正常处理 |
| `showapi_res_error` | 系统级 | 字符串 | 通道异常时的错误描述，正常时为空串 |
| `showapi_res_id` | 系统级 | 字符串 | 本次请求的唯一标识，排查问题时提供给客服 |
| `showapi_fee_num` | 系统级 | 整数 | 本次调用的计费次数 |
| `showapi_res_body.ret_code` | 业务级 | 0 表示成功，其他为失败 | 本次查询本身是否成功 |
判断逻辑写成代码是这样：
```python
import requests
js = requests.post(
"https://route.showapi.com/105-30",
params={"appKey": "YOUR_APPKEY"},
data={"code": "EUR"},
timeout=15
).json()
if js.get("showapi_res_code") != 0:
print("通道异常：", js.get("showapi_res_error"))
elif js["showapi_res_body"].get("ret_code") != 0:
print("业务失败，ret_code =", js["showapi_res_body"].get("ret_code"))
else:
print("查询成功，共", js["showapi_res_body"]["listSize"], "条")
```
系统级和业务级会分开返回各自的结果。2026-09-18 实测历史汇率接入点时观察到一种组合：不传任何货币参数，`showapi_res_code` 仍为 0，但 `ret_code` 为 -1，同时 `showapi_fee_num` 为 0。这组数据说明只判断系统级状态码并不够，业务级必须一起看。
## 五大价位字段对照
| 字段 | 名称 | 含义 |
|------|------|------|
| `hui_in` | 现汇买入价 | 银行买入外汇现汇时使用的价格 |
| `chao_in` | 现钞买入价 | 银行买入外币现钞时使用的价格 |
| `hui_out` | 现汇卖出价 | 银行卖出外汇现汇时使用的价格 |
| `chao_out` | 现钞卖出价 | 银行卖出外币现钞时使用的价格 |
| `zhesuan` | 中行折算价 | 折算基准价 |
除五个价位外，`list[]` 还有 `name`（货币名称）、`code`（货币简码）、`day`（发布日）、`time`（发布时间），外层业务体还有 `listSize`（本次返回条数）。
现汇与现钞是两组独立字段，取值以接口实际返回为准。2026-09-18 实测的 46 条记录中，两个字段都有值的货币里，`hui_in` 与 `chao_in` 的取值完全相同，`hui_out` 与 `chao_out` 也完全相同，没有任何一条出现差异。展示层建议同时读两个字段，而不是预先假定某一侧一定更低或更高。
## 返回示例与解析
2026-09-18 实测 `105-30?code=USD` 的真实返回：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": 0,
"listSize": 1,
"list": [
{
"name": "美元",
"code": "USD",
"hui_in": "669.61",
"chao_in": "669.61",
"hui_out": "672.42",
"chao_out": "672.42",
"zhesuan": "675.21",
"day": "2026-09-18",
"time": "09:16:23"
}
]
}
}
```
## 空值情况与展示兜底
2026-09-18 实测 `105-30` 不传 `code` 时共返回 46 条记录，其中 29 种货币五个价位齐全，17 种货币存在空字符串价位。空值的分布有规律：
| 情况 | 数量 | 为空的字段 | 涉及货币简码 |
|------|------|------------|--------------|
| 只有现钞价，没有现汇价 | 11 种 | `hui_in`、`hui_out` | BND、BRL、CZK、ILS、INR、KHR、KWD、NPR、PKR、TWD、VND |
| 只有现汇价，没有现钞价 | 6 种 | `chao_in`、`chao_out` | MUR、MYR、PLN、RON、RSD、ZMW |
人民币（CNY）在同一批返回里五个价位都是 `"100"`，它是这套牌价的折算基准。前端做表格时对空字符串统一显示为 `-`，不要直接参与数值计算，避免出现 `NaN`。
## 与历史接入点的字段差异
历史汇率接入点（105-34）用的是另一套字段名，两者不要混用：
| 汇率查询（105-30） | 查询历史汇率（105-34） |
|--------------------|------------------------|
| `hui_in` 现汇买入价 | `buying_rate` |
| `chao_in` 现钞买入价 | `cash_buying_rate` |
| `hui_out` 现汇卖出价 | `selling_rate` |
| `chao_out` 现钞卖出价 | `cash_selling_rate` |
| `zhesuan` 中行折算价 | `middle_rate` |
| `day` + `time` | `publish_time` |
历史接入点的口径是「100 外币兑人民币」，跨接入点落库时先统一到同一列，再交给前端展示。
## FAQ
**Q1：`ret_code` 非 0 时有哪些具体取值？**
接口文档只说明 0 为成功、其他为失败，未枚举非 0 取值。实测遇到过的非 0 值是 -1，出现在必填条件未满足时（如历史接入点未传货币参数）。遇到非 0 时以实际返回的 `ret_code` 与 `showapi_res_error` 为准。
**Q2：为什么人民币返回的五个价位都是 100？**
人民币是这套牌价的折算基准，实测五个价位字段都返回 `"100"`。写代码时不要假设非人民币货币也都是完整五价位，空值兜底同样要用在人民币以外的货币上。
**Q3：五个价位都是字符串，直接做算术会怎样？**
会报类型错误。`"669.61"` 是字符串，Python 里 `"669.61" * 2` 会得到重复字符串而不是数值。参与计算前统一转成浮点，并决定展示时保留几位小数。
**Q4：`zhesuan` 能直接拿来算金额换算吗？**
`zhesuan` 是折算基准价。换算金额建议走汇率转换接入点（105-31），它的换算口径与牌价一致，返回结果里还带一个 `rate` 字段，便于核对。
**Q5：`showapi_res_id` 有什么用？**
它是本次请求的唯一标识。排查调用异常时把它提供给客服，对方可以直接定位到具体的请求记录。
## 下一步阅读
- [银行汇率查询：5 分钟从注册跑到第一次调用](https://www.showapi.com/guides/exchange-rate-quickstart-105)：还没跑通第一次请求的话从这篇开始。
- [银行汇率查询：汇率转换只需 3 个必填参数](https://www.showapi.com/guides/exchange-rate-convert-guide-105)：用接口做金额换算，返回 `money` 与 `rate`。
- [银行汇率查询历史汇率接入点：按月取还是按区间取](https://www.showapi.com/guides/exchange-rate-history-guide-105)：历史数据的字段与区间行为说明。
- **本系列共 13 篇**：查看[银行汇率查询指南总目录](https://www.showapi.com/guides/exchange-rate-guides-105)
