Perché questo aggiornamento è importante

Se ti è mai capitato di dover inserire manualmente “Pagina X di Y” in un report, un fascicolo di allegati, un pacchetto di fatture o un documento da consegnare a un cliente, conosci già il problema: PDF generati da fonti diverse, numero di pagine che cambia all’ultimo momento e intestazioni/piè di pagina quasi mai coerenti tra piattaforme. L’API Insert Page Numbers into PDF di Zoho PDF Editor nasce proprio per risolvere questo scenario in modo programmabile, trasformando la paginazione in un passaggio ripetibile del flusso documentale, invece che in una rifinitura manuale.

Le guide “quickstart” più vecchie su questa API tendevano a concentrarsi sull’essenziale: endpoint, caricamento file, segnaposto come <<page_number>> e <<total_pages>>, e una risposta asincrona da interrogare finché non compare un link di download. Quella base è ancora valida. Ciò che è cambiato “da prima a oggi” è quanto l’integrazione possa essere completa e configurabile grazie alle opzioni ora documentate con maggiore chiarezza: intervalli di pagine (sections), valori predefiniti di formattazione dei font, schemi di numerazione, configurazione della data e offset di posizionamento in pixel. Il risultato è meno tentativi, più coerenza e meno sorprese del tipo “Perché a pagina 1 non compare il piè di pagina?”.

Questo articolo spiega come usare l’API oggi e cosa cambia rispetto all’approccio minimo di un tempo, così puoi migliorare l’implementazione senza riscrivere l’intero workflow.

Cosa fa l’API (e a cosa serve)

In sostanza, l’API inserisce numeri di pagina in un PDF. Il vero valore, però, è la personalizzazione: puoi controllare font, stile, schema di numerazione e posizione in intestazione o piè di pagina.

Casi d’uso comuni nel mondo reale

Di solito ricorri a questa API quando vuoi:

  • Paginare automaticamente report, allegati, fatture o pacchetti documentali prima dell’invio.
  • Standardizzare intestazioni e piè di pagina tra PDF generati da sistemi diversi.
  • Aggiungere “Pagina X di Y” senza aprire un editor desktop (e senza contare sulla memoria degli utenti per le regole di formattazione).

Gli obiettivi non sono cambiati, ma la documentazione “di oggi” rende più chiaro come ottenere uno stile uniforme su molti PDF con meno ritocchi manuali.

Endpoint e autenticazione necessari oggi

Per inserire i numeri di pagina, invii una richiesta POST all’endpoint Insert Page Numbers sotto il dominio API regionale del tuo account. (Il dominio esatto varia in base alla regione e alla configurazione dell’account, per questo molte implementazioni lo gestiscono come variabile di ambiente.)

Per effettuare la chiamata, il token OAuth deve includere lo scope:

  • ZohoWriter.pdfEditor.ALL

Cosa è cambiato rispetto ai quickstart precedenti?

In passato, alcune sintesi riportavano l’endpoint in modo più generico o incoerente. Oggi la documentazione è più esplicita sulla struttura dell’endpoint e sull’uso del dominio regionale corretto. Sembra un dettaglio, ma riduce errori di integrazione dovuti a domini sbagliati o configurazioni non allineate.

Struttura della richiesta: multipart form-data con tre parti chiave

Questa API usa una POST multipart/form-data e si basa su tre input principali:

CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?

  1. file (obbligatorio)
  2. input_options (stringa JSON)
  3. output_settings (JSON)

file (obbligatorio)

Puoi fornire il PDF in due modi, usando lo stesso parametro:

  • Caricare un PDF dal tuo sistema (upload file)
  • Fornire un URL pubblicamente accessibile (come stringa)

Sono previsti limiti chiari:

  • Dimensione massima del file: 50 MB
  • Numero massimo di pagine: 150

Cosa è cambiato rispetto ai quickstart precedenti?

Prima questi limiti venivano talvolta citati rapidamente. Oggi sono messi in evidenza vicino al parametro file. In produzione è importante perché puoi validare i requisiti prima dell’upload, evitando job falliti e ritardi a valle.

input_options (stringa JSON)

input_options contiene tutta la configurazione: page_number_settings e i dettagli di layout su dove stampare il testo.

Qui si vede la differenza più grande tra “prima” e “oggi”. Le guide minime spesso si fermavano a: “Metti il testo al centro del piè di pagina”. Oggi puoi definire sections, applicare regole a specifici intervalli di pagine, configurare font e tipi di numerazione, inserire date e regolare la posizione con offset in pixel.

output_settings (JSON)

È la parte più semplice: decidi il nome del PDF in uscita (ad esempio "ModifiedFile.pdf"). Nei flussi automatizzati, spesso si usano convenzioni di naming (es. suffisso -paginated o timestamp) per riconoscere i file elaborati senza aprirli.

I segnaposto che restano fondamentali

L’approccio minimo di un tempo si basava sui segnaposto dentro una stringa, e resta il modo più rapido per ottenere un risultato utile. Due segnaposto chiave sono:

  • <<page_number>>
  • <<total_pages>>

