본문으로 건너뛰기

다음 도구 찾기

문서/API/워크플로 API: 다단계 워크플로 만들고 실행하기
API

워크플로 API: 다단계 워크플로 만들고 실행하기

API 호출 한 번으로 다단계 문서 워크플로를 만들고, 파일 하나 또는 수백 개에 실행하며, 각 실행을 추적하고 결과를 다운로드합니다.

핵심 답변

단계 목록(예: [{"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-pdfPDF 2개 이상 → 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크레딧)이 들며, 키 하나로 활성 워크플로를 최대 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 플랜에서 요청 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}/는 워크플로 하나를 반환합니다
  • 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로 직접 시작한 처리 작업에 대해 전송됩니다.

관련 가이드