Scansione via API

La scansione via API trasforma un PDF in una copia scansionata realistica con una chiamata REST, adatta a processi automatizzati e integrazioni applicative. Crea il lavoro, carica il PDF e interroga lo stato o attendi il webhook: tre passaggi, da qualsiasi ambiente o linguaggio in grado di inviare una richiesta HTTP. Spazio colore, risoluzione, rotazione, sfocatura, rumore, luminosità, contrasto e bordo sono tutti configurabili.

Come funziona una chiamata

  1. Creare il lavoro

    POST /v1/scan-jobs

    Invia la tua config e, se vuoi, un webhookUrl; ricevi un jobID e una uploadURL prefirmata.

  2. Caricare il PDF

    PUT {uploadURL}

    Esegui il PUT del file direttamente all'indirizzo S3 prefirmato del passaggio precedente: nessun token necessario.

  3. Ritirare la copia scansionata

    GET /v1/scan-jobs/{jobID}

    Interroga lo stato o attendi il webhook; quando il lavoro è completed, scaricala da downloadURL.

Dove si inserisce

Produzione in blocco dal backend

Contratti, fatture e report generati sul server passano direttamente per l'effetto scansione, senza che nessuno ripeta l'operazione a mano sulla pagina web.

Dentro un sistema esistente

Aggiungi a un CRM, un ERP o un sistema di ticket un'azione «esporta copia scansionata» che chiama l'API.

Catene di automazione

CI, n8n, Zapier e simili avviano un lavoro su un evento, e al termine il webhook passa la mano al passaggio successivo.

Code di file consistenti

I lavori sono asincroni: una volta creati vengono elaborati ciascuno per conto proprio, con l'avanzamento consultabile tramite status e createdAfter.

Linguaggi e ambienti

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLRiga di comando / CI
AltroQualsiasi client HTTP

L'API è HTTP e JSON standard: qualsiasi linguaggio o piattaforma di automazione in grado di inviare una richiesta può usarla.

Esempi di codice

API Bearer Token

Il token appartiene al tuo account e puoi rigenerarlo in qualsiasi momento. La scansione via API richiede un account Pro: senza un token valido l'API risponde 401, senza il ruolo Pro risponde 403.

Provalo

Regola i parametri, guarda il corpo della richiesta cambiare di conseguenza, poi esegui le tre chiamate verso l’API.

Parametri di scansione

Una prova chiama l’API con il tuo token e richiede un account Pro; i parametri e il corpo della richiesta restano liberamente consultabili.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

Informazioni lavoro di scansione

esempio
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

Riferimento API

MetodoPercorsoDescrizione
POST/v1/scan-jobsCrea un lavoro di scansione. Invia config e, se serve, webhookUrl; ricevi l'oggetto del lavoro con stato created e una uploadURL prefirmata.
PUT{uploadURL}L'indirizzo S3 prefirmato del passaggio precedente, non su api.lookscanned.ioCarica il PDF di origine con Content-Type: application/pdf e Content-Length. L'indirizzo porta con sé la propria firma: non aggiungere l'intestazione Authorization.
GET/v1/scan-jobs/{jobID}Legge un singolo lavoro, per l'interrogazione periodica. Con created contiene uploadURL, con completed downloadURL.
GET/v1/scan-jobsElenca i tuoi lavori, filtrati per jobID, status o createdAfter.
Statocreatedprocessingcompletedfailed
  • 401 nessun token valido
  • 403 l'account non è Pro
  • 404 lavoro inesistente

Corpo della richiesta

CampoTipoPredefinitoDescrizione
webhookUrlstring · —Viene chiamato una volta quando il lavoro finisce, così non serve interrogare lo stato.
config.colorspace'gray' | 'sRGB' · graygraySpazio colore dell'immagine prodotta; gray è una scansione in bianco e nero.
config.resolutionnumber · 7272Risoluzione dell'immagine prodotta, in DPI.
config.rotatenumber · —Rotazione dell'intero documento, in gradi.
config.rotate_varnumber · —Ampiezza della rotazione casuale pagina per pagina, in gradi: l'aspetto di un foglio appoggiato storto.
config.blurnumber · 00Intensità della sfocatura.
config.noisenumber · 00Intensità del rumore.
config.brightnessnumber · 11Luminosità; 1 la lascia invariata.
config.contrastnumber · 11Contrasto; 1 lo lascia invariato.
config.borderboolean · falsefalseSe aggiungere alla pagina un bordo di scansione.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormato immagine in cui vengono renderizzate le pagine.

Tutti i campi sono facoltativi. I valori di partenza di «Provalo» (risoluzione 150, rotazione 1, luminosità e contrasto 1,3) sono la combinazione consigliata dall'applicazione web, non i valori predefiniti dell'API.

Campi da tenere d'occhio nell'oggetto del lavoro

status
created / processing / completed / failed: determina se i due indirizzi qui sotto sono presenti.
uploadURL
Solo finché è created. Indirizzo di caricamento prefirmato, con scadenza.
downloadURL
Solo quando è completed. Indirizzo di download prefirmato, con scadenza.
inputUploadedAt / completedAt
Quando è terminato il caricamento dell'originale e quando è finito il lavoro; la differenza è il tempo di elaborazione.

Domande frequenti

La scansione via API richiede Pro?

Sì. Senza un token valido l'API risponde 401 e un account privo del ruolo Pro riceve 403. Dopo l'upgrade e l'accesso, il token compare in questa pagina.

Come faccio a sapere quando un lavoro è finito?

In due modi: interrogare GET /v1/scan-jobs/{jobID}, oppure passare un webhookUrl alla creazione del lavoro e lasciare che il servizio richiami una volta.

Il risultato è uguale a quello della scansione sulla pagina web?

Sì. Entrambi usano la stessa implementazione dell'effetto scansione, e spazio colore, risoluzione, rotazione, sfocatura, rumore, luminosità, contrasto e bordo in config sono le opzioni omonime della pagina web: a parità di parametri il risultato è lo stesso. Cambia solo dove avviene l'elaborazione, in locale sulla pagina e da remoto tramite l'API.

Posso salvare gli indirizzi di caricamento e download e riutilizzarli?

Meglio di no. uploadURL e downloadURL sono indirizzi prefirmati a tempo; una volta scaduti bisogna rileggere il lavoro per ottenerne di nuovi.

Quanto dura un lavoro?

Dipende dal numero di pagine e dalla risoluzione. Poche pagine si completano di solito in pochi secondi; risoluzioni più alte o documenti più lunghi richiedono più tempo. La differenza tra inputUploadedAt e completedAt è il tempo effettivamente trascorso.

Cosa faccio se un lavoro fallisce?

Lo stato diventa failed. Le cause abituali sono un file che non è un PDF valido, restrizioni di cifratura o un caricamento interrotto. Verifica che il file si apra e crea un nuovo lavoro.

Posso consultare i lavori passati?

Sì. GET /v1/scan-jobs elenca i tuoi lavori e accetta filtri su jobID, status e createdAfter: abbastanza per una riconciliazione o per riscaricare un file.