Aller au contenu principal

Trouvez votre prochain outil

Documentation/API/API de flux de travail en plusieurs étapes
API

API de flux de travail en plusieurs étapes

Créez un flux de travail documentaire en plusieurs étapes en un seul appel d’API, exécutez-le sur un fichier ou sur des centaines, suivez chaque exécution et téléchargez les résultats.

Réponse courte

Envoyez POST https://maxscanner.app/api/v1/workflows/ avec une liste d’étapes, par exemple [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. MaxScanner vérifie que la chaîne peut s’exécuter dans le cloud, l’enregistre, la relie à votre clé API et renvoie un automationId. Lancez-la avec POST /api/v1/automations/{automationId}/runs/ et une Idempotency-Key, suivez-la avec GET /api/v1/automation-runs/{runId}/ et téléchargez chaque résultat depuis /api/v1/documents/{documentId}/download/.

Démarrage rapide

  1. 1GET /api/v1/workflow-steps/ pour voir les étapes, ce que chacune accepte et produit, et ses réglages.
  2. 2POST /api/v1/workflows/ avec un nom et 1–10 étapes. Conservez workflow.automationId de la réponse.
  3. 3Importez ou envoyez les fichiers, puis faites POST /api/v1/automations/{automationId}/runs/ avec leurs documentId et une Idempotency-Key.
  4. 4Interrogez GET /api/v1/automation-runs/{runId}/ jusqu’à ce que l’état soit completed, ou listez toutes les exécutions de l’automatisation.
  5. 5Téléchargez chaque entrée de run.outputs avec GET /api/v1/documents/{documentId}/download/.

Pourquoi un flux de travail plutôt que des appels séparés

Un flux de travail garde la chaîne du côté de MaxScanner : le résultat d’une étape passe directement à la suivante sans revenir sur votre serveur, chaque exécution est relancée en cas d’échec et enregistrée, et les résultats arrivent dans Mes documents. Vous pouvez ouvrir un flux créé par l’API dans Tableau de bord → Flux de travail pour le vérifier, et modifier la chaîne plus tard sans redéployer votre code : créez un nouveau flux et changez l’automation id.

Étapes disponibles

Ces étapes s’exécutent sur les processeurs cloud de MaxScanner, si bien qu’un flux de travail composé de ces étapes peut tourner sans navigateur.

stepEntrée → sortieRéglages
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfFichier Office → PDF—
merge-pdf2 PDF ou plus → un PDF (première étape uniquement)—
compress-pdfPDF → PDF plus léger—
rotate-pdfPDF → PDFdegrees : 90, 180 ou 270
extract-pagesPDF → PDFpages : "1,3-5" (numérotées à partir de 1)
image-transformJPG, PNG ou WebP → JPG, PNG, WebP ou AVIFformat, quality, maxWidth, maxHeight, width, height, targetBytes
image-ocrJPG, PNG ou WebP → texte (anglais)—

Créer un flux de travail

Les étapes s’exécutent dans l’ordre où vous les indiquez et chacune doit accepter ce que produit la précédente ; sinon, la réponse est 422 workflow_not_runnable avec la raison. Envoyez une Idempotency-Key pour qu’une requête relancée renvoie le même flux de travail. Créer un flux de travail coûte une requête (un crédit sur les offres payantes), et chaque clé peut posséder jusqu’à 25 flux de travail actifs.

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" }
    ]
  }'

L’exécuter sur un fichier ou sur plusieurs

Les entrées sont des documents déjà présents dans le compte : imports par l’API, envois terminés avec /extension/upload/complete/, résultats précédents et numérisations Android. Chaque exécution exige une Idempotency-Key ; la répéter ne lance jamais une deuxième exécution. Utilisez "mode": "together" (par défaut) lorsque les fichiers doivent passer dans une seule exécution, par exemple plusieurs PDF pour merge-pdf. Utilisez "mode": "each" pour lancer une exécution par fichier, jusqu’à 100 fichiers en un appel. Chaque exécution coûte 3 crédits sur les offres payantes et une requête sur l’offre Free ; si la limite de l’offre est atteinte en cours de route, la réponse indique combien de fichiers n’ont pas été lancés.

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();

Suivre les exécutions et télécharger les résultats

GET /api/v1/automation-runs/{runId}/ renvoie l’état (reserved, executing, suspended, completed, failed ou cancelled) et, une fois terminé, une liste outputs avec le documentId, le nom de fichier, le type et la taille de chaque fichier enregistré. GET /api/v1/automations/{automationId}/runs/ liste les 100 dernières exécutions avec un décompte par état, le moyen le plus rapide de suivre un appel en masse. La lecture de l’état est gratuite.

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"

Gérer les flux de travail

Les flux de travail créés dans l’éditeur visuel peuvent aussi être lancés depuis l’API : ouvrez Tableau de bord → Flux de travail → Versions → Exécuter depuis l’API et choisissez la clé. L’éditeur propose aussi des étapes qui nécessitent une personne, comme la signature, les attentes et les validations ; elles restent hors des flux créés par l’API.

  • GET /api/v1/workflows/ liste tous les flux de travail que cette clé peut lancer, avec leurs étapes
  • GET /api/v1/workflows/{workflowId}/ en renvoie un
  • DELETE /api/v1/workflows/{workflowId}/ le déconnecte de la clé ; les flux créés par l’API sont archivés et les exécutions déjà lancées se terminent
  • Pour changer les étapes, créez un nouveau flux de travail et utilisez son automationId dans votre code

Questions fréquentes

Dois-je utiliser l’éditeur visuel ?

Non. POST /api/v1/workflows/ crée le flux de travail à partir de JSON. L’éditeur est facultatif : il sert à le vérifier ou pour des étapes qui ne sont pas disponibles dans l’API.

Quelle est la différence entre "together" et "each" ?

"together" lance une exécution qui reçoit toutes les entrées, ce dont merge-pdf a besoin. "each" lance une exécution distincte par entrée : un fichier défectueux n’affecte pas les autres et les résultats arrivent au fur et à mesure.

Quelle autorisation la clé doit-elle avoir ?

« Exécuter les flux de travail enregistrés » (workflows:run et workflows:read) pour créer et exécuter des flux, « Enregistrer des documents » pour importer les fichiers d’entrée et « Lire les documents » pour télécharger les résultats.

Une exécution de flux de travail envoie-t-elle un webhook à la fin ?

Pas encore. Interrogez l’exécution ou la liste des exécutions ; les webhooks sont envoyés pour les tâches de traitement lancées directement avec /jobs, /pipeline, /pdf-job et /media/process.

Guides associés