Vai al contenuto principale

Trova il prossimo strumento

Documentazione/API/API per flussi di lavoro in più passaggi
API

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

  1. 1GET /api/v1/workflow-steps/ per vedere i passaggi, cosa accetta e produce ciascuno e le sue impostazioni.
  2. 2POST /api/v1/workflows/ con un nome e 1–10 passaggi. Conserva workflow.automationId dalla risposta.
  3. 3Importa o carica i file, poi invia POST /api/v1/automations/{automationId}/runs/ con i loro documentId e una Idempotency-Key.
  4. 4Interroga GET /api/v1/automation-runs/{runId}/ finché lo stato è completed, oppure elenca tutte le esecuzioni dell’automazione.
  5. 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.

stepInput → outputImpostazioni
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfFile di Office → PDF—
merge-pdf2 o più PDF → un PDF (solo come primo passaggio)—
compress-pdfPDF → PDF più leggero—
rotate-pdfPDF → PDFdegrees: 90, 180 o 270
extract-pagesPDF → PDFpages: "1,3-5" (numerazione da 1)
image-transformJPG, PNG o WebP → JPG, PNG, WebP o AVIFformat, quality, maxWidth, maxHeight, width, height, targetBytes
image-ocrJPG, 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.

Guide correlate