金店参考价格：返回字段与状态码全解（ret_code 0/-1、goldPrice/platinumPrice、日期字段）
# 金店参考价格：返回字段与状态码全解（ret_code 0/-1、goldPrice/platinumPrice、日期字段）
> 接口 2145（金店参考价格）· 免费 · 返回 JSON · 适用人群：所有调用者 · 阅读时间约 4 分钟
## 核心要点
- 系统级信封：`showapi_res_code` 0 表示请求成功，业务数据在 `showapi_res_body` 内。
- 业务级 `ret_code`：0 成功；-1 在最新价格接入点表示「没有找到」该品牌。
- 金价相关字段：`goldPrice`、`platinumPrice`、`auLastDate`、`ptLastDate`、`brand`、`_id`、`remark`。
## Why：这跟我有什么关系
调通接口后，最常被卡住的就是「这段 JSON 里每个字段什么意思、出错时看哪个」。本文把金店参考价格的两个接入点返回结构一次讲清，作全系列的可搜速查页。
## What：前置条件与接口速览
**系统级字段（两个接入点一致）**
| 字段 | 类型 | 说明 |
|---|---|---|
| showapi_res_code | Number | 系统级状态码，0 成功 |
| showapi_res_error | String | 系统级错误信息 |
| showapi_res_id | String | 本次请求 id |
| showapi_fee_num | Number | 本次计费条数 |
| showapi_res_body | Object | 业务数据封装对象 |
**2145-1（支持金店）业务字段**
| 字段 | 类型 | 说明 |
|---|---|---|
| ret_code | Number | 0 表示查询成功 |
| data | Object[] | 品牌数组 |
| data[]._id | String | 品牌 id（查价钥匙） |
| data[].brand | String | 品牌中文名 |
**2145-2（最新价格）业务字段**
| 字段 | 类型 | 示例 | 说明 |
|---|---|---|---|
| ret_code | Number | 0 | 0 成功，-1 没有找到 |
| goldPrice | Number | 869 | 黄金参考价格 |
| platinumPrice | Number | 409 | 铂金参考价 |
| brand | String | 周大生 | 品牌中文名 |
| _id | String | 5da958ead3fb8b0eefc6a3d2 | 品牌 id |
| auLastDate | String | 2025-02-07 | 黄金价格日期 |
| ptLastDate | String | 2025-02-07 | 铂金价格日期 |
| remark | String | （空） | 错误信息 |
| showapi_fee_code | Number | 0 | 无意义 |
## How：接入步骤
解析时建议分层判断：
```python
body = resp.json()["showapi_res_body"]
if body["ret_code"] == 0:
# 2145-2：正常拿到金价
print(body["goldPrice"], body["platinumPrice"], body["auLastDate"])
elif body["ret_code"] == -1:
# 2145-2：没有找到该 _id 对应的品牌
print("未找到:", body.get("remark"))
# 2145-1 只需判断 ret_code == 0
```
## 返回示例与解析
**2145-1 返回示例**
```python
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "67a5aa89fb638c27e149bc47",
"showapi_res_body": {
"ret_code": 0,
"data": [
{ "_id": "5da958e9d3fb8b0eefc6a3d1", "brand": "潮宏基" }
]
}
}
```
**2145-2 返回示例**
```python
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "67a5aaf5fb638c27e15696c2",
"showapi_res_body": {
"ret_code": 0,
"platinumPrice": 409,
"_id": "5da958ead3fb8b0eefc6a3d2",
"remark": "",
"auLastDate": "2025-02-07",
"showapi_fee_code": 0,
"ptLastDate": "2025-02-07",
"brand": "周大生",
"goldPrice": 869
}
}
```
## 进阶 / 边界
- `data` 是数组（Object[]），即使只返回一个品牌也是数组，遍历处理最稳妥。
- `showapi_fee_code` 文档标注「无意义」，解析时可忽略。
- `ret_code = -1` 仅最新价格接入点（2145-2）文档显式标注；支持金店（2145-1）文档仅标注 0 表示查询成功。
## FAQ
**Q：ret_code 和 showapi_res_code 有什么区别？**
showapi_res_code 是系统级状态码（0 表示请求本身成功），ret_code 在 showapi_res_body 内、是业务级状态码。两处都建议判断为 0 再取数。
**Q：返回 -1 是什么意思？**
在最新价格接入点（2145-2）中，-1 表示没有找到该 _id 对应的品牌，通常是因为传了错误的或已下线的 _id。
**Q：铂金价字段可能为空吗？**
部分品牌可能未提供铂金价，platinumPrice 可能缺失或为空，前端展示需做空值兜底。
**Q：价格日期和今天不一致正常吗？**
正常。最新价格接入点每天 13:40 更新，auLastDate/ptLastDate 是数据所属的报价日期，不是请求日期。
## 相关能力 / 下一步阅读
- [金店参考价格：5 分钟接入](https://www.showapi.com/guides/gold-price-quickstart-2145)
- [金店参考价格：两步调用工作流](https://www.showapi.com/guides/gold-price-two-step-2145)
- [金店参考价格：最新价格接入点（2145-2）使用指南](https://www.showapi.com/guides/gold-price-latest-price-2145)
- **本系列共 12 篇**：查看[金店参考价格 · 官方指南总目录](https://www.showapi.com/guides/gold-price-guides-2145)
