文档文本获取模式篇

目标：让集成方直接通过 API 取到文档的整篇文本——扫描件 / 图片经 OCR 识别出的全文、数字文档经抽取出的文本，统一从同一个接口获取，并配套「文本就绪」通知。可用于文本展示、回填业务字段、在自家查看器上叠加文本层、人工校对或二次加工。
不在本篇范围：上传与版本管理见文档与版本模式篇；全文检索 / 语义召回见全文搜索与 RAG 检索；事件订阅机制见 Webhook 模式篇。

适用场景

文档文本是「整篇可读文本」这一原语，区别于检索（按查询召回片段）：

在自家查看器上叠加文本层（扫描件可选中 / 复制 / 检索）。
把识别出的文本回填业务字段或交人工校对、二次加工。
纯文本展示、导出、再加工等需要整篇内容的场景。

接口与状态

按版本直取文档文本：

text

GET /v1/versions/text?versionId=${versionId}

响应是一个带状态机的统一结构，数字件与扫描件同款返回：

`status`	含义	处理方式
`READY`	文本已就绪	读 `text`（整篇）/ `pages`（按页）；`source` 标注来源（OCR 识别 / 文本抽取）
`PENDING`	处理中，尚未产出	可轮询或等 webhook，不返回半成品
`FAILED`	产出失败	读 `failReason` 取原因
`NOT_APPLICABLE`	该文件无文本可取	如纯二进制文件、无文本层且未开启 OCR 的 PDF——明确区别于「处理中」「失败」

status 的四态是显式契约：PENDING 表示「还没好、可再来」，NOT_APPLICABLE 表示「这类文件本就取不到、别再轮询」，两者务必分开处理，不要把「不适用」当「失败」重试。

取文本

bash

curl -X GET 'https://atkonbase.example.com/api/v1/versions/text?versionId=${versionId}' \
  -H 'Authorization: Bearer ${clientAccessToken}' \
  -H 'X-Atk-User-Token: ${userToken}'

期望响应（`READY`，关键字段）

json

{
  "code": 0,
  "data": {
    "versionId": "V1000123",
    "status": "READY",
    "source": "OCR",
    "text": "第一页文本……\n第二页文本……",
    "pages": [
      { "page": 1, "text": "第一页文本……", "confidence": 0.98, "coverage": 1.0, "ocrStatus": "ok" },
      { "page": 2, "text": "", "confidence": null, "coverage": null, "ocrStatus": "empty" }
    ]
  }
}

text —— 整篇拼接文本。
pages —— 按页结构；每页带 page（1 基页码）与 text。OCR 来源覆盖文档全部物理页：空白页、识别失败页、超量未处理页也如实出条目、页号连续不偏移，并默认带三个页级信号：
- confidence —— 页级 OCR 置信度均值（0~1，无识别分数时为空）：识别得多准。
- coverage —— 页级 OCR 文本覆盖率（0~1，无文本时为空）：该页多少文本出自 OCR，与 confidence 同域、须配合它解读。覆盖率极低时（如数字件里个别零星字符被补识），confidence 只代表那几个字符、不代表整页，据 coverage 即可判断该分是否可采信。
- ocrStatus —— 页级状态，仅表结构维度：ok（有文本）/ empty（无文本）/ failed（坏页占位）/ unprocessed（超量未处理页占位）。平台不代判「识别质量好坏」——那是业务分界（合同审查与内部归档的可用线天差地别），由消费方按 confidence + coverage 两个原始信号自行分档。
- 文本抽取来源为确定性抽取，无 confidence / coverage / ocrStatus。
source —— 标注文本来源是 OCR 识别还是文本抽取（确切取值见接口参考）。

按页取单页

只要某一页时带 page 参数（1 基），响应的 text 即该页文本、pages 仅含该页：

bash

curl -X GET 'https://atkonbase.example.com/api/v1/versions/text?versionId=${versionId}&page=2' \
  -H 'Authorization: Bearer ${clientAccessToken}' \
  -H 'X-Atk-User-Token: ${userToken}'

结构化 OCR 版面（`includeLayout`）

默认响应给的是「整篇 / 按页纯文本」。若要更细的版面结构——按版面块切段、在原图上按坐标高亮、表格结构化还原与比对、对低置信内容降权——对 OCR 来源的版本带 includeLayout=true，每页会附结构化版面明细 layout：

bash

curl -X GET 'https://atkonbase.example.com/api/v1/versions/text?versionId=${versionId}&includeLayout=true' \
  -H 'Authorization: Bearer ${clientAccessToken}' \
  -H 'X-Atk-User-Token: ${userToken}'

开启后响应在原有字段之上追加：

顶层坐标系与版本自描述：coordinateSystem（原点 / 单位 / 分辨率——PDF 用点坐标、图片用像素坐标，消费方无需猜坐标含义）、engineVersion（识别引擎版本）、schemaVersion（结构版本）。
每页 layout（接口层按原样 JSON 透传、不逐字段建模，其形状以本篇为对外唯一权威），含两组版面块：
- 正文块 blocks：按人眼阅读顺序排列（多栏文档先读完左栏再读右栏），每块带类型标签与块级坐标 bbox。
  - 常见类型：正文、标题、列表、行间公式、图片、表格、图表、代码等（类型值为稳定的英文枚举串，如 text / title / table）。其中图表、代码类型仅在文档确有该版面时才出现，消费方不应假定其必然出现。
  - 文本块下含行 lines、行下含 span：每个 span 带文本 content、坐标 bbox 与识别分数 score；OCR 识别出的 span 给真实识别分数并显式标 ocr: true，数字文本层来源的 span 不带该标记、score 为占位值、不冒充识别分数。
  - 表格块：其正文子块以 HTML 片段 html 返回（标准 <table> 结构，合并单元格用 colspan / rowspan 承载结构），消费方直接渲染或解析 HTML 即得表格；取表格文本一律走 html，不再是行列网格数组。
