条码生成与识别：返回字段全解（imgUrl / retText / ret_code / msg）
返回字段imgUrlretTextret_code字段速查 # 条码生成与识别：返回字段全解（imgUrl / retText / ret_code / msg）
> 接口/接入点：条码生成与识别（apiCode 1129）· 1129-1/2/3/4 ｜ 是否免费：免费 ｜ 请求方式：POST/GET ｜ 返回格式：JSON ｜ 适用人群：所有开发者 ｜ 阅读时间：约 5 分钟
## TL;DR
- 业务数据都在 `showapi_res_body` 里；系统级字段在 `showapi_res_code`/`showapi_res_error`/`showapi_res_id` 等。
- 生成（1129-1）看 `imgUrl` + `ret_code`；识别（1129-2/3/4）看 `retText` + `ret_code`。
- 可靠字段是 `ret_code` 与 `imgUrl`/`retText`；`msg` 仅 1129-2 示例出现，不要依赖。
## Why：先懂字段再写代码
返回结构统一封装在 `showapi_res_body` 内。搞清楚每个字段的含义与取值，才能在代码里正确判断成功/失败、正确取值，避免"拿到了响应却取错字段"的低级 bug。
## What：返回字段对照
| 接入点 | 字段 | 类型 | 含义 |
|----|----|----|----|
| 全部（系统级） | `showapi_res_code` | int | 系统级状态码，0 通常表示请求被接受 |
| 全部（系统级） | `showapi_res_error` | String | 系统级错误信息 |
| 全部（系统级） | `showapi_res_id` | String | 本次请求标识 |
| 1129-1 生成 | `showapi_res_body.imgUrl` | String | 生成的条码图片链接 |
| 1129-1 生成 | `showapi_res_body.ret_code` | String | 业务码：`"0"` 成功，其他失败 |
| 1129-2/3/4 识别 | `showapi_res_body.retText` | String | 识别出的条码文字 |
| 1129-2/3/4 识别 | `showapi_res_body.ret_code` | String | 业务码：`"0"` 成功，其他失败 |
| 1129-2 识别（示例） | `showapi_res_body.msg` | String | 如 "操作成功!"，非所有接入点都返回 |
> 业务成功以 `showapi_res_body.ret_code == "0"` 为准；该字段为字符串类型，判断时用 `"0"` 而非 `0`。
## How：正确取值（Python）
```python
import requests
APPKEY = "YOUR_APPKEY"
# 生成
gen = requests.post(
f"https://route.showapi.com/1129-1?appKey={APPKEY}",
data={"content": "6901294172197", "formatType": "5"}, timeout=10,
).json()
gb = gen.get("showapi_res_body", {})
if gb.get("ret_code") == "0" and gb.get("imgUrl"):
print("图片:", gb["imgUrl"])
else:
print("生成失败:", gb)
# 识别
rec = requests.post(
f"https://route.showapi.com/1129-3?appKey={APPKEY}",
data={"imgUrl": gb.get("imgUrl", "")}, timeout=10,
).json()
rb = rec.get("showapi_res_body", {})
if rb.get("ret_code") == "0":
print("文字:", rb.get("retText"))
```
## 返回示例与解析
生成：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": { "imgUrl": "http://app2.showapi.com/img/barCodeImg/20160930/xxxx.jpg", "ret_code": "0" }
}
```
识别（1129-2 示例）：
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": { "retText": "6901294172197", "ret_code": 0, "msg": "操作成功!" }
}
```
## 进阶 / 边界
- `ret_code` 在文档中定义为"0 成功，其他失败"，**未枚举具体失败数字**：不要写死对某个特定错误码的判断，统一用 `!= "0"` 即失败处理。
- `msg` 不是可靠字段：仅 1129-2 示例出现，1129-3/1129-4 示例未含，解析时做"有则用、无则忽略"。
- 生成图片 `imgUrl` 每 12 小时删除，取回后及时落盘（见 [12 小时过期策略](https://www.showapi.com/guides/barcode-image-expiry-1129)）。
## FAQ
**Q：showapi_res_code 和 body.ret_code 有什么区别？**
`showapi_res_code` 是系统级（请求是否被网关接受），`body.ret_code` 是业务级（本次生成/识别是否成功）。判断业务成败看 `body.ret_code == "0"`。
**Q：ret_code 是数字还是字符串？**
文档示例里既有 `"0"`（字符串）也有 `0`（数字）写法，解析时建议做容错：`str(rb.get("ret_code")) == "0"`。
**Q：msg 字段总是有吗？**
不是。仅 1129-2 的官方示例出现 `msg`，其余接入点示例无此字段，请勿依赖。
**Q：识别失败 retText 会是什么？**
失败时 `retText` 可能为空或异常值；以 `ret_code != "0"` 判定失败，失败时不采信 `retText`。
## 相关能力 / 下一步阅读
- [条码生成与识别：ret_code 非 0 与识别失败排查指南](https://www.showapi.com/guides/barcode-error-handling-1129)
- [条码生成与识别：5 分钟接入，从注册到生成第一条条码与识别第一张图](https://www.showapi.com/guides/barcode-quickstart-1129)
- [条码识别三种传图方式怎么选：上传图片 / 图片链接 / Base64 实战对比](https://www.showapi.com/guides/barcode-three-input-modes-1129)
- **本系列共 12 篇**：查看[条码生成与识别指南总目录](https://www.showapi.com/guides/barcode-guides-1129)
