Se ti \u00e8 mai capitato di dover inserire manualmente \u201cPagina X di Y\u201d in un report, un fascicolo di allegati, un pacchetto di fatture o un documento da consegnare a un cliente, conosci gi\u00e0 il problema: PDF generati da fonti diverse, numero di pagine che cambia all\u2019ultimo momento e intestazioni\/pi\u00e8 di pagina quasi mai coerenti tra piattaforme. L\u2019API Insert Page Numbers into PDF<\/strong> 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.<\/p>\n\n\n\n Le guide \u201cquickstart\u201d pi\u00f9 vecchie su questa API tendevano a concentrarsi sull\u2019essenziale: endpoint, caricamento file, segnaposto come Questo articolo spiega come usare l\u2019API oggi e cosa cambia rispetto all\u2019approccio minimo di un tempo, cos\u00ec puoi migliorare l\u2019implementazione senza riscrivere l\u2019intero workflow.<\/p>\n\n\n\n In sostanza, l\u2019API inserisce numeri di pagina in un PDF. Il vero valore, per\u00f2, \u00e8 la personalizzazione: puoi controllare font, stile, schema di numerazione e posizione<\/strong> in intestazione o pi\u00e8 di pagina.<\/p>\n\n\n\n Di solito ricorri a questa API quando vuoi:<\/p>\n\n\n\n Gli obiettivi non sono cambiati, ma la documentazione \u201cdi oggi\u201d rende pi\u00f9 chiaro come ottenere uno stile uniforme su molti PDF con meno ritocchi manuali.<\/p>\n\n\n\n Per inserire i numeri di pagina, invii una richiesta POST all\u2019endpoint Insert Page Numbers<\/strong> sotto il dominio API regionale del tuo account. (Il dominio esatto varia in base alla regione e alla configurazione dell\u2019account, per questo molte implementazioni lo gestiscono come variabile di ambiente.)<\/p>\n\n\n\n Per effettuare la chiamata, il token OAuth deve includere lo scope:<\/p>\n\n\n\n In passato, alcune sintesi riportavano l\u2019endpoint in modo pi\u00f9 generico o incoerente. Oggi la documentazione \u00e8 pi\u00f9 esplicita sulla struttura dell\u2019endpoint e sull\u2019uso del dominio regionale corretto. Sembra un dettaglio, ma riduce errori di integrazione dovuti a domini sbagliati o configurazioni non allineate.<\/p>\n\n\n\n Questa API usa una POST Puoi fornire il PDF in due modi, usando lo stesso parametro:<\/p>\n\n\n\n Sono previsti limiti chiari:<\/p>\n\n\n\n Prima questi limiti venivano talvolta citati rapidamente. Oggi sono messi in evidenza vicino al parametro Qui si vede la differenza pi\u00f9 grande tra \u201cprima\u201d e \u201coggi\u201d. Le guide minime spesso si fermavano a: \u201cMetti il testo al centro del pi\u00e8 di pagina\u201d. Oggi puoi definire sections<\/strong>, applicare regole a specifici intervalli di pagine, configurare font e tipi di numerazione, inserire date e regolare la posizione con offset in pixel.<\/p>\n\n\n\n \u00c8 la parte pi\u00f9 semplice: decidi il nome del PDF in uscita (ad esempio L\u2019approccio minimo di un tempo si basava sui segnaposto dentro una stringa, e resta il modo pi\u00f9 rapido per ottenere un risultato utile. Due segnaposto chiave sono:<\/p>\n\n\n\n Una formula tipica \u00e8:<\/p>\n\n\n\n Poi scegli se visualizzarla in intestazione o pi\u00e8 di pagina, e se allinearla a sinistra, al centro o a destra.<\/p>\n\n\n\n I segnaposto sono gli stessi, ma oggi \u00e8 pi\u00f9 chiaro dove vanno inseriti (nei campi La documentazione attuale mette in evidenza (e spiega meglio) il concetto che sblocca layout avanzati: sections<\/strong>.<\/p>\n\n\n\n Puoi impostare un intervallo del tipo:<\/p>\n\n\n\n Comportamenti da ricordare:<\/p>\n\n\n\n Questa funzione rende possibile una formattazione \u201cda editoria\u201d anche in workflow automatizzati, ad esempio:<\/p>\n\n\n\n Prima, la formattazione per intervalli veniva spesso ignorata; oggi \u00e8 uno degli strumenti principali quando i PDF hanno frontespizi, indici, appendici o strutture miste.<\/p>\n\n\n\n La documentazione aggiornata definisce un oggetto Sono anche indicati i valori predefiniti:<\/p>\n\n\n\n In pratica, puoi trattare la formattazione come un sistema \u201ca strati\u201d:<\/p>\n\n\n\n Le guide pi\u00f9 brevi spesso accennavano alla possibilit\u00e0 di stilizzare, ma senza chiarire i default. Oggi la formattazione \u00e8 pi\u00f9 prevedibile: anche se ometti i dettagli, sai cosa otterrai.<\/p>\n\n\n\n L\u2019oggetto Sono supportati diversi schemi, tra cui:<\/p>\n\n\n\n Se non specifichi Prima, molte guide davano per scontato lo schema 1,2,3. Oggi puoi ottenere layout pi\u00f9 \u201cprofessionali\u201d (ad esempio numeri romani per l\u2019introduzione) senza logiche esterne all\u2019API.<\/p>\n\n\n\n Un\u2019altra opzione utile \u201cdi oggi\u201d \u00e8 Regola importante:<\/p>\n\n\n\n Nei flussi reali, la data viene spesso affiancata alla paginazione:<\/p>\n\n\n\n Locale e timezone evitano incoerenze quando i job partono a cavallo della mezzanotte o quando generi documenti per regioni diverse.<\/p>\n\n\n\n Le sintesi pi\u00f9 vecchie raramente parlavano di inserire date. Oggi \u00e8 un\u2019opzione documentata con regole di validazione chiare, utile per produrre output coerenti.<\/p>\n\n\n\n Le regole di layout sono semplici ma fondamentali:<\/p>\n\n\n\n La documentazione spiega anche Gli offset non sono obbligatori, ma diventano essenziali quando devi:<\/p>\n\n\n\n Prima si vedeva spesso solo \u201cfooter center\u201d. Oggi gli offset ti permettono di adattare la paginazione a template esistenti e mantenere allineamenti coerenti.<\/p>\n\n\n\n Per capire quanto sia pi\u00f9 potente l\u2019approccio attuale rispetto a quello minimale, immagina una configurazione che:<\/p>\n\n\n\n Il punto non \u00e8 incollare un JSON identico per tutti, ma comprendere lo \u201cspazio di design\u201d disponibile:<\/p>\n\n\n\n sections + format + numbering_config + (opzionale) date_config + posizionamenti header\/footer + offsets<\/strong><\/p>\n\n\n\n Questo \u00e8 ci\u00f2 che trasforma un quickstart in un sistema di impaginazione adatto alla produzione.<\/p>\n\n\n\n Questa API funziona come job asincrono. Dopo l\u2019invio della richiesta, ricevi uno stato \u201cin progress\u201d e un URL di controllo da interrogare.<\/p>\n\n\n\n Quando il job termina con successo, ricevi uno stato di successo e un risultato scaricabile.<\/p>\n\n\n\n Alcune descrizioni parlano di \u201cstatus URL\u201d, mentre negli esempi il campo pu\u00f2 avere un nome leggermente diverso. In pratica, considera il valore URL restituito come la fonte di verit\u00e0 e fai polling su quello, invece di hardcodare un nome campo unico.<\/p>\n\n\n\n Le guide pi\u00f9 vecchie spesso dicevano solo \u201cinterroga lo stato finch\u00e9 compare un link\u201d. Oggi \u00e8 pi\u00f9 evidente che stai monitorando un job pianificato e che esistono stati distinti (in corso e completato), rendendo pi\u00f9 semplice costruire polling robusto e gestione errori.<\/p>\n\n\n\n Se la tua integrazione \u201cdi prima\u201d faceva solo \u201cfooter center Pagina X di Y\u201d, non serve buttare tutto. Puoi migliorare a strati.<\/p>\n\n\n\n La base resta:<\/p>\n\n\n\n Oggi \u00e8 pi\u00f9 chiaro che:<\/p>\n\n\n\n Puoi quindi omettere campi non necessari e ottenere comunque output consistente.<\/p>\n\n\n\n Con Qui sta uno dei cambiamenti pi\u00f9 evidenti: la paginazione diventa \u201cconsapevole\u201d della struttura del PDF.<\/p>\n\n\n\n Negli scenari brandizzati, gli offset aiutano ad allineare correttamente la paginazione a intestazioni grafiche, timbri, footer pre-stampati o firme.<\/p>\n\n\n\n Se vuoi \u201cGenerato il \u2026\u201d insieme alla paginazione, Dato il limite di 50 MB e 150 pagine, \u00e8 utile inserire controlli preventivi per fallire presto e in modo chiaro.<\/p>\n\n\n\n Definisci una o due stringhe standard:<\/p>\n\n\n\n Riutilizzarle aumenta coerenza e riduce differenze tra progetti.<\/p>\n\n\n\n Poich\u00e9 il processo \u00e8 asincrono, costruisci un polling che:<\/p>\n\n\n\n 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.<\/p>\n\n\n\n Il modo \u201cdi prima\u201d di intendere questo endpoint era: \u201cAggiungi numeri di pagina\u201d. L\u2019approccio moderno, supportato dalla documentazione attuale, \u00e8: costruire un sistema coerente di intestazioni e pi\u00e8 di pagina su tutti i PDF del tuo workflow<\/strong>.<\/p>\n\n\n\n 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\u2019ultimo minuto. E poich\u00e9 l\u2019elaborazione avviene come job asincrono con stati chiari, si integra bene sia in sistemi ad alto volume sia in pipeline documentali occasionali.<\/p>\n\n\n\n \u00a9 Crediti d’immagine a Sharon\u00a0Snider<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<<page_number>><\/code> e <<total_pages>><\/code>, e una risposta asincrona da interrogare finch\u00e9 non compare un link di download. Quella base \u00e8 ancora valida. Ci\u00f2 che \u00e8 cambiato \u201cda prima a oggi\u201d \u00e8 quanto l\u2019integrazione possa essere completa e configurabile<\/strong> 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<\/strong>. Il risultato \u00e8 meno tentativi, pi\u00f9 coerenza e meno sorprese del tipo \u201cPerch\u00e9 a pagina 1 non compare il pi\u00e8 di pagina?\u201d.<\/p>\n\n\n\nCosa fa l\u2019API (e a cosa serve)<\/h2>\n\n\n\n
Casi d\u2019uso comuni nel mondo reale<\/h3>\n\n\n\n
\n
Endpoint e autenticazione necessari oggi<\/h2>\n\n\n\n
\n
ZohoWriter.pdfEditor.ALL<\/code><\/li>\n<\/ul>\n\n\n\nCosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h3>\n\n\n\n
Struttura della richiesta: multipart form-data con tre parti chiave<\/h2>\n\n\n\n
multipart\/form-data<\/code> e si basa su tre input principali:<\/p>\n\n\n\n\n
file<\/code> (obbligatorio)<\/li>\n\n\n\ninput_options<\/code> (stringa JSON)<\/li>\n\n\n\noutput_settings<\/code> (JSON)<\/li>\n<\/ol>\n\n\n\nfile (obbligatorio)<\/h3>\n\n\n\n
\n
\n
Cosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
file<\/code>. In produzione \u00e8 importante perch\u00e9 puoi validare i requisiti prima dell\u2019upload, evitando job falliti e ritardi a valle.<\/p>\n\n\n\ninput_options (stringa JSON)<\/h3>\n\n\n\n
input_options<\/code> contiene tutta la configurazione: page_number_settings<\/code> e i dettagli di layout su dove stampare il testo.<\/p>\n\n\n\noutput_settings (JSON)<\/h3>\n\n\n\n
\"ModifiedFile.pdf\"<\/code>). Nei flussi automatizzati, spesso si usano convenzioni di naming (es. suffisso -paginated<\/code> o timestamp) per riconoscere i file elaborati senza aprirli.<\/p>\n\n\n\nI segnaposto che restano fondamentali<\/h2>\n\n\n\n
\n
<<page_number>><\/code><\/li>\n\n\n\n<<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nEsempio: \u201cPagina X di Y\u201d<\/h3>\n\n\n\n
\n
Pagina <<page_number>> di <<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nCosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
text<\/code> dei blocchi di intestazione\/pi\u00e8 di pagina) e come riutilizzarli in pi\u00f9 sezioni e layout.<\/p>\n\n\n\nL\u2019aggiornamento pi\u00f9 importante: sections e intervalli di pagine<\/h2>\n\n\n\n
sections<\/code> \u00e8 un elenco di blocchi di configurazione, e ciascun blocco pu\u00f2 applicarsi a un intervallo di pagine specifico (o a tutte le pagine per default).<\/p>\n\n\n\nUsare range per colpire pagine specifiche<\/h3>\n\n\n\n
\n
\"range\": \"1-10\"<\/code><\/li>\n<\/ul>\n\n\n\n\n
range<\/code> \u00e8 opzionale<\/li>\n\n\n\nPerch\u00e9 \u00e8 importante nella pratica<\/h4>\n\n\n\n
\n
Controlli di formattazione: font, dimensione e stile (con valori predefiniti)<\/h2>\n\n\n\n
format<\/code> che pu\u00f2 includere:<\/p>\n\n\n\n\n
name<\/code> (nome del font)<\/li>\n\n\n\nsize<\/code> (dimensione del font)<\/li>\n\n\n\nstyle<\/code> (stile del font)<\/li>\n<\/ul>\n\n\n\n\n
Valori supportati su cui puoi fare affidamento<\/h3>\n\n\n\n
\n
Cosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
Schemi di numerazione: arabi, lettere, numeri romani e valore iniziale<\/h2>\n\n\n\n
numbering_config<\/code> definisce lo schema e il punto di partenza. Due propriet\u00e0 particolarmente utili sono:<\/p>\n\n\n\n\n
type<\/code> controlla lo schema di numerazione<\/li>\n\n\n\nstart<\/code> controlla il numero iniziale<\/li>\n<\/ul>\n\n\n\nTipi di numerazione supportati<\/h3>\n\n\n\n
\n
1<\/code> \u2192 1,2,3<\/li>\n\n\n\na<\/code> \u2192 a,b,c<\/li>\n\n\n\nA<\/code> \u2192 A,B,C<\/li>\n\n\n\ni<\/code> \u2192 i,ii,iii<\/li>\n\n\n\nI<\/code> \u2192 I,II,III<\/li>\n<\/ul>\n\n\n\nnumbering_config<\/code>, la numerazione predefinita \u00e8 1,2,3.<\/p>\n\n\n\nCosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
Inserimento data: opzionale, ma ora pi\u00f9 chiaro<\/h2>\n\n\n\n
date_config<\/code>, che permette di inserire una data nel layout insieme alla paginazione, con formati controllati.<\/p>\n\n\n\n\n
date_config<\/code>, locale e timezone diventano obbligatori<\/strong><\/li>\n<\/ul>\n\n\n\nPerch\u00e9 la data \u00e8 importante<\/h3>\n\n\n\n
\n
Cosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
Posizionamento in intestazione e pi\u00e8 di pagina: sinistra, centro, destra (almeno uno richiesto)<\/h2>\n\n\n\n
\n
text<\/code> \u00e8 obbligatorio in ogni blocco di posizionamento e pu\u00f2 includere <<page_number>><\/code> e <<total_pages>><\/code><\/li>\n<\/ul>\n\n\n\nOffsets: regolazione in pixel per precisione<\/h3>\n\n\n\n
offsets<\/code>, che consente aggiustamenti in pixel tramite:<\/p>\n\n\n\n\n
top<\/code>, bottom<\/code>, left<\/code>, right<\/code><\/li>\n<\/ul>\n\n\n\n\n
Cosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
Un esempio moderno \u201cdi oggi\u201d (concettuale)<\/h2>\n\n\n\n
\n
range<\/code>)<\/li>\n\n\n\nformat<\/code>)<\/li>\n\n\n\nnumbering_config<\/code>)<\/li>\n\n\n\nGestione della risposta: job asincrono (e cosa \u00e8 pi\u00f9 chiaro oggi)<\/h2>\n\n\n\n
status_url vs status_check_url<\/h3>\n\n\n\n
Cosa \u00e8 cambiato rispetto ai quickstart precedenti?<\/h4>\n\n\n\n
Guida pratica all\u2019upgrade: come cambia l\u2019implementazione da prima a oggi<\/h2>\n\n\n\n
Mantieni segnaposto e gestione asincrona<\/h3>\n\n\n\n
\n
file<\/code>, input_options<\/code> e output_settings<\/code> come multipart form data.<\/li>\n\n\n\n<<page_number>><\/code> e <<total_pages>><\/code> nel campo text<\/code>.<\/li>\n\n\n\nUsa i default in modo intenzionale<\/h3>\n\n\n\n
\n
Introduci sections per layout professionali<\/h3>\n\n\n\n
sections<\/code> (e opzionalmente range<\/code>) risolvi problemi tipici:<\/p>\n\n\n\n\n
Usa offsets quando serve precisione<\/h3>\n\n\n\n
Aggiungi la data solo quando aggiunge valore<\/h3>\n\n\n\n
date_config<\/code> lo supporta, ma ricordati che locale e timezone diventano obbligatori.<\/p>\n\n\n\nBest practice per uso in produzione<\/h2>\n\n\n\n
Valida i limiti del file prima dell\u2019upload<\/h3>\n\n\n\n
Standardizza un pi\u00e8 di pagina \u201caziendale\u201d e riusalo ovunque<\/h3>\n\n\n\n
\n
Pagina <<page_number>> di <<total_pages>><\/code><\/li>\n\n\n\nRendi il polling resiliente<\/h3>\n\n\n\n
\n
Evita di formattare troppo se non serve<\/h3>\n\n\n\n
Conclusione: l\u2019API \u201cdi oggi\u201d punta alla coerenza, non solo ai numeri<\/h2>\n\n\n\n