跳到主要内容

查找下一个工具

文档/API/工作流 API:创建并运行多步骤工作流
API

工作流 API:创建并运行多步骤工作流

一次 API 调用即可创建多步骤文档工作流,在一个或数百个文件上运行,跟踪每次运行并下载结果。

简要回答

发送 POST https://maxscanner.app/api/v1/workflows/ 并附上步骤列表,例如 [{"step":"word-to-pdf"},{"step":"compress-pdf"}]。MaxScanner 会检查该链能否在云端运行,保存后连接到你的 API 密钥,并返回 automationId。用 POST /api/v1/automations/{automationId}/runs/ 和 Idempotency-Key 启动它,通过 GET /api/v1/automation-runs/{runId}/ 跟踪进度,再从 /api/v1/documents/{documentId}/download/ 下载每个输出。

快速入门

  1. 1用 GET /api/v1/workflow-steps/ 查看步骤、每一步接受和输出的格式以及设置。
  2. 2发送 POST /api/v1/workflows/,附上名称和 1–10 个步骤。保存响应中的 workflow.automationId。
  3. 3导入或上传文件,然后附上它们的 documentId 和 Idempotency-Key 发送 POST /api/v1/automations/{automationId}/runs/。
  4. 4轮询 GET /api/v1/automation-runs/{runId}/ 直到状态为 completed,或列出该自动化的所有运行。
  5. 5用 GET /api/v1/documents/{documentId}/download/ 下载 run.outputs 中的每一项。

为什么用工作流而不是分别调用

工作流把整条链留在 MaxScanner 这边:每一步的输出直接进入下一步,不必返回你的服务器;每次运行都会重试并记录;结果保存到“我的文档”。你可以在 控制台 → 工作流 中打开通过 API 创建的工作流进行检查;以后要更改链条,只需新建工作流并替换 automation id,无需重新部署代码。

可用的步骤

这些步骤在 MaxScanner 的云端 Worker 上运行,因此由它们组成的工作流无需浏览器即可运行。

step输入 → 输出设置
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfOffice 文件 → PDF—
merge-pdf2 个或更多 PDF → 一个 PDF(仅限第一步)—
compress-pdfPDF → 更小的 PDF—
rotate-pdfPDF → PDFdegrees:90、180 或 270
extract-pagesPDF → PDFpages: "1,3-5"(从 1 开始计数)
image-transformJPG、PNG 或 WebP → JPG、PNG、WebP 或 AVIFformat, quality, maxWidth, maxHeight, width, height, targetBytes
image-ocrJPG、PNG 或 WebP → 文本(英文)—

创建工作流

步骤按你列出的顺序运行,每一步都必须接受上一步的输出;不匹配时返回 422 workflow_not_runnable 并说明原因。请发送 Idempotency-Key,这样重试的请求会返回同一个工作流。创建工作流消耗一次请求(付费套餐为一积分),每个密钥最多可拥有 25 个启用的工作流。

curl -X POST 'https://maxscanner.app/api/v1/workflows/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: create-contract-flow-v1' \
  -d '{
    "name": "Contracts to small PDF",
    "steps": [
      { "step": "word-to-pdf" },
      { "step": "compress-pdf" }
    ]
  }'

在一个或多个文件上运行

输入是账户中已有的文档:API 导入、通过 /extension/upload/complete/ 完成的上传、之前的输出以及 Android 扫描件。每次运行都需要 Idempotency-Key;重复使用同一密钥绝不会启动第二次运行。当文件应放在同一次运行中时(例如 merge-pdf 需要的多个 PDF),使用 "mode": "together"(默认)。使用 "mode": "each" 为每个文件各启动一次运行,一次调用最多 100 个文件。付费套餐每次运行消耗 3 积分,Free 套餐消耗一次请求;如果中途达到套餐上限,响应会列出未启动的文件数量。

const res = await fetch(`https://maxscanner.app/api/v1/automations/${automationId}/runs/`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MAXSCANNER_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'contracts-2026-11-11',
  },
  body: JSON.stringify({
    mode: 'each', // one run per document
    inputs: documentIds.map((documentId) => ({ kind: 'document', documentId })),
  }),
});
const { runs, replayedCount, notStarted } = await res.json();

跟踪运行并下载结果

GET /api/v1/automation-runs/{runId}/ 返回状态(reserved、executing、suspended、completed、failed 或 cancelled),完成后还会返回 outputs 列表,包含每个已保存文件的 documentId、文件名、类型和大小。GET /api/v1/automations/{automationId}/runs/ 列出最近 100 次运行及各状态的数量,是跟踪批量调用最快的方法。读取状态免费。

curl 'https://maxscanner.app/api/v1/automation-runs/$RUN_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"

# then, for each output:
curl "https://maxscanner.app/api/v1/documents/$DOCUMENT_ID/download/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"

管理工作流

在可视化编辑器中创建的工作流也能通过 API 运行:打开 控制台 → 工作流 → 版本 → 从 API 运行 并选择密钥。编辑器还提供需要人工参与的步骤,例如签名、等待和审批;这些步骤不会出现在通过 API 创建的工作流中。

  • GET /api/v1/workflows/ 列出此密钥可以启动的所有工作流及其步骤
  • GET /api/v1/workflows/{workflowId}/ 返回其中一个
  • DELETE /api/v1/workflows/{workflowId}/ 断开它与密钥的连接;通过 API 创建的工作流会被归档,已启动的运行会继续完成
  • 要更改步骤,请新建工作流并在代码中改用它的 automationId

常见问题

一定要使用可视化编辑器吗?

不需要。POST /api/v1/workflows/ 会根据 JSON 创建工作流。编辑器是可选的,用于检查工作流或使用 API 中没有的步骤。

"together" 和 "each" 有什么区别?

"together" 启动一次接收所有输入的运行,merge-pdf 需要这种方式。"each" 为每个输入各启动一次运行,因此一个有问题的文件不会影响其他文件,每个文件完成后就会返回结果。

密钥需要什么权限?

创建和运行工作流需要“运行已保存的工作流”(workflows:run 和 workflows:read),导入输入文件需要“保存文档”,下载输出需要“读取文档”。

工作流运行结束时会发送 webhook 吗?

暂时不会。请轮询运行或运行列表;webhook 会针对直接通过 /jobs、/pipeline、/pdf-job 和 /media/process 启动的处理任务发送。

相关指南