运行提取

POST /v1/extractions/run

对 PDF 文档运行提取。文档将使用指定的模板进行处理，提取的数据以与模板字段定义匹配的结构化 JSON 形式返回。

试一试

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

需要认证

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

请求

请求头

头	值	必需
Authorization	Bearer <token>	是
Content-Type	application/json	是

查询参数

参数	类型	必需	描述
async	string	否	设置为 "true" 时立即返回 processing 状态，而不是等待完成。默认行为（省略或 "false"）为同步模式。

请求体

字段	类型	必需	描述
templateId	string	是	要使用的提取模板 ID。
fileName	string	是	文档的原始文件名。
pdfBase64	string	是	PDF 文件的 Base64 编码内容。
mimeType	string	是	文件的 MIME 类型。接受的值：application/pdf、application/vnd.openxmlformats-officedocument.wordprocessingml.document。
runId	string	否	可选标识符，用于将相关提取分组到一个批次中。

代码示例

curl

curl -X POST https://api.docmap.io/v1/extractions/run \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/extractions/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 'tmpl_8f3a2b1c4d5e6f7g',
    fileName: 'invoice-2024-001.pdf',
    pdfBase64: pdfBuffer.toString('base64'),
    mimeType: 'application/pdf',
  }),
})

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

Python

import requests
import base64

api_key = "dm_live_abc123def456ghi789jkl012mno345"

with open("invoice-2024-001.pdf", "rb") as f:
    pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    "https://api.docmap.io/v1/extractions/run",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tmpl_8f3a2b1c4d5e6f7g",
        "fileName": "invoice-2024-001.pdf",
        "pdfBase64": pdf_base64,
        "mimeType": "application/pdf",
    },
)

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

响应

状态码：200 OK

响应体包含在 data 对象中。

字段

字段	类型	描述
id	string	唯一提取 ID（以 extract_ 为前缀）。
userId	string	拥有此提取的用户 ID。
templateId	string	用于提取的模板 ID。
templateName	string	所使用模板的显示名称。
fileName	string	上传文档的原始文件名。
status	"processing" | "completed" | "failed"	当前提取状态。使用异步模式时为 "processing"，成功时为 "completed"，错误时为 "failed"。
extractedData	object | null	与模板字段匹配的提取数据。如果提取失败则为 null。
error	string | null	描述失败原因的错误信息。如果提取成功则为 null。
variables	Variable[]	提取过程中使用的模板变量定义数组。
source	"dashboard" | "api"	提取的触发方式。
runId	string | null	批次运行 ID（如果在请求中提供了的话）。
processingTimeMs	number | 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",
      "invoice_date": "2024-11-15",
      "total_amount": 1250.00,
      "currency": "USD",
      "line_items": [
        {
          "description": "Widget A",
          "quantity": 10,
          "unit_price": 125.00
        }
      ]
    },
    "error": null,
    "variables": [
      {
        "name": "vendor_name",
        "type": "string",
        "description": "Name of the vendor or supplier"
      },
      {
        "name": "total_amount",
        "type": "number",
        "description": "Total invoice amount"
      }
    ],
    "source": "api",
    "runId": null,
    "processingTimeMs": 3842,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

异步模式

默认情况下，API 会等待提取完成后再响应（同步模式）。对于长时间运行的提取，您可以使用异步模式获得即时响应，然后轮询结果。

在 URL 中添加 ?async=true 以启用异步模式：

curl -X POST "https://api.docmap.io/v1/extractions/run?async=true" \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_8f3a2b1c4d5e6f7g",
    "fileName": "invoice-2024-001.pdf",
    "pdfBase64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YW...",
    "mimeType": "application/pdf"
  }'

响应：202 Accepted

响应结构与同步响应相同，但 status 将为 "processing"，extractedData 将为 null，processingTimeMs 将为 null：

{
  "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": [...],
    "source": "api",
    "runId": null,
    "processingTimeMs": null,
    "createdAt": "2024-11-20T14:30:00.000Z"
  }
}

使用返回的 id 轮询获取提取端点，直到 status 变为 "completed" 或 "failed"。

WARNING

如果提取在 "processing" 状态超过 2 分钟，应将其视为失败。系统没有自动超时机制 -- 在极少数情况下（例如服务器重启），记录可能会无限期保持 "processing" 状态。

错误

状态码	错误码	描述
401	UNAUTHORIZED	缺少、无效或已过期的 API 密钥/令牌。
404	NOT_FOUND	指定的模板未找到或不属于您的账户。
429	USAGE_LIMIT_EXCEEDED	您已达到计划的月度提取限额。
500	INTERNAL_ERROR	提取处理过程中发生意外错误。