Da un PDF a molti: cosa c’è di nuovo nell’API “Split Pages” di Zoho PDF Editor e come usarla oggi (Aggiornamento 2026)

L’API “Split Pages from PDF” di Zoho sembra semplice: invii un PDF, scegli quante pagine devono essere incluse in ogni file di output e scarichi i risultati. Tuttavia, il modo in cui questa funzione viene implementata in un’integrazione reale è cambiato nel tempo: Zoho è passata da un semplice editor online a una suite di API REST per la manipolazione delle pagine, fino ad arrivare a un approccio “storage-first” che permette anche di salvare gli output direttamente in WorkDrive.

Questo articolo aggiornato porta la procedura “ad oggi” e mette in evidenza cosa è cambiato rispetto alle guide precedenti—soprattutto per quanto riguarda gli endpoint regionali, l’archiviazione e i limiti pratici che emergono in produzione.

Perché dividere i PDF via API è più importante oggi rispetto a prima

Prima che le API di manipolazione PDF diventassero comuni, i flussi di lavoro di “split” venivano spesso gestiti manualmente (aprendo un editor PDF e esportando parti del documento) oppure affidati a servizi di terze parti. Funzionava, ma non era scalabile e soprattutto non era ripetibile in modo affidabile.

Con il tempo, Zoho ha spostato il focus da “editor PDF come strumento” a “workflow PDF come API”. Questa evoluzione è fondamentale perché la divisione di un PDF non è più solo una funzione comoda: è diventata un elemento base per pipeline automatizzate—elaborazione documentale legale, suddivisione di estratti conto, pacchetti di onboarding e instradamento interno dei file.

Cosa fa l’API Split Pages (e cosa non fa)

In sostanza, l’API divide un PDF in più PDF in base a un solo parametro: split_by.

Come funziona `split_by`

Indichi quante pagine devono essere incluse in ogni PDF di output. Se il PDF di input ha 10 pagine e split_by è impostato a 2, Zoho genererà 5 PDF da 2 pagine ciascuno.

Per cosa non è pensata questa API

Questo endpoint non è progettato per “scegliere solo determinate pagine”. Se ti servono intervalli specifici o l’estrazione selettiva di pagine, l’ecosistema di API include operazioni pagina più adatte (ad esempio, l’estrazione di pagine).

Cosa è cambiato rispetto alle guide precedenti (note aggiornamento 2026)

Se hai letto tutorial più vecchi (o appunti interni) su questo endpoint, ecco gli aggiornamenti che impattano maggiormente l’implementazione oggi:

Gli endpoint regionali sono più espliciti

In passato molte spiegazioni dicevano “usa l’endpoint della tua regione” senza un quadro chiaro. Oggi Zoho supporta in modo evidente più domini API regionali (US, EU, IN, CN, AU, JP, CA, SA). In ambienti reali questo riduce errori e problemi di autenticazione causati dall’uso dell’host sbagliato.

L’archiviazione è diventata un’opzione di primo livello: Split and Store

Oltre alla divisione e al download, esiste ora un endpoint dedicato che può dividere il PDF e salvare gli output in Zoho WorkDrive. Questo cambia il workflow perché i file finali possono “atterrare” direttamente in un sistema condiviso, senza costringere l’utente a scaricare e poi ricaricare manualmente i documenti.

I limiti di upload sono più chiari

Molte guide iniziali si fermavano a “50 MB max”. Oggi sono più chiari anche altri vincoli e casi di fallimento (ad esempio restrizioni sul numero di pagine e PDF protetti da password non supportati), e questo aiuta a creare una validazione migliore e messaggi più utili per gli utenti.

Le aspettative di gestione errori sono meglio definite

Non si tratta più di “se fallisce, controlla il token”. La struttura degli errori rende più semplice gestire retry sensati, troubleshooting e log di supporto.

Passaggio 1: scegliere il dominio API Zoho corretto per il tuo account

Zoho richiede l’utilizzo del dominio legato al data center (regione) del tuo account. Il percorso base delle API è:

/pdfeditor/api/v1

L’host cambia in base alla regione (ad esempio: US, EU, IN, CN, AU, JP, CA, SA). Questo è importante perché scegliere l’host sbagliato è una causa frequente di errori di autenticazione o comportamenti anomali (richieste “valide” che però non completano correttamente).

Passaggio 2: autenticazione corretta (OAuth + scope)

Devi generare un access token OAuth e inviarlo nell’headerCon il termine header si può fare riferimento sia alla parte superiore di una pagina web che tipica... Leggi di autorizzazione. Lo scope richiesto per le operazioni PDF Editor è:

ZohoWriter.pdfEditor.ALL

(Per l’opzione WorkDrive sono necessari scope aggiuntivi, spiegati più avanti.)

Passaggio 3: inviare la richiesta di split (multipart form-data)

Il formato dell’endpoint è:

POST https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/split

Per dividere un PDF, servono tre input principali:

Input PDF

Puoi fornire il PDF caricandolo come file oppure passando una stringa con un URL pubblicamente accessibile.

Impostazioni di output

Invii JSON per dare un nome al documento di output.

Opzioni di split

Invii la configurazione JSON che include split_by.

Dettaglio importante: differenze nei nomi dei parametri

In pratica, gli sviluppatori notano talvolta che i nomi dei parametri nelle liste possono differire da quelli presenti nei sample. L’approccio più sicuro è:

implementare inizialmente la struttura della richiesta esattamente come nei sample,
se ricevi errori di parametri mancanti, provare i nomi alternativi mantenendo invariato il contenuto JSON.

Esempio pulito in curl

curl --location --request POST "https://www.zohoapis.com/pdfeditor/api/v1/pdf/pages/split" \
  --header "Authorization: Zoho-oauthtoken xxx.yyy.zzz" \
  --form 'files=@"/Users/username/Documents/Sample.pdf"' \
  --form 'input_settings={"split_by":"2"}' \
  --form 'output_settings={"name":"ModifiedFile.pdf"}'

Passaggio 4: gestire il flusso asincrono (controlli stato e download)

L’endpoint Split Pages lavora in modo asincrono. Quando invii la richiesta, Zoho restituisce una risposta di job che include:

un URL di controllo stato
uno stato iniziale come inprogress

Risposta iniziale del job

Riceverai una risposta che include status_check_url e lo stato.

Risposta a completamento

Quando il job termina, Zoho fornisce un download_url e lo stato success.

Flusso di polling affidabile

Un pattern stabile in produzione è:

Inviare la richiesta di split.
Salvare status_check_url come riferimento del job.
Fare polling sull’URL finché lo stato diventa success.
Scaricare i risultati dal download_url.

Se stai costruendo un’automazione seria, aggiungi:

polling con backoff esponenziale (1s → 2s → 4s, ecc.)
timeout massimo
logging legato all’identificativo del job

La nuova opzione Split and Store (workflow con WorkDrive)

Se il tuo obiettivo non è “scaricare localmente” ma “mettere i file dove lavora il team”, l’endpoint di archiviazione WorkDrive è l’upgrade più grande.

Formato endpoint:

POST https://{zohoapis_domain}/pdfeditor/api/v1/pdf/pages/split/store

Cosa puoi configurare oggi

Le impostazioni di output includono:

name
folder_id
comportamento di overwrite opzionale (per controllare se i file esistenti devono essere sostituiti)

Requisiti aggiuntivi

Questo workflow richiede:

un account Zoho WorkDrive
scope OAuth aggiuntivi oltre a PDF Editor (scope WorkDrive)

Perché cambia l’implementazione

Invece di un singolo link di download, le risposte di archiviazione in WorkDrive possono restituire più elementi di output—ognuno con il proprio identificativo e un URL di riferimento. Zoho supporta anche la “partial success”, ovvero alcuni file possono essere salvati correttamente mentre altri falliscono: l’app dovrebbe quindi gestire e comunicare chiaramente risultati misti.

Limiti in produzione e punti di fallimento comuni

Se stai costruendo una funzionalità per utenti reali (non solo un comando una tantum), questi vincoli contano.

Limiti di dimensione file e numero pagine

L’endpoint supporta PDF fino a una dimensione massima (spesso indicata come 50 MB). Inoltre possono esistere limiti sul numero di pagine: PDF molto lunghi possono fallire anche se la dimensione file sembra accettabile.

PDF protetti da password

I PDF protetti da password possono essere rifiutati. Se la tua applicazione accetta upload dagli utenti, conviene prevedere rilevazione e messaggi chiari (ad esempio: “rimuovi la protezione e riprova”).

Dimensioni pagina insolite

Pagine molto grandi (comuni in disegni tecnici o scansioni di grande formato) possono causare errori. Se lavori con documenti in formati grandi, prevedi una validazione o un piano di fallback.

Gestione errori per un’integrazione API moderna

Le guide più vecchie spesso ignoravano la gestione errori. Oggi, una gestione robusta è ciò che distingue un’implementazione “funziona sul mio PC” da una “funziona per tutti gli utenti”.

Cosa include una buona gestione errori

Logging del contesto della richiesta (senza esporre token)
Salvataggio di codici e messaggi di errore
Mappatura degli errori frequenti in messaggi user-friendly
Retry solo quando ha senso (errori temporanei), e fallimento immediato per input non validi

Dove si inserisce lo split in una pipeline completa di automazione PDF

Lo split spesso è solo il primo passo. Molti workflow reali seguono una logica simile:

Dividere un PDF grande in blocchi coerenti
Applicare operazioni sulle pagine (watermark, numerazione pagine, rotazione, eliminazione, sostituzione)
Salvare gli output (spesso in WorkDrive) per condivisione, audit e accesso del team

Questo modo di pensare “a pipeline” è la differenza principale rispetto alle vecchie guide: oggi l’ecosistema di API incoraggia l’unione di più operazioni in un sistema completo di elaborazione documentale.

Casi d’uso pratici che beneficiano di più dagli aggiornamenti

Operazioni di billing e finanza

Estratti conto e report devono spesso essere distribuiti o archiviati in blocchi prevedibili. Dividere per numero fisso di pagine rende più semplice la gestione a valle.

Workflow legali

Allegati ed exhibit di grandi dimensioni spesso superano limiti di upload o email. La divisione in parti migliora l’affidabilità. Salvare i risultati in WorkDrive crea un passaggio pulito ai team interni.

Automazione intake documentale

Quando un PDF in ingresso contiene più documenti “logici” (un pacchetto di moduli, ad esempio), lo split può preparare il file per estrazione, classificazione o instradamento.

Conclusione: l’idea è la stessa, ma l’implementazione “giusta” è cambiata

Il concetto base rimane semplice: carichi (o linki) un PDF, specifichi split_by, monitori il job asincrono e recuperi l’output.

Ciò che è cambiato oggi rispetto agli approcci più vecchi è tutto ciò che sta attorno:

la chiarezza degli endpoint regionali riduce gli errori di configurazione
WorkDrive permette un workflow “split e consegna” senza passaggi manuali di download
vincoli più chiari rendono migliore la validazione e la comunicazione agli utenti
una struttura errori più definita aiuta la risoluzione rapida dei problemi

Se stai aggiornando un’implementazione precedente, il miglior upgrade moderno è trattare lo split come un workflow di job—con polling, validazione e (quando serve) archiviazione diretta in WorkDrive, così l’automazione termina dove il team collabora davvero.