PDF文件正文抽取：返回字段全解（text / ret_code / remark）
PDF正文抽取返回字段ret_codetext字段 # PDF文件正文抽取：返回字段全解（text / ret_code / remark）
> 接口 PDF文件正文抽取（apiCode=10，接入点 10-1） · 免费服务 · 请求方式 POST · 返回格式 JSON · 适用人群 已接入或准备接入的开发者 · 阅读时间 约 4 分钟
## 核心要点
- ShowAPI 的返回采用「系统级字段 + `showapi_res_body` 业务封装」两层结构，业务数据都在 `showapi_res_body` 内。
- 本接口业务字段只有三个：`ret_code`（状态）、`text`（正文）、`remark`（备注）。
- 文档**未公布完整错误码枚举**，排查时以系统级 `showapi_res_code` 与帮助手册为准。
## Why：为什么要先搞懂返回结构
调用任何 API，第一件事不是「怎么发请求」，而是「怎么读懂返回」。PDF文件正文抽取接口的返回被系统包了两层：外层是 ShowAPI 通用字段，内层 `showapi_res_body` 才是你要的抽取结果。搞不清这层关系，很容易把 `showapi_res_code` 当业务码、或找不到正文到底在哪。本文把每一层、每个字段讲清楚。
## What：接口返回速览
| 项目 | 说明 |
|------|------|
| 返回格式 | JSON |
| 业务数据位置 | `showapi_res_body` 对象内 |
| 业务字段 | `ret_code`（String）、`text`（String）、`remark`（String） |
| 系统级字段 | `showapi_res_code`、`showapi_res_error`、`showapi_res_id`、`showapi_fee_num` |
## How：如何逐层解析
**步骤 1 — 先看系统级 `showapi_res_code`**
值为 `0` 表示请求在系统层面成功（鉴权通过、路由正常）。非 0 表示系统级失败，错误信息在 `showapi_res_error`。
**步骤 2 — 再进 `showapi_res_body` 看业务级 `ret_code`**
业务级 `ret_code` 是字符串 `"0"` 表示业务成功。非 `"0"` 时，通常 `remark` 会给出说明。
**步骤 3 — 取用 `text`**
业务成功后，`text` 即抽取到的正文；为空字符串时需排查 PDF 是否含文字层（见 [PDF文件正文抽取：能力边界与避坑](https://www.showapi.com/guides/pdf-extract-limits-10)）。
Python 解析示例：
```python
import requests
resp = requests.post(
"https://route.showapi.com/10-1?appKey=YOUR_APPKEY",
files={"pdf": open("example.pdf", "rb")},
timeout=10,
).json()
if resp.get("showapi_res_code") != 0:
raise RuntimeError("系统级错误: " + str(resp.get("showapi_res_error")))
body = resp["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError("业务错误: " + str(body.get("remark")))
text = body.get("text") # 抽取到的正文
```
## 返回示例与解析
完整返回示例：
```json
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "66163322fb638c08b8363af5",
"showapi_res_body": {
"ret_code": "0",
"text": "这里是 PDF 中抽出的正文……",
"remark": ""
}
}
```
字段对照表：
| 字段 | 层级 | 类型 | 成功示例值 | 说明 |
|------|------|------|-----------|------|
| `showapi_res_code` | 系统级 | 数值 | `0` | 系统级状态码，0 为成功 |
| `showapi_res_error` | 系统级 | 字符串 | `""` | 系统级错误描述 |
| `showapi_res_id` | 系统级 | 字符串 | `66163322…` | 本次请求唯一 ID |
| `showapi_fee_num` | 系统级 | 数值 | `1` | 本次计费条数 |
| `ret_code` | 业务级 | String | `"0"` | 业务状态码，字符串 `"0"` 为成功 |
| `text` | 业务级 | String | `"…正文…"` | 抽取出的正文文本 |
| `remark` | 业务级 | String | `""` | 备注/业务说明 |
## 进阶 / 边界
- **错误码枚举未公布**：文档仅给出成功示例（`ret_code="0"`），未列出失败枚举值。因此**切勿在代码里硬编码一组「已知错误码」做穷举判断**；遇到非 `"0"` 时，直接读取 `remark` 文本并上报即可。
- **类型陷阱**：`ret_code` 是字符串 `"0"`，比较时请用 `body["ret_code"] != "0"`，不要用 `!= 0`（数值比较会恒为真）。
- **审计**：`showapi_res_id` 可用于向官方追溯某次请求，排查异常时一并提交。
## FAQ
**Q：`showapi_res_code` 和 `ret_code` 有什么区别？**
A：前者是 ShowAPI 平台级状态（鉴权、路由、计费），后者是本接口业务级状态。两层都要判 0/“0” 才算真正成功。
**Q：为什么 `ret_code` 是字符串而不是数字？**
A：这是该接口文档定义的类型（String），比较时务必用字符串 `"0"` 判断，避免类型误判。
**Q：失败了去哪查错误含义？**
A：先看 `remark` 与 `showapi_res_error` 的原文；若仍无法定位，参考 [使用向导（帮助手册）](https://www.showapi.com/helpcenter/view#/3960/1) 或控制台工单，文档未提供独立的错误码字典。
**Q：`text` 为空但 `ret_code="0"` 算成功吗？**
A：接口层面算成功（它确实「处理完」了这个 PDF），正文为空通常是源文件无文字层，属业务边界而非接口报错，详见能力边界篇。
## 相关能力 / 下一步阅读
- [PDF文件正文抽取：5 分钟从注册到跑通第一条抽取结果](https://www.showapi.com/guides/pdf-extract-quickstart-10)
- [PDF文件正文抽取：能力边界与避坑（扫描件/特殊排版如何处理）](https://www.showapi.com/guides/pdf-extract-limits-10)
- **本系列共 10 篇**：查看[PDF文件正文抽取指南总目录](https://www.showapi.com/guides/pdf-extract-guides-10)