- 被弃块 discardedBlocks：页眉、页脚、页码、边注、页脚注等非正文内容单列于此、与正文块互斥，且不计入整篇 / 按页 text。需要抬头识别、页码核对等场景可从这里取用。

json

{
  "code": 0,
  "data": {
    "status": "READY",
    "source": "OCR",
    "schemaVersion": "2.0",
    "engineVersion": "…",
    "coordinateSystem": { "origin": "top-left", "unit": "point", "dpi": 72 },
    "pages": [
      {
        "page": 1,
        "text": "……",
        "confidence": 0.98,
        "coverage": 1.0,
        "ocrStatus": "ok",
        "layout": {
          "blocks": [
            { "type": "title", "index": 1, "bbox": [ /* … */ ],
              "lines": [ { "bbox": [ /* … */ ], "spans": [
                { "type": "text", "content": "技术服务合同", "score": 0.998, "ocr": true, "bbox": [ /* … */ ] } ] } ] },
            { "type": "table", "index": 3, "bbox": [ /* … */ ],
              "blocks": [
                { "type": "table_body", "index": 4, "bbox": [ /* … */ ],
                  "html": "<table><tr><td>序号</td><td>金额</td></tr><tr><td>1</td><td>¥120,000</td></tr></table>" } ] }
          ],
          "discardedBlocks": [
            { "type": "page_number", "bbox": [ /* … */ ], "lines": [ /* … */ ] }
          ]
        }
      }
    ]
  }
}

要点：

只对 OCR 来源有值：文本抽取来源不产结构化版面；不带 includeLayout 时响应形态与体积不变（不影响既有纯文本对接）。
终态不返明细：FAILED / NOT_APPLICABLE 只返回状态与原因，不返回页级 / 版面明细。
确定性可复现：同一文件重复调用返回稳定一致的结果（版面块序、行文本、表格 HTML、页级状态均可复现）；engineVersion 涵盖影响结果的完整配置指纹，可据此判断结果是否可能变化、是否需重跑比对基线。
整篇 / 按页 text、status、source、confidence / coverage / ocrStatus 等字段以接口参考为准；layout 的内部版面结构在接口层按原样 JSON 透传，其形状以本篇描述为对外权威。

文本何时就绪

文本是上传发布后异步产出的衍生物。与其轮询，更推荐订阅事件：

document.text_ready webhook：文档文本产出就绪后推送，集成方可免轮询及时获取。仅对真正产出了文本的文档推送，无文本衍生物的文档不会误推。事件订阅与投递机制见 Webhook 模式篇。
需要主动查时，按上面的接口轮询 status：PENDING 继续等，READY 取文本，FAILED / NOT_APPLICABLE 停止。

想在发布前判断「文本是否已就绪、能否安全发布」，可结合文档处理状态查询（见文档与版本模式篇）。

哪些文档有文本

文件类型	文本来源	是否默认产出
数字文档（有文本层的 PDF / Office / 文本等）	文本抽取	默认产出
图片（截图、拍照的证件 / 票据 / 合同等）	OCR 识别	开箱即用
扫描件 / 无文本层 PDF	OCR 识别	按文档类型开关启用（默认不开启）

扫描 PDF 的 OCR 全文按文档类型授予该能力后才产出；不影响数字 PDF 的文本抽取。
无文本层、又未开启 OCR 的 PDF，以及纯二进制文件，查询返回 NOT_APPLICABLE。

访问门控

文本接口的权限延续源文档的访问语义，不另立独立的衍生物权限：

具备源文档读取权即可查询文本状态（status）。
获取文本内容（text / pages）时另校下载权限。
无源文档访问权者取不到文本。

常见坑

⚠️ 把 NOT_APPLICABLE 当失败一直重试：该状态表示这类文件本就取不到文本，重试无意义。规避：四态分开处理，仅 PENDING 才轮询。
⚠️ 发布后立刻取文本拿到 PENDING：文本是异步产出的。规避：订阅 document.text_ready，或对 PENDING 退避轮询。
⚠️ 期望扫描 PDF 默认有 OCR 全文：扫描 PDF 的 OCR 默认不开启，需按文档类型授予。规避：对接前确认该类型是否已开启 OCR 文本能力。
⚠️ 只有读取权就想取文本内容：查状态够读取权，取内容还需下载权限。规避：为需要取文本内容的用户授予源文档下载权限。

下一步

上传、版本与处理状态 → 文档与版本模式篇
文本就绪事件的订阅与投递 → Webhook 模式篇
接口字段与确切取值 → 接口参考

文档文本获取模式篇 ​

适用场景 ​

接口与状态 ​

取文本 ​

期望响应（READY，关键字段） ​

按页取单页 ​

结构化 OCR 版面（includeLayout） ​

文本何时就绪 ​

哪些文档有文本 ​

访问门控 ​

常见坑 ​

下一步 ​

文档文本获取模式篇

适用场景

接口与状态

取文本

期望响应（`READY`，关键字段）

按页取单页

结构化 OCR 版面（`includeLayout`）

文本何时就绪

哪些文档有文本

访问门控

常见坑

下一步