Esempio: “Pagina X di Y”

Una formula tipica è:

  • Pagina <<page_number>> di <<total_pages>>

Poi scegli se visualizzarla in intestazione o piè di pagina, e se allinearla a sinistra, al centro o a destra.

Cosa è cambiato rispetto ai quickstart precedenti?

I segnaposto sono gli stessi, ma oggi è più chiaro dove vanno inseriti (nei campi text dei blocchi di intestazione/piè di pagina) e come riutilizzarli in più sezioni e layout.

L’aggiornamento più importante: sections e intervalli di pagine

La documentazione attuale mette in evidenza (e spiega meglio) il concetto che sblocca layout avanzati: sections.

sections è un elenco di blocchi di configurazione, e ciascun blocco può applicarsi a un intervallo di pagine specifico (o a tutte le pagine per default).

Usare range per colpire pagine specifiche

Puoi impostare un intervallo del tipo:

  • "range": "1-10"

Comportamenti da ricordare:

  • range è opzionale
  • Se non è presente, la configurazione si applica a tutte le pagine

Perché è importante nella pratica

Questa funzione rende possibile una formattazione “da editoria” anche in workflow automatizzati, ad esempio:

  • Numeri romani per le pagine introduttive e numerazione araba per il contenuto principale.
  • Nessuna numerazione sulla copertina (o un piè di pagina diverso).
  • Etichetta “Confidenziale” insieme alla paginazione solo su determinate pagine.
  • Layout diverso per appendici (ad esempio “Appendice — Pagina X di Y”).

Prima, la formattazione per intervalli veniva spesso ignorata; oggi è uno degli strumenti principali quando i PDF hanno frontespizi, indici, appendici o strutture miste.

Controlli di formattazione: font, dimensione e stile (con valori predefiniti)

La documentazione aggiornata definisce un oggetto format che può includere:

  • name (nome del font)
  • size (dimensione del font)
  • style (stile del font)

Sono anche indicati i valori predefiniti:

  • Se non specifichi la formattazione, per default vengono usati Roboto e dimensione 12

Valori supportati su cui puoi fare affidamento

In pratica, puoi trattare la formattazione come un sistema “a strati”:

  • Se ti serve coerenza di brand, specifica font/dimensione/stile.
  • Se ti interessa solo la correttezza e la velocità, affidati ai default per una base consistente.

Cosa è cambiato rispetto ai quickstart precedenti?

Le guide più brevi spesso accennavano alla possibilità di stilizzare, ma senza chiarire i default. Oggi la formattazione è più prevedibile: anche se ometti i dettagli, sai cosa otterrai.

Schemi di numerazione: arabi, lettere, numeri romani e valore iniziale

L’oggetto numbering_config definisce lo schema e il punto di partenza. Due proprietà particolarmente utili sono:

  • type controlla lo schema di numerazione
  • start controlla il numero iniziale

Tipi di numerazione supportati

Sono supportati diversi schemi, tra cui:

  • 1 → 1,2,3
  • a → a,b,c
  • A → A,B,C
  • i → i,ii,iii
  • I → I,II,III

Se non specifichi numbering_config, la numerazione predefinita è 1,2,3.

Cosa è cambiato rispetto ai quickstart precedenti?

Prima, molte guide davano per scontato lo schema 1,2,3. Oggi puoi ottenere layout più “professionali” (ad esempio numeri romani per l’introduzione) senza logiche esterne all’API.

Inserimento data: opzionale, ma ora più chiaro

Un’altra opzione utile “di oggi” è date_config, che permette di inserire una data nel layout insieme alla paginazione, con formati controllati.

Regola importante:

  • Se usi date_config, locale e timezone diventano obbligatori

Perché la data è importante

Nei flussi reali, la data viene spesso affiancata alla paginazione:

  • “Generato il 2026-01-19 | Pagina X di Y”
  • “Data emissione: … | Pagina X di Y”

Locale e timezone evitano incoerenze quando i job partono a cavallo della mezzanotte o quando generi documenti per regioni diverse.

Cosa è cambiato rispetto ai quickstart precedenti?

Le sintesi più vecchie raramente parlavano di inserire date. Oggi è un’opzione documentata con regole di validazione chiare, utile per produrre output coerenti.

Posizionamento in intestazione e piè di pagina: sinistra, centro, destra (almeno uno richiesto)

Le regole di layout sono semplici ma fondamentali:

  • Devi specificare almeno uno tra header o footer
  • In header o footer, devi indicare almeno uno tra left, center o right
  • text è obbligatorio in ogni blocco di posizionamento e può includere <<page_number>> e <<total_pages>>

Offsets: regolazione in pixel per precisione

La documentazione spiega anche offsets, che consente aggiustamenti in pixel tramite:

  • top, bottom, left, right

Gli offset non sono obbligatori, ma diventano essenziali quando devi:

  • Allineare la paginazione a template brandizzati
  • Evitare sovrapposizioni con aree di intestazione predefinite
  • Mantenere spaziature coerenti tra PDF generati da sistemi diversi con margini leggermente differenti

