工作流程 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以 GET /api/v1/workflow-steps/ 查看步驟、每一步接受與輸出的格式以及設定。
- 2傳送 POST /api/v1/workflows/,附上名稱和 1–10 個步驟。保存回應中的 workflow.automationId。
- 3匯入或上傳檔案,然後附上它們的 documentId 和 Idempotency-Key 傳送 POST /api/v1/automations/{automationId}/runs/。
- 4輪詢 GET /api/v1/automation-runs/{runId}/ 直到狀態為 completed,或列出該自動化的所有執行。
- 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-pdf | Office 檔案 → PDF | — |
| merge-pdf | 2 個或更多 PDF → 一個 PDF(僅限第一步) | — |
| compress-pdf | PDF → 更小的 PDF | — |
| rotate-pdf | PDF → PDF | degrees:90、180 或 270 |
| extract-pages | PDF → PDF | pages: "1,3-5"(從 1 開始計數) |
| image-transform | JPG、PNG 或 WebP → JPG、PNG、WebP 或 AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG、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 啟動的處理工作傳送。