Site icon Little Marketing Book

Impaginazione pronta per l’invio: cosa c’è di nuovo nell’inserimento dei numeri di pagina con l’API Zoho PDF Editor (e come usarla oggi)

respect

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:

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:

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:

Sono previsti limiti chiari:

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:

Esempio: “Pagina X di Y”

Una formula tipica è:

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:

Comportamenti da ricordare:

Perché è importante nella pratica

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

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:

Sono anche indicati i valori predefiniti:

Valori supportati su cui puoi fare affidamento

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

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:

Tipi di numerazione supportati

Sono supportati diversi schemi, tra cui:

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:

Perché la data è importante

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

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:

Offsets: regolazione in pixel per precisione

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

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

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:

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:

Usa i default in modo intenzionale

Oggi è più chiaro che:

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

Introduci sections per layout professionali

Con sections (e opzionalmente range) risolvi problemi tipici:

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:

Riutilizzarle aumenta coerenza e riduce differenze tra progetti.

Rendi il polling resiliente

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

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

Exit mobile version