メインコンテンツへ移動

次に使うツールを探す

ドキュメント/API/ワークフロー API:複数ステップのワークフローを作成・実行
API

ワークフロー API:複数ステップのワークフローを作成・実行

1 回の API 呼び出しでマルチステップの文書ワークフローを作成し、1 ファイルにも数百ファイルにも実行して、各実行を追跡し結果をダウンロードします。

要点

ステップのリスト (例: [{"step":"word-to-pdf"},{"step":"compress-pdf"}]) を付けて POST https://maxscanner.app/api/v1/workflows/ を送信します。MaxScanner はチェーンがクラウドで実行できるかを確認して保存し、API キーに接続して automationId を返します。POST /api/v1/automations/{automationId}/runs/ と Idempotency-Key で開始し、GET /api/v1/automation-runs/{runId}/ で進捗を追い、各出力を /api/v1/documents/{documentId}/download/ からダウンロードします。

クイックスタート

  1. 1GET /api/v1/workflow-steps/ で、ステップと、それぞれが受け付ける形式・出力する形式・設定を確認します。
  2. 2名前と 1–10 個のステップを付けて POST /api/v1/workflows/ を送信します。レスポンスの workflow.automationId を保存します。
  3. 3ファイルをインポートまたはアップロードし、その documentId と Idempotency-Key を付けて POST /api/v1/automations/{automationId}/runs/ を送信します。
  4. 4ステータスが completed になるまで GET /api/v1/automation-runs/{runId}/ をポーリングするか、自動化のすべての実行を一覧表示します。
  5. 5run.outputs の各項目を GET /api/v1/documents/{documentId}/download/ でダウンロードします。

個別の呼び出しではなくワークフローを使う理由

ワークフローならチェーン全体が MaxScanner 側に留まります。各ステップの出力はサーバーに戻らずそのまま次のステップへ渡り、実行ごとに再試行と記録が行われ、結果はマイドキュメントに保存されます。API で作成したワークフローはダッシュボード → ワークフローで確認でき、新しいワークフローを作成して automation id を切り替えれば、コードを再デプロイせずにチェーンを変更できます。

使用できるステップ

これらのステップは MaxScanner のクラウドワーカーで実行されるため、これらで構成したワークフローはブラウザなしで実行できます。

step入力 → 出力設定
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfOffice ファイル → PDF—
merge-pdf2 つ以上の PDF → 1 つの 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 を送ると、再試行したリクエストでも同じワークフローが返されます。ワークフローの作成には 1 リクエスト (有料プランでは 1 クレジット) かかり、1 つのキーで有効なワークフローを最大 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" }
    ]
  }'

1 ファイルにも多数のファイルにも実行

入力はアカウントにすでにあるドキュメントです。API インポート、/extension/upload/complete/ で完了したアップロード、以前の出力、Android のスキャンが使えます。各実行には Idempotency-Key が必要で、同じキーを繰り返しても 2 回目の実行は始まりません。merge-pdf に渡す複数の PDF のように、ファイルを 1 回の実行にまとめる場合は "mode": "together" (既定) を使います。ファイルごとに実行を開始するには "mode": "each" を使い、1 回の呼び出しで最大 100 ファイルまで扱えます。各実行は有料プランで 3 クレジット、Free プランで 1 リクエストかかります。途中でプランの上限に達した場合は、開始されなかったファイル数がレスポンスに示されます。

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) を返し、完了後は保存した各ファイルの documentId・ファイル名・種類・サイズを含む outputs リストを返します。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}/ は 1 つを返します
  • DELETE /api/v1/workflows/{workflowId}/ はキーとの接続を解除します。API で作成したワークフローはアーカイブされ、開始済みの実行は最後まで処理されます
  • ステップを変えるには新しいワークフローを作成し、コードでその automationId を使います

よくある質問

ビジュアルエディターを使う必要はありますか?

いいえ。POST /api/v1/workflows/ は JSON からワークフローを作成します。エディターは任意で、確認したいときや API にないステップを使うときに利用します。

"together" と "each" の違いは何ですか?

"together" はすべての入力を受け取る 1 回の実行を開始します。merge-pdf にはこちらが必要です。"each" は入力ごとに別の実行を開始するため、問題のあるファイルが他に影響せず、各ファイルの処理が終わるたびに結果が届きます。

キーにはどの権限が必要ですか?

ワークフローの作成と実行には「保存済みワークフローの実行」(workflows:run と workflows:read)、入力ファイルのインポートには「ドキュメントの保存」、出力のダウンロードには「ドキュメントの読み取り」が必要です。

ワークフローの実行が終わると webhook は送信されますか?

まだ送信されません。実行または実行一覧をポーリングしてください。webhook は /jobs、/pipeline、/pdf-job、/media/process で直接開始した処理ジョブに対して送信されます。

関連ガイド