跳至主要內容

尋找下一個工具

說明文件/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 啟動的處理工作傳送。

相關指南