银行汇率查询：返回字段与状态码全解（ret_code / showapi_res_code / 五大价位）
# 银行汇率查询：返回字段与状态码全解（ret_code / showapi_res_code / 五大价位）
> 接口：银行汇率查询（apiCode=105）· 接入点：汇率查询（105-30）· 免费 · 返回格式：JSON · 适用人群：已接入或即将接入的开发者 · 阅读时间：约 6 分钟
## TL;DR
- 响应有「系统级 + 业务级」两层状态码：`showapi_res_code`（通道）和 `ret_code`（本次查询）。
- 实时牌价核心字段是五大价位：现汇买入 / 现钞买入 / 现汇卖出 / 现钞卖出 / 中行折算价。
- 所有价位字段以**字符串**返回，且人民币（CNY）作为基准货币字段可能不全。
## Why
调通接口只是第一步，真正决定你能否正确展示牌价、做金额换算的，是把每个字段读对。本篇把零散在文档各处的字段、状态码、特殊货币处理一次性讲清，避免你对着返回 JSON 猜含义。
## What
| 项目 | 说明 |
|------|------|
| 系统级字段 | `showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num` |
| 业务封装 | 所有业务数据都在 `showapi_res_body` 对象内 |
| 业务级状态码 | `showapi_res_body.ret_code`，0 为成功，非 0 为失败 |
| 实时牌价字段 | `list[].{name, code, hui_in, chao_in, hui_out, chao_out, zhesuan, day, time}`、`listSize` |
## How
### 两层状态码怎么判断
```python
import requests
js = requests.post(
"https://route.showapi.com/105-30",
params={"appKey": "YOUR_APPKEY"},
data={"code": "EUR"},
timeout=10
).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"], "条")
```
### 五大价位字段对照
| 字段 | 中文 | 业务含义 |
|------|------|---------|
| `hui_in` | 现汇买入价 | 银行用「外汇现汇」向你买入外币的价格 |
| `chao_in` | 现钞买入价 | 银行用「外币现钞」向你买入外币的价格（通常更低） |
| `hui_out` | 现汇卖出价 | 你用人民币向银行买「外汇现汇」的价格 |
| `chao_out` | 现钞卖出价 | 你用人民币向银行买「外币现钞」的价格 |
| `zhesuan` | 中行折算价 | 中国银行内部用于折算的基准价 |
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": 0,
"listSize": 26,
"list": [
{ "name": "人民币", "code": "CNY", "hui_in": "100" }
]
}
}
```
> 注意示例中的人民币（CNY）：只返回了 `hui_in = "100"`，没有 hui_out / chao_out / zhesuan 等字段。人民币是基准货币，字段可能不全，前端不要假设每个货币都有完整五价位。
## 进阶 / 边界
- **字符串而非数字**：`hui_in` 等以字符串返回（如 `"663.94"`），做算术前务必转换类型。
- **空值兜底**：小众货币可能某些价位为空字符串，展示层需判空，避免页面显示 `None`/`NaN`。
- **历史接入点字段不同**：历史汇率（105-34）用的是 `buying_rate` / `selling_rate` / `cash_buying_rate` / `cash_selling_rate` / `middle_rate`，字段名与实时不同，详见[历史汇率接入点指南](https://www.showapi.com/guides/exchange-rate-history-guide-105)。
## FAQ
**Q：ret_code 非 0 时有哪些具体错误码？**
文档仅说明 ret_code 为 0 表示成功、非 0 表示失败，未枚举具体非 0 取值。出现非 0 时以接口实际返回的 ret_code 与 showapi_res_error 为准。
**Q：现汇和现钞价格为什么不一样？**
现汇是账面外汇、现钞是实物外币，银行对现钞的买入价通常更低（兑出人民币更少），卖出价也可能不同。具体以银行挂牌为准。
**Q：中行折算价能直接拿来做换算吗？**
折算价是中行内部基准价，可用作参考基准，但做金额换算建议使用[汇率转换接入点](https://www.showapi.com/guides/exchange-rate-convert-guide-105)返回的换算结果，口径更一致。
**Q：为什么人民币只有 hui_in=100？**
人民币是基准货币，文档示例仅返回 hui_in，其余价位字段未给出。代码不要对 CNY 强求完整五价位。
## 相关能力 / 下一步阅读
- [银行汇率查询：5 分钟接入——从注册到第一次实时汇率查询](https://www.showapi.com/guides/exchange-rate-quickstart-105)
- [银行汇率查询：用"历史汇率"接入点拉取任意时段牌价（含 90 天区间）](https://www.showapi.com/guides/exchange-rate-history-guide-105)
- **本系列共 13 篇**：查看[银行汇率查询指南总目录](https://www.showapi.com/guides/exchange-rate-guides-105)
