Vai al contenuto principale

Trova il prossimo strumento

Documentazione/Per iniziare/Guida rapida all'API: converti il tuo primo file
Per iniziare

Guida rapida all'API: converti il tuo primo file

Crea una chiave API, invia un file, attendi la fine del job e scarica il risultato, con richieste pronte da copiare e incollare.

Risposta breve

Crea una chiave in Dashboard → API e chiavi, poi invia POST https://maxscanner.app/api/v1/jobs/ con l'URL pubblico di un file, il nome del file e il formato di destinazione. L'API restituisce subito un jobId; interroga GET /api/v1/jobs/{jobId}/ ogni pochi secondi finché status non diventa "completed", poi scarica output.downloadUrl entro cinque minuti.

Guida rapida

  1. 1Apri Dashboard → API e chiavi, scegli Crea chiave API, spunta "Elaborare file" e copia la chiave (viene mostrata una sola volta).
  2. 2Salva la chiave in una variabile d'ambiente come MAXSCANNER_API_KEY, mai nel codice lato client.
  3. 3Invia POST /api/v1/jobs/ con url, filename e format. Conserva il jobId della risposta 202.
  4. 4Chiama GET /api/v1/jobs/{jobId}/ ogni 2–10 secondi finché status non è completed o failed.
  5. 5Scarica subito output.downloadUrl: il link firmato scade dopo cinque minuti.

Prima di iniziare

Ogni richiesta va a https://maxscanner.app/api/v1/ e invia la chiave come token Bearer. Gli URL delle richieste terminano con una barra: un URL senza barra riceve un redirect 308, che la maggior parte dei client HTTP segue, ma includere la barra fa risparmiare un round trip.

Il piano Free consente 10 richieste al giorno e 100 al mese, quanto basta per sviluppare e testare un'integrazione. I piani a pagamento usano invece crediti mensili; ogni endpoint costa da 0 a 3 crediti.

  • URL di base: https://maxscanner.app/api/v1/
  • Header: Authorization: Bearer <your key> (la tua chiave)
  • Corpo: JSON con Content-Type: application/json
  • File: fino a 50 MB tramite importazione da URL o caricamento diretto

Convertire un file Word in PDF

L'endpoint dei job sceglie il processore giusto in base ai formati di input e di output. Passa un URL pubblico e il server scarica il file da solo quando crei il job (fino a 50 MB entro 30 secondi; i reindirizzamenti non vengono seguiti, quindi usa il link finale del file); per i file privati usa invece un caricamento diretto e passa sourceKey (vedi la guida File e caricamenti). Aggiungi un header Idempotency-Key, così una richiesta ripetuta non crea mai un secondo job.

curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-0001' \
  -d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'

Attendere il risultato

I job sono asincroni, così i file di grandi dimensioni non tengono mai aperta la tua connessione HTTP. Interroga l'URL di stato partendo da circa 2 secondi e allungando l'intervallo fino a 10 secondi. Un piccolo file Office di solito termina in meno di 20 secondi; un video 1080p può richiedere alcuni minuti. Quando status è completed, output riporta il tipo di contenuto, la dimensione in byte e un downloadUrl firmato.

curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY"

Prossimi passi

Sostituisci il polling con un webhook quando elabori più di qualche file, leggi la guida ai job per le regole sui nuovi tentativi e scegli la guida dedicata alla funzionalità che ti serve: OCR, strumenti PDF, immagini, media o esecuzione di un flusso di lavoro salvato.

Domande frequenti

Devo installare un SDK?

No. L'API usa semplicemente HTTPS e JSON, quindi funziona con qualsiasi linguaggio o strumento no-code in grado di inviare una richiesta HTTP. La guida agli esempi di codice contiene versioni complete in Node.js, Python, PHP e cURL.

Per quanto tempo resta valido un link di download?

Cinque minuti. Se scade, richiedi di nuovo lo stato del job per ottenere un link nuovo.

Esiste una modalità di test?

Per i test usa il piano Free: offre gli stessi endpoint e limita ogni account a 10 richieste al giorno e 100 al mese.

Guide correlate