获取提取

GET /v1/extractions/{id}

通过 ID 获取单个提取记录。此端点主要用于轮询异步提取的结果。

试一试

在 Swagger UI 中交互式测试此端点。

需要认证

在 Authorization 头中包含您的 API 密钥。

请求

请求头

头	值	必需
Authorization	Bearer <token>	是

路径参数

参数	类型	必需	描述
id	string	是	从运行提取端点返回的提取 ID。

代码示例

curl

curl https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345"

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch(
  'https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t',
  { headers: { 'Authorization': `Bearer ${apiKey}` } },
)

const { data } = await response.json()
console.log(data.status, data.extractedData)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.get(
    "https://api.docmap.io/v1/extractions/extract_9k2m4n6p8q0r1s3t",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]
print(data["status"], data["extractedData"])

响应

状态码：200 OK

响应体包含在 data 对象中，包含单个提取记录。

字段

每个字段与运行提取响应相同。

字段	类型	描述
id	string	唯一提取 ID。
userId	string	拥有此提取的用户 ID。
templateId	string	用于提取的模板 ID。
templateName	string	所使用模板的显示名称。
fileName	string	上传文档的原始文件名。
status	"processing" | "completed" | "failed"	当前提取状态。
extractedData	object | null	与模板字段匹配的提取数据。处理中或失败时为 null。
error	string | null	失败时的错误信息。其他情况为 null。
variables	Variable[]	提取过程中使用的模板变量定义数组。
source	"dashboard" | "api"	提取的触发方式。
runId	string | null	批次运行 ID（如果已提供）。
processingTimeMs	number | null	总处理时长（毫秒）。处理中时为 null。
createdAt	string	提取创建时间的 ISO 8601 时间戳。

示例（已完成）

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "completed",
    "extractedData": {
      "vendor_name": "Acme Corp",
      "invoice_number": "INV-2024-001",
      "total_amount": 1250.00
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

示例（处理中）

{
  "data": {
    "id": "extract_9k2m4n6p8q0r1s3t",
    "userId": "uid_a1b2c3d4e5f6",
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "templateName": "Invoice Template",
    "fileName": "invoice-2024-001.pdf",
    "status": "processing",
    "extractedData": null,
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

轮询模式

使用异步提取时，轮询此端点直到状态不再为 "processing"：

TypeScript

async function pollExtraction(extractionId: string, apiKey: string) {
  const maxAttempts = 30
  const intervalMs = 2000

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.docmap.io/v1/extractions/${extractionId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } },
    )

    const { data } = await response.json()

    if (data.status !== 'processing') {
      return data
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }

  throw new Error('Extraction timed out')
}

Python

import time
import requests

def poll_extraction(extraction_id: str, api_key: str):
    max_attempts = 30
    interval_s = 2

    for _ in range(max_attempts):
        response = requests.get(
            f"https://api.docmap.io/v1/extractions/{extraction_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        )

        data = response.json()["data"]

        if data["status"] != "processing":
            return data

        time.sleep(interval_s)

    raise TimeoutError("Extraction timed out")

TIP

建议使用 2 秒的轮询间隔。大多数提取在 5--30 秒内完成。

错误

状态码	错误码	描述
401	UNAUTHORIZED	缺少、无效或已过期的 API 密钥/令牌。
403	FORBIDDEN	该提取属于其他用户。
404	NOT_FOUND	指定 ID 的提取不存在。