Cosa è cambiato rispetto ai quickstart precedenti?

Prima si vedeva spesso solo “footer center”. Oggi gli offset ti permettono di adattare la paginazione a template esistenti e mantenere allineamenti coerenti.

Un esempio moderno “di oggi” (concettuale)

Per capire quanto sia più potente l’approccio attuale rispetto a quello minimale, immagina una configurazione che:

  • Si applica alle pagine 1–10 (con range)
  • Imposta font/dimensione/stile (con format)
  • Imposta schema e numero iniziale (con numbering_config)
  • Posiziona “Pagina X di Y” in un punto scelto in header/footer
  • Usa offset per micro-regolare la posizione

Il punto non è incollare un JSON identico per tutti, ma comprendere lo “spazio di design” disponibile:

sections + format + numbering_config + (opzionale) date_config + posizionamenti header/footer + offsets

Questo è ciò che trasforma un quickstart in un sistema di impaginazione adatto alla produzione.

Gestione della risposta: job asincrono (e cosa è più chiaro oggi)

Questa API funziona come job asincrono. Dopo l’invio della richiesta, ricevi uno stato “in progress” e un URL di controllo da interrogare.

Quando il job termina con successo, ricevi uno stato di successo e un risultato scaricabile.

status_url vs status_check_url

Alcune descrizioni parlano di “status URL”, mentre negli esempi il campo può avere un nome leggermente diverso. In pratica, considera il valore URL restituito come la fonte di verità e fai polling su quello, invece di hardcodare un nome campo unico.

Cosa è cambiato rispetto ai quickstart precedenti?

Le guide più vecchie spesso dicevano solo “interroga lo stato finché compare un link”. Oggi è più evidente che stai monitorando un job pianificato e che esistono stati distinti (in corso e completato), rendendo più semplice costruire polling robusto e gestione errori.

Guida pratica all’upgrade: come cambia l’implementazione da prima a oggi

Se la tua integrazione “di prima” faceva solo “footer center Pagina X di Y”, non serve buttare tutto. Puoi migliorare a strati.

Mantieni segnaposto e gestione asincrona

La base resta:

  • Invia file, input_options e output_settings come multipart form data.
  • Usa <<page_number>> e <<total_pages>> nel campo text.
  • Fai polling sull’URL di stato finché non ottieni un risultato scaricabile.

Usa i default in modo intenzionale

Oggi è più chiaro che:

  • Font di default: Roboto, dimensione 12
  • Numerazione di default: 1,2,3

Puoi quindi omettere campi non necessari e ottenere comunque output consistente.

Introduci sections per layout professionali

Con sections (e opzionalmente range) risolvi problemi tipici:

  • Avviare la numerazione da una pagina specifica
  • Usare schemi diversi su intervalli diversi
  • Applicare contenuti diversi a parti differenti del documento

Qui sta uno dei cambiamenti più evidenti: la paginazione diventa “consapevole” della struttura del PDF.

Usa offsets quando serve precisione

Negli scenari brandizzati, gli offset aiutano ad allineare correttamente la paginazione a intestazioni grafiche, timbri, footer pre-stampati o firme.

Aggiungi la data solo quando aggiunge valore

Se vuoi “Generato il …” insieme alla paginazione, date_config lo supporta, ma ricordati che locale e timezone diventano obbligatori.

Best practice per uso in produzione

Valida i limiti del file prima dell’upload

Dato il limite di 50 MB e 150 pagine, è utile inserire controlli preventivi per fallire presto e in modo chiaro.

Standardizza un piè di pagina “aziendale” e riusalo ovunque

Definisci una o due stringhe standard:

  • Pagina <<page_number>> di <<total_pages>>
  • oppure una variante con data tramite la tua configurazione

Riutilizzarle aumenta coerenza e riduce differenze tra progetti.

Rendi il polling resiliente

Poiché il processo è asincrono, costruisci un polling che:

  • Legge l’URL di stato restituito nella risposta
  • Esegue retry con attese sensate (idealmente con backoff)
  • Si ferma dopo un limite ragionevole e segnala “ancora in elaborazione” al chiamante

Evita di formattare troppo se non serve

I default sono utili. Se ti servono solo i numeri di pagina, puoi evitare di specificare font e numerazione e ottenere comunque un risultato stabile.

Conclusione: l’API “di oggi” punta alla coerenza, non solo ai numeri

Il modo “di prima” di intendere questo endpoint era: “Aggiungi numeri di pagina”. L’approccio moderno, supportato dalla documentazione attuale, è: costruire un sistema coerente di intestazioni e piè di pagina su tutti i PDF del tuo workflow.

Grazie a sections, intervalli, default di formattazione, schemi di numerazione, regole per la data e offset in pixel, la paginazione diventa un passaggio affidabile e automatico, non un compito di rifinitura dell’ultimo minuto. E poiché l’elaborazione avviene come job asincrono con stati chiari, si integra bene sia in sistemi ad alto volume sia in pipeline documentali occasionali.

© Crediti d’immagine a Sharon Snider

CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?

Posted in CRM