API per flussi di lavoro in più passaggi
Crea un flusso di lavoro documentale in più passaggi con una sola chiamata API, eseguilo su un file o su centinaia, segui ogni esecuzione e scarica i risultati.
Risposta breve
Invia POST https://maxscanner.app/api/v1/workflows/ con un elenco di passaggi, per esempio [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. MaxScanner verifica che la catena possa essere eseguita nel cloud, la salva, la collega alla tua chiave API e restituisce un automationId. Avviala con POST /api/v1/automations/{automationId}/runs/ e una Idempotency-Key, seguila con GET /api/v1/automation-runs/{runId}/ e scarica ogni risultato da /api/v1/documents/{documentId}/download/.
Guida rapida
- 1GET /api/v1/workflow-steps/ per vedere i passaggi, cosa accetta e produce ciascuno e le sue impostazioni.
- 2POST /api/v1/workflows/ con un nome e 1–10 passaggi. Conserva workflow.automationId dalla risposta.
- 3Importa o carica i file, poi invia POST /api/v1/automations/{automationId}/runs/ con i loro documentId e una Idempotency-Key.
- 4Interroga GET /api/v1/automation-runs/{runId}/ finché lo stato è completed, oppure elenca tutte le esecuzioni dell’automazione.
- 5Scarica ogni voce di run.outputs con GET /api/v1/documents/{documentId}/download/.
Perché un flusso di lavoro invece di chiamate separate
Un flusso di lavoro tiene la catena dal lato di MaxScanner: il risultato di un passaggio passa direttamente al successivo senza tornare al tuo server, ogni esecuzione viene ritentata e registrata e i risultati finiscono in I miei documenti. Puoi aprire un flusso creato tramite API in Dashboard → Flussi di lavoro per controllarlo e cambiare la catena in seguito senza ridistribuire il codice: crea un nuovo flusso e sostituisci l’automation id.
Passaggi disponibili
Questi passaggi vengono eseguiti sui processori cloud di MaxScanner, quindi un flusso di lavoro composto da questi passaggi può funzionare senza browser.
| step | Input → output | Impostazioni |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | File di Office → PDF | — |
| merge-pdf | 2 o più PDF → un PDF (solo come primo passaggio) | — |
| compress-pdf | PDF → PDF più leggero | — |
| rotate-pdf | PDF → PDF | degrees: 90, 180 o 270 |
| extract-pages | PDF → PDF | pages: "1,3-5" (numerazione da 1) |
| image-transform | JPG, PNG o WebP → JPG, PNG, WebP o AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG, PNG o WebP → testo (inglese) | — |
Creare un flusso di lavoro
I passaggi vengono eseguiti nell’ordine in cui li elenchi e ognuno deve accettare ciò che produce il precedente; se non combaciano, la risposta è 422 workflow_not_runnable con il motivo. Invia una Idempotency-Key perché una richiesta ripetuta restituisca lo stesso flusso di lavoro. Creare un flusso di lavoro costa una richiesta (un credito nei piani a pagamento) e ogni chiave può avere fino a 25 flussi di lavoro attivi.
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" }
]
}'Eseguirlo su un file o su molti
Gli input sono documenti già presenti nell’account: importazioni tramite API, caricamenti completati con /extension/upload/complete/, risultati precedenti e scansioni Android. Ogni esecuzione richiede una Idempotency-Key; ripeterla non avvia mai una seconda esecuzione. Usa "mode": "together" (predefinito) quando i file vanno in un’unica esecuzione, come più PDF per merge-pdf. Usa "mode": "each" per avviare un’esecuzione per file, fino a 100 file in una chiamata. Ogni esecuzione costa 3 crediti nei piani a pagamento e una richiesta nel piano Free; se il limite del piano viene raggiunto a metà, la risposta indica quanti file non sono stati avviati.
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();Seguire le esecuzioni e scaricare i risultati
GET /api/v1/automation-runs/{runId}/ restituisce lo stato (reserved, executing, suspended, completed, failed o cancelled) e, a esecuzione completata, un elenco outputs con documentId, nome del file, tipo e dimensione di ogni file salvato. GET /api/v1/automations/{automationId}/runs/ elenca le ultime 100 esecuzioni con il conteggio per stato, il modo più rapido per seguire una chiamata in blocco. La lettura dello stato è gratuita.
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"Gestire i flussi di lavoro
Anche i flussi di lavoro creati nell’editor visuale possono essere eseguiti dall’API: apri Dashboard → Flussi di lavoro → Versioni → Esegui dall’API e scegli la chiave. L’editor offre anche passaggi che richiedono una persona, come firma, attese e approvazioni; questi restano fuori dai flussi creati tramite API.
- GET /api/v1/workflows/ elenca tutti i flussi di lavoro che questa chiave può avviare, con i loro passaggi
- GET /api/v1/workflows/{workflowId}/ ne restituisce uno
- DELETE /api/v1/workflows/{workflowId}/ lo scollega dalla chiave; i flussi creati tramite API vengono archiviati e le esecuzioni già avviate terminano
- Per cambiare i passaggi, crea un nuovo flusso di lavoro e usa il suo automationId nel codice
Domande frequenti
Devo usare l’editor visuale?
No. POST /api/v1/workflows/ crea il flusso di lavoro da JSON. L’editor è facoltativo: serve per controllarlo o per passaggi non disponibili tramite API.
Qual è la differenza tra "together" ed "each"?
"together" avvia un’esecuzione che riceve tutti gli input, ciò di cui merge-pdf ha bisogno. "each" avvia un’esecuzione separata per ogni input, così un file difettoso non influisce sugli altri e i risultati arrivano man mano che ogni file è pronto.
Quale permesso serve alla chiave?
"Esegui flussi di lavoro salvati" (workflows:run e workflows:read) per creare ed eseguire flussi, "Salva documenti" per importare i file di input e "Leggi documenti" per scaricare i risultati.
Un’esecuzione di un flusso di lavoro invia un webhook quando termina?
Non ancora. Interroga l’esecuzione o l’elenco delle esecuzioni; i webhook vengono inviati per i job di elaborazione avviati direttamente con /jobs, /pipeline, /pdf-job e /media/process.