Il grande cambiamento: dall’editing nel browser all’automazione per sviluppatori

Zoho PDF Editor è nato come uno strumento web: apri un PDF, apporti modifiche e scarichi il risultato. Questo approccio funziona quando una persona gestisce i documenti uno alla volta, ma diventa un collo di bottiglia quando i team devono elaborare PDF su larga scala—contratti, pacchetti di onboarding, fatture o report lunghi che devono essere suddivisi e inoltrati automaticamente.

Con il tempo, Zoho è passato dalle sole “funzioni da editor” a un modello più orientato alle API. Invece di dipendere da un’interfaccia utente, oggi gli sviluppatori possono eseguire operazioni sulle pagine tramite endpoint REST all’interno di flussi di lavoro automatizzati. Questa evoluzione ha cambiato il modo in cui le aziende gestiscono attività ripetitive sui documenti: l’estrazione diventa un passaggio backend attivato da un evento dell’app (upload, approvazione, invio di un modulo), non un’azione manuale fatta dopo aver scaricato il file.

Com’era “prima”

In passato, estrarre pagine era soprattutto un’operazione rivolta all’utente. Qualcuno apriva un PDF, selezionava le pagine da estrarre e salvava il risultato. Andava bene per attività occasionali, ma non scalava. Qualunque flusso che richiedesse coerenza—ad esempio estrarre sempre le pagine di firma o isolare una sezione specifica di un report—dipendeva dal fatto che le persone eseguissero correttamente gli stessi passaggi ogni volta.

Cosa cambia “oggi”

Oggi la stessa azione può essere eseguita in modo programmatico. L’endpoint di estrazione è progettato per prelevare pagine selezionate da un PDF senza aprire un editor. L’output può essere un nuovo PDF o immagini, rendendolo utile per tutto: dall’instradamento dei documenti alla generazione di anteprime nelle applicazioni web.

Cosa fa oggi l’API di estrazione pagine

L’endpoint “Estrai pagine” consente di estrarre pagine specifiche da un PDF e restituirle come:

  • un nuovo PDF (unito o separato per pagina), oppure
  • immagini (JPEG o PNG), a seconda del formato di output scelto.

È particolarmente utile quando vuoi far proseguire nel processo solo una parte del documento—ad esempio una singola pagina firmata, una sezione di riepilogo o un gruppo di pagine necessario per una fase di revisione.

Casi d’uso comuni

I team usano spesso questo endpoint per:

  • Estrarre pagine di firma: isolare le pagine firmate da contratti più lunghi
  • Segmentare report: dividere un report lungo in PDF più piccoli per la distribuzione
  • Creare anteprime: estrarre pagine come immagini per generare miniature o preview di revisione
  • Instradare flussi: inviare solo pagine specifiche a sistemi downstream (archiviazione, analisi, approvazione)

Requisiti prima di chiamare l’endpoint

Un’integrazione riuscita di solito dipende da tre aspetti: scegliere il dominio corretto, usare un token con lo scope giusto e rispettare i vincoli del file.

Scegliere il dominio del data center corretto

Zoho ospita gli account in più regioni (ad esempio US, EU, IN e altre). Il dominio API da usare dipende da dove è ospitato il tuo account. In pratica, l’URL della richiesta contiene un segnaposto come {zohoapis_domain}, che va sostituito con il dominio regionale corretto per il tuo ambiente.

Se il dominio non corrisponde al data center dell’account, potresti riscontrare problemi di autenticazione o di instradamento delle richieste—quindi consideralo un elemento di configurazione fondamentale, soprattutto per applicazioni multi-tenant o multi-regione.

CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?

Usare lo scope OAuth corretto

Il token di accesso deve includere:

  • ZohoWriter.pdfEditor.ALL

Senza questo scope, l’API non autorizzerà le richieste di estrazione.

Rispettare i vincoli del file di input

Il PDF di input è soggetto a limiti di dimensione (spesso indicati come un massimo di 50 MB nelle note di documentazione e nelle linee guida di implementazione). In ambienti di produzione è consigliabile validare la dimensione del file prima dell’upload, così da evitare fallimenti dopo aver già inviato la richiesta.

