Traitement de documents en masse avec l’API
Convertissez, compressez ou passez à l’OCR des centaines de fichiers : choisissez entre les tâches par lot et les exécutions de flux en masse, restez dans les limites de votre offre et ne relancez que ce qui a échoué.
Réponse courte
Pour une conversion en une étape de jusqu’à 20 fichiers par appel, utilisez POST /api/v1/jobs/batch/ avec un tableau "jobs" et suivez-la avec GET /api/v1/jobs/batch/{batchId}/. Pour plusieurs étapes par fichier, créez un flux de travail et lancez-le avec "mode": "each" sur jusqu’à 100 documents par appel. Donnez à chaque appel une Idempotency-Key stable pour qu’une nouvelle tentative ne lance que ce qui manque.
Choisir le bon outil
Avec l’offre Free, chaque appel de traitement compte comme une des 10 requêtes quotidiennes : le traitement en masse nécessite donc une offre payante ou des crédits achetés.
| Besoin | Utiliser | Par appel |
|---|---|---|
| La même conversion pour de nombreux fichiers (DOCX → PDF) | POST /jobs/batch/ | 1–20 fichiers, 2 crédits par lot |
| Plusieurs étapes par fichier (convertir, compresser, faire pivoter) | Flux de travail + exécutions avec mode "each" | 1–100 documents, 3 crédits par exécution |
| Réunir de nombreux fichiers en un seul (fusion) | Flux de travail + exécutions avec mode "together" | jusqu’à 100 documents en une exécution |
| Vidéo et audio | Une tâche /media/process/ par fichier | 1 fichier, 1 crédit |
Conversions par lots
Chaque élément accepte les mêmes champs que POST /jobs/ : url ou sourceKey, filename, format et, en option, inputFormat. Le lot est validé dans son ensemble (la réponse indique l’index du premier élément invalide) et chaque élément devient sa propre tâche.
curl -X POST 'https://maxscanner.app/api/v1/jobs/batch/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "jobs": [
{ "url": "https://example.com/a.docx", "filename": "a.docx", "format": "pdf" },
{ "url": "https://example.com/b.xlsx", "filename": "b.xlsx", "format": "pdf" }
] }'
curl 'https://maxscanner.app/api/v1/jobs/batch/$BATCH_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"Exécutions de flux de travail en masse
Importez ou envoyez d’abord les fichiers (chaque import renvoie un documentId), puis lancez une exécution par document en un seul appel. Les exécutions sont mises en file d’attente et traitées dans l’ordre sur des processeurs partagés : 100 fichiers Office prennent des minutes, pas des secondes. Interrogez GET /api/v1/automations/{automationId}/runs/ toutes les 15–30 secondes et lisez les décomptes par état.
import os, requests
KEY = os.environ["MAXSCANNER_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://maxscanner.app/api/v1"
doc_ids = [requests.post(f"{BASE}/documents/import/", headers=H, json={"url": u, "filename": u.rsplit("/", 1)[-1]}, timeout=60).json()["documentId"] for u in urls]
r = requests.post(f"{BASE}/automations/{automation_id}/runs/", headers={**H, "Idempotency-Key": "invoices-2026-11"},
json={"mode": "each", "inputs": [{"kind": "document", "documentId": d} for d in doc_ids]}, timeout=60)
print(r.status_code, r.json().get("notStarted"))Relancer sans risque
- Répétez un appel d’exécution en masse avec la même Idempotency-Key : les exécutions qui existent déjà sont ignorées (replayedCount) et seules les manquantes démarrent
- Si notStarted est présent, la limite de l’offre a arrêté l’appel ; ajoutez des crédits ou attendez la réinitialisation, puis répétez la même requête
- Une exécution en échec n’affecte pas les autres ; lancez une nouvelle exécution pour ce document avec une nouvelle Idempotency-Key
- Ne gardez pas plus de quelques centaines d’exécutions en cours ; attendez que counts.completed augmente avant d’envoyer la centaine suivante
Questions fréquentes
Le nombre d’exécutions en file d’attente est-il limité ?
Chaque appel lance au plus 100 exécutions. Il n’y a pas de limite de file séparée, mais les exécutions partagent les processeurs avec d’autres clients, donc les très gros volumes se terminent plus lentement. Envoyez le travail par lots de quelques centaines.
Puis-je obtenir un ZIP de tous les résultats ?
Pas encore depuis l’API. Téléchargez chaque résultat depuis son document, ou utilisez les outils ZIP du site.