Workflow-API für mehrstufige Abläufe
Erstellen Sie einen mehrstufigen Dokument-Workflow mit einem einzigen API-Aufruf, führen Sie ihn für eine oder Hunderte Dateien aus, verfolgen Sie jeden Lauf und laden Sie die Ergebnisse herunter.
Kurze Antwort
Senden Sie POST https://maxscanner.app/api/v1/workflows/ mit einer Liste von Schritten, zum Beispiel [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. MaxScanner prüft, ob die Kette in der Cloud laufen kann, speichert sie, verknüpft sie mit Ihrem API-Schlüssel und liefert eine automationId. Starten Sie sie mit POST /api/v1/automations/{automationId}/runs/ und einem Idempotency-Key, verfolgen Sie sie mit GET /api/v1/automation-runs/{runId}/ und laden Sie jedes Ergebnis über /api/v1/documents/{documentId}/download/ herunter.
Schnellstart
- 1GET /api/v1/workflow-steps/, um die Schritte zu sehen: was jeder annimmt und erzeugt und welche Einstellungen er hat.
- 2POST /api/v1/workflows/ mit einem Namen und 1–10 Schritten. Merken Sie sich workflow.automationId aus der Antwort.
- 3Importieren oder laden Sie die Dateien hoch und senden Sie dann POST /api/v1/automations/{automationId}/runs/ mit ihren documentId und einem Idempotency-Key.
- 4Fragen Sie GET /api/v1/automation-runs/{runId}/ ab, bis der Status completed ist, oder listen Sie alle Läufe der Automatisierung auf.
- 5Laden Sie jeden Eintrag von run.outputs mit GET /api/v1/documents/{documentId}/download/ herunter.
Warum ein Workflow statt einzelner Aufrufe
Ein Workflow hält die Kette auf der Seite von MaxScanner: Das Ergebnis eines Schritts geht direkt in den nächsten, ohne zu Ihrem Server zurückzukehren, jeder Lauf wird bei Fehlern wiederholt und protokolliert, und die Ergebnisse landen in Meine Dokumente. Einen per API erstellten Workflow können Sie unter Dashboard → Workflows prüfen und die Kette später ändern, ohne Ihren Code neu auszurollen: Erstellen Sie einen neuen Workflow und tauschen Sie die automation id aus.
Verfügbare Schritte
Diese Schritte laufen auf den Cloud-Workern von MaxScanner, daher kann ein daraus gebauter Workflow ohne Browser laufen.
| step | Eingabe → Ausgabe | Einstellungen |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | Office-Datei → PDF | — |
| merge-pdf | 2 oder mehr PDFs → ein PDF (nur als erster Schritt) | — |
| compress-pdf | PDF → kleineres PDF | — |
| rotate-pdf | PDF → PDF | degrees: 90, 180 oder 270 |
| extract-pages | PDF → PDF | pages: "1,3-5" (Zählung ab 1) |
| image-transform | JPG, PNG oder WebP → JPG, PNG, WebP oder AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG, PNG oder WebP → Text (Englisch) | — |
Workflow erstellen
Die Schritte laufen in der angegebenen Reihenfolge, und jeder Schritt muss annehmen, was der vorherige erzeugt; passt das nicht, lautet die Antwort 422 workflow_not_runnable mit dem Grund. Senden Sie einen Idempotency-Key, damit eine wiederholte Anfrage denselben Workflow liefert. Das Erstellen eines Workflows kostet eine Anfrage (einen Credit in bezahlten Tarifen), und jeder Schlüssel kann bis zu 25 aktive Workflows besitzen.
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" }
]
}'Für eine oder viele Dateien ausführen
Eingaben sind Dokumente, die bereits im Konto liegen: API-Importe, mit /extension/upload/complete/ abgeschlossene Uploads, frühere Ergebnisse und Android-Scans. Jeder Lauf braucht einen Idempotency-Key; eine Wiederholung startet nie einen zweiten Lauf. Verwenden Sie "mode": "together" (Standard), wenn die Dateien in einen Lauf gehören, etwa mehrere PDFs für merge-pdf. Verwenden Sie "mode": "each", um einen Lauf pro Datei zu starten, bis zu 100 Dateien in einem Aufruf. Jeder Lauf kostet 3 Credits in bezahlten Tarifen und eine Anfrage im Free-Tarif; wird das Tariflimit unterwegs erreicht, nennt die Antwort, wie viele Dateien nicht gestartet wurden.
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();Läufe verfolgen und Ergebnisse herunterladen
GET /api/v1/automation-runs/{runId}/ liefert den Status (reserved, executing, suspended, completed, failed oder cancelled) und nach Abschluss eine outputs-Liste mit documentId, Dateiname, Typ und Größe jeder gespeicherten Datei. GET /api/v1/automations/{automationId}/runs/ listet die letzten 100 Läufe mit einer Anzahl pro Status auf, der schnellste Weg, einen Massenaufruf zu verfolgen. Statusabfragen sind kostenlos.
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"Workflows verwalten
Auch im visuellen Editor erstellte Workflows lassen sich über die API starten: Öffnen Sie Dashboard → Workflows → Versionen → Über die API ausführen und wählen Sie den Schlüssel. Der Editor bietet zudem Schritte, die eine Person brauchen, etwa Signieren, Wartezeiten und Freigaben; diese bleiben aus per API erstellten Workflows heraus.
- GET /api/v1/workflows/ listet alle Workflows auf, die dieser Schlüssel starten kann, mit ihren Schritten
- GET /api/v1/workflows/{workflowId}/ liefert einen davon
- DELETE /api/v1/workflows/{workflowId}/ trennt ihn vom Schlüssel; per API erstellte Workflows werden archiviert, bereits gestartete Läufe werden beendet
- Um Schritte zu ändern, erstellen Sie einen neuen Workflow und verwenden Sie dessen automationId in Ihrem Code
Häufige Fragen
Muss ich den visuellen Editor verwenden?
Nein. POST /api/v1/workflows/ erstellt den Workflow aus JSON. Der Editor ist optional, zum Prüfen oder für Schritte, die über die API nicht verfügbar sind.
Was ist der Unterschied zwischen "together" und "each"?
"together" startet einen Lauf, der alle Eingaben erhält, was merge-pdf braucht. "each" startet für jede Eingabe einen eigenen Lauf, sodass eine fehlerhafte Datei die anderen nicht beeinflusst und Ergebnisse eintreffen, sobald jede Datei fertig ist.
Welche Berechtigung braucht der Schlüssel?
„Gespeicherte Workflows ausführen“ (workflows:run und workflows:read), um Workflows zu erstellen und auszuführen, „Dokumente speichern“, um die Eingabedateien zu importieren, und „Dokumente lesen“, um die Ergebnisse herunterzuladen.
Sendet ein Workflow-Lauf am Ende einen Webhook?
Noch nicht. Fragen Sie den Lauf oder die Laufliste ab; Webhooks werden für Verarbeitungsjobs gesendet, die direkt mit /jobs, /pipeline, /pdf-job und /media/process gestartet wurden.