워크플로 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/에서 다운로드합니다.
빠른 시작
- 1GET /api/v1/workflow-steps/로 단계와 각 단계가 받아들이는 형식, 출력 형식, 설정을 확인합니다.
- 2이름과 1–10개 단계를 담아 POST /api/v1/workflows/를 보냅니다. 응답의 workflow.automationId를 보관합니다.
- 3파일을 가져오거나 업로드한 뒤, 그 documentId와 Idempotency-Key를 담아 POST /api/v1/automations/{automationId}/runs/를 보냅니다.
- 4상태가 completed가 될 때까지 GET /api/v1/automation-runs/{runId}/를 폴링하거나, 자동화의 모든 실행을 나열합니다.
- 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-pdf | Office 파일 → PDF | — |
| merge-pdf | PDF 2개 이상 → 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를 보내면 재시도한 요청에도 같은 워크플로가 반환됩니다. 워크플로를 만드는 데는 요청 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로 직접 시작한 처리 작업에 대해 전송됩니다.