二维码生成和识别：返回字段全解（ret_code / flag / imgUrl / retText）
二维码返回字段ret_codeflagimgUrlretText # 二维码生成和识别：返回字段全解（ret_code / flag / imgUrl / retText）
> 接口/接入点：二维码生成和识别（apiCode=887，覆盖 887-1~887-4）· 是否免费：是 · 返回格式：JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 4 分钟
## 核心要点
- 所有接入点业务数据都封装在 `showapi_res_body` 内；系统级字段 `showapi_res_code` 等在外层。
- 成功判据统一用 `ret_code == "0"`，不要依赖 `flag` 字面。
- **结构不一致**：887-4（Base64 识别）返回体**没有 `flag` / `msg`**，只有 `ret_code` + `retText`。
## Why：为什么需要一张速查表
四个接入点返回字段名字相近但结构不同，写错字段名会取不到值或误判失败。本文把四者结构一次性对齐，作为全系列的可搜速查页。
## What：接口与返回结构速览
| 接入点 | 用途 | 关键返回字段 |
|--------|------|--------------|
| 887-1 | 生成 | `ret_code`、`flag`、`msg`、`imgUrl` |
| 887-2 | 识别（上传图片） | `ret_code`、`flag`、`msg`、`retText` |
| 887-3 | 识别（图片地址） | `ret_code`、`flag`、`msg`、`retText` |
| 887-4 | 识别（Base64） | `ret_code`、`retText`（**无 flag/msg**） |
公共外层（每个请求都有）：
| 字段 | 含义 |
|------|------|
| `showapi_res_code` | 系统级状态码，0 正常 |
| `showapi_res_error` | 系统级错误信息 |
| `showapi_res_id` | 本次请求 ID |
| `showapi_res_body` | 业务数据对象，下文所有字段均在其内 |
## How：解析返回的正确姿势
```python
import requests
def call(body_data, api="887-1"):
url = f"https://route.showapi.com/{api}"
resp = requests.post(url, params={"appKey": "YOUR_APPKEY"},
data=body_data, timeout=10)
return resp.json()["showapi_res_body"]
# 生成
gen = call({"content": "https://www.showapi.com"}, "887-1")
if gen.get("ret_code") == "0":
qr_url = gen.get("imgUrl") # 生成才有 imgUrl
# 识别（上传/地址）
rec = call({"imgUrl": "https://example.com/qr.png"}, "887-3")
if rec.get("ret_code") == "0":
text = rec.get("retText") # 识别才有 retText
# 识别（Base64）—— 注意没有 flag/msg
b64 = call({"imgData": "<base64>"}, "887-4")
if b64.get("ret_code") == "0":
text = b64.get("retText")
```
## 返回示例
生成（887-1）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"flag": "ture",
"msg": "操作成功!",
"imgUrl": "http://app2.showapi.com/img/qrCode/201601/1451885183552.jpg"
}
}
```
识别（887-2 / 887-3）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"flag": "true",
"msg": "操作成功!",
"retText": "https://www.showapi.com"
}
}
```
识别（887-4，无 flag/msg）：
```json
{
"showapi_res_body": {
"ret_code": "0",
"retText": "http://www.showapi.com"
}
}
```
## 字段逐项说明
| 字段 | 类型 | 取值 | 说明 |
|------|------|------|------|
| `ret_code` | String | `"0"` 成功，其他失败 | **成功唯一可靠判据** |
| `flag` | String | `true` / `ture` | 是否成功；887-1 示例为 `ture`（疑似拼写），887-2/3 为 `true`；勿据此字面判等 |
| `msg` | String | 文本 | 提示信息；887-4 无此字段 |
| `imgUrl` | String | URL | 生成的二维码图片地址（仅 887-1），12h 清理 |
| `retText` | String | 文本 | 识别出的内容（887-2/3/4） |
> 完整错误排查见[错误码与失败排查](https://www.showapi.com/guides/qrcode-error-handling-887)。
## 进阶 / 边界
- **不要写 `if flag == True`**：`flag` 是字符串，且 887-1 拼写为 `ture`，布尔判断会误判。一律用 `ret_code == "0"`。
- **识别结果可能为空**：识别失败时 `retText` 可能为空串，需结合 `ret_code` 判断。
## FAQ
**Q1：ret_code 和 flag 以哪个为准？**
A：以 `ret_code == "0"` 为准，最稳定。
**Q2：为什么 887-4 没有 flag 和 msg？**
A：文档定义的返回体确实只有 `ret_code` + `retText`，这是真实结构差异，代码里不要再取 flag/msg。
**Q3：imgUrl 和 retText 会同时出现吗？**
A：不会。生成（887-1）返回 `imgUrl`，识别（887-2/3/4）返回 `retText`。
**Q4：showapi_res_code 和 ret_code 什么区别？**
A：前者是系统级（网络/网关）状态，后者是业务状态；业务成功看 `ret_code`。
## 相关能力 / 下一步阅读
- [二维码生成和识别：错误码与失败排查（ret_code 判据与 flag 拼写陷阱）](https://www.showapi.com/guides/qrcode-error-handling-887)
- [二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）](https://www.showapi.com/guides/qrcode-recognition-compare-887)
- [二维码生成和识别：10 个实战避坑清单（100KB 上限 / 12h 清理 / 格式）](https://www.showapi.com/guides/qrcode-best-practices-887)
- **本系列共 12 篇**：查看[二维码生成和识别指南总目录](https://www.showapi.com/guides/qrcode-guides-887)