L’endpoint da chiamare

Per estrarre pagine, invii una richiesta POST a:

https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/extract

Questo endpoint fa parte del percorso base dell’API:

.../pdfeditor/api/v1

Come sono strutturate le richieste

L’API utilizza dati in formato multipart. In sintesi, invii:

  1. il PDF di input
  2. un oggetto JSON che descrive quali pagine estrarre
  3. un oggetto JSON che descrive come impacchettare e nominare l’output

Input file (obbligatorio)

Puoi fornire il PDF in due modi:

  • Caricando il file direttamente come multipart, oppure
  • fornendo una URL pubblicamente accessibile (a seconda dell’approccio della richiesta)

input_options (JSON obbligatorio)

Questo JSON controlla:

  • page_ranges: quali pagine estrarre
  • format: il formato di output, come pdf, jpeg o png

Pattern di intervalli di pagina utilizzabili

Esempi tipici di selezione:

  • 1,2,5 per pagine specifiche
  • 2-4,7-9 per combinare intervalli
  • -5 per “dalla prima pagina fino alla pagina 5”
  • 7- per “dalla pagina 7 fino all’ultima pagina”

output_settings (JSON)

Questo JSON include di solito:

  • name: nome del file di output
  • single_pdf (opzionale):
    • true per unire le pagine estratte in un solo PDF
    • false per ottenere PDF separati per ogni pagina estratta

Se single_pdf viene omesso, il comportamento predefinito è generalmente un output PDF unico e unito.

Un esempio cURL pulito e funzionante

Di seguito un template corretto e riutilizzabile. Sostituisci dominio, token, percorso file e intervalli:

curl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/pages/extract" \
  --header "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN" \
  --form 'files=@"/path/to/Sample.pdf"' \
  --form 'input_options={"page_ranges":"2-4,7-","format":"pdf"}' \
  --form 'output_settings={"name":"Extracted.pdf","single_pdf":true}'

Flusso basato su job: invio, controllo stato, download

Un dettaglio operativo importante è che l’estrazione viene eseguita come processo pianificato, invece di restituire immediatamente l’output finale.

Cosa ricevi per primo

Dopo l’invio della richiesta, il sistema restituisce una risposta che indica che il job è in corso, insieme a un URL di controllo stato. Questo URL serve per monitorare l’avanzamento.

Come recuperare l’output

Quando l’elaborazione termina con successo, ricevi (o puoi recuperare tramite il flusso di controllo stato) un URL di download che contiene l’identificatore del job. A quel punto la tua applicazione può scaricare il risultato estratto e archiviarlo dove richiesto dal workflow.

Come è cambiata l’integrazione da “prima” a “oggi”

Il cambiamento più significativo è che l’estrazione non richiede più una sessione manuale nell’editor. Quello che prima necessitava di aprire il documento, selezionare pagine e salvare un nuovo file, oggi può essere eseguito automaticamente con una chiamata API.

Non è solo un miglioramento di comodità: cambia il modo in cui le aziende progettano i flussi documentali:

  • Prima: l’estrazione dipendeva da passaggi manuali e dall’accuratezza umana
  • Oggi: l’estrazione può essere integrata nei sistemi, attivata automaticamente e tracciata come job

Questo aumenta la coerenza, accelera l’elaborazione e abilita flussi ad alto volume senza aumentare il personale.

Conclusione

Se il tuo workflow tratta ancora l’estrazione di pagine PDF come un passaggio manuale, stai perdendo un’importante opportunità di automazione. Con l’endpoint “Estrai pagine”, puoi definire regole una volta (ad esempio “estrai sempre la pagina di firma”) e lasciare che l’applicazione esegua il processo in modo affidabile e scalabile.

Se vuoi, posso anche produrre una seconda versione pensata per un pubblico non tecnico (meno codice e più esempi concreti), mantenendo comunque una struttura professionale e chiara.

© Crediti d’immagine a Steve Johnson

CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?

Posted in CRM