Vai al contenuto principale

Trova il prossimo strumento

Documentazione/API/Elaborazione di documenti in blocco con l’API
API

Elaborazione di documenti in blocco con l’API

Converti, comprimi o passa all’OCR centinaia di file: scegli tra job in batch ed esecuzioni di flussi in blocco, resta nei limiti del piano e ripeti solo ciò che non è riuscito.

Risposta breve

Per una conversione in un solo passaggio di fino a 20 file per chiamata, usa POST /api/v1/jobs/batch/ con un array "jobs" e seguila con GET /api/v1/jobs/batch/{batchId}/. Per più passaggi per file, crea un flusso di lavoro e avvialo con "mode": "each" su fino a 100 documenti per chiamata. Dai a ogni chiamata una Idempotency-Key stabile, così un nuovo tentativo avvia solo ciò che manca.

Scegliere lo strumento giusto

Nel piano Free ogni chiamata di elaborazione conta come una delle 10 richieste giornaliere, quindi il lavoro in blocco richiede un piano a pagamento o crediti acquistati.

CompitoUsaPer chiamata
La stessa conversione per molti file (DOCX → PDF)POST /jobs/batch/1–20 file, 2 crediti per batch
Più passaggi per file (converti, comprimi, ruota)Flusso di lavoro + esecuzioni con mode "each"1–100 documenti, 3 crediti per esecuzione
Unire molti file in uno (merge)Flusso di lavoro + esecuzioni con mode "together"fino a 100 documenti in un’esecuzione
Video e audioUn job /media/process/ per file1 file, 1 credito

Conversioni in batch

Ogni elemento accetta gli stessi campi di POST /jobs/: url o sourceKey, filename, format e, facoltativamente, inputFormat. Il batch viene convalidato per intero (la risposta indica l’indice del primo elemento non valido) e ogni elemento diventa un job a sé.

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"

Esecuzioni di flussi di lavoro in blocco

Prima importa o carica i file (ogni importazione restituisce un documentId), poi avvia un’esecuzione per documento in un’unica chiamata. Le esecuzioni vanno in coda e vengono elaborate in ordine su processori condivisi, quindi 100 file di Office richiedono minuti, non secondi; interroga GET /api/v1/automations/{automationId}/runs/ ogni 15–30 secondi e leggi i conteggi per stato.

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"))

Ripetere in sicurezza

  • Ripeti una chiamata di esecuzione in blocco con la stessa Idempotency-Key: le esecuzioni già esistenti vengono saltate (replayedCount) e partono solo quelle mancanti
  • Se compare notStarted, il limite del piano ha fermato la chiamata; aggiungi crediti o attendi il rinnovo, poi ripeti la stessa richiesta
  • Un’esecuzione non riuscita non influisce sulle altre; avvia una nuova esecuzione per quel documento con una nuova Idempotency-Key
  • Tieni al massimo qualche centinaio di esecuzioni in corso; aspetta che counts.completed salga prima di inviare il centinaio successivo

Domande frequenti

C’è un limite alle esecuzioni in coda?

Ogni chiamata avvia al massimo 100 esecuzioni. Non esiste un limite di coda separato, ma le esecuzioni condividono i processori con altri clienti, quindi gli arretrati molto grandi terminano più lentamente. Invia il lavoro in gruppi di qualche centinaio.

Posso ottenere un unico ZIP con tutti i risultati?

Dall’API non ancora. Scarica ogni risultato dal suo documento oppure usa gli strumenti ZIP del sito.

Guide correlate