Perché l’API addimages è importante oggi
Aggiungere un logo, un timbro “PAGATO”, un’immagine di firma, un badge di watermark o un marchio di conformità a un PDF, fino a poco tempo fa, era un lavoro ripetitivo e manuale: aprire un editor PDF, inserire un’immagine, ridimensionarla, esportare e ripetere l’operazione per ogni documento. L’API di Zoho PDF Editor cambia completamente questo flusso, perché permette alla tua applicazione di inserire immagini in un PDF esistente in modo programmatico—così il tuo sistema può applicare branding alle fatture, timbrare le ricevute o inserire firme automaticamente, senza intervento umano.
Questa automazione è particolarmente utile quando i PDF vengono generati in grandi volumi (fatturazione, onboarding, pacchetti di spedizione, documenti legali, report). Invece di far passare i PDF in una coda manuale, puoi trattare le sovrapposizioni di immagini come un passaggio di post-produzione prevedibile: genera il PDF → chiama addimages → consegna il PDF aggiornato.
Questo articolo aggiornato spiega come funziona oggi l’endpoint addimages, quali dettagli risultano più chiari nella documentazione attuale e come implementarlo in modo affidabile in pipeline reali.
Cosa è cambiato da “prima” a “oggi”
I limiti sulle immagini sono ora più chiari e più facili da implementare correttamente
In alcune bozze o sintesi informali, l’endpoint veniva descritto come capace di inserire “dieci o più” immagini. Oggi la documentazione è esplicita: puoi inserire fino a 10 immagini per richiesta, con un massimo di 10 MB per immagine, utilizzando PNG o JPEG.
Questo aspetto è importante perché i limiti influenzano l’architettura. Se devi posizionare più di 10 immagini (ad esempio un pacchetto multipagina con più timbri per pagina), dovrai dividere il lavoro in più chiamate API oppure ripensare le regole di posizionamento in modo da usare meno immagini uniche.
La selezione del dominio è considerata un vero requisito di deployment, non un dettaglio secondario
In passato molte implementazioni fallivano perché gli sviluppatori fissavano un solo dominio base e scoprivano poi che l’account Zoho era su un diverso data center. Le indicazioni attuali sottolineano che il dominio base dell’API deve corrispondere al data center dell’account (US, EU, IN e altri). In pratica, “funziona sul mio computer” diventa “funziona ovunque” solo quando il dominio è configurabile.
Le regole di posizionamento (input_options) sono oggi più comprese come un modello strutturato
La principale fonte di errori spesso non è l’autenticazione: è la formattazione di input_options. Oggi è più chiaro che le istruzioni di posizionamento sono un payload strutturato che descrive:
- Dove va l’immagine (coordinate e dimensioni del rettangolo)
- Su quali pagine va applicata (intervalli di pagine)
- Se la parità della pagina conta (filtro pagine dispari/pari)
Questo rende l’endpoint più flessibile di quanto molti utenti alle prime armi pensino. Non sei limitato a “un’immagine, una pagina”. Puoi definire regole ripetibili da applicare su più pagine senza duplicare manualmente le istruzioni.
I flussi di archiviazione sono più centrali nell’uso moderno
Molti team oggi non vogliono più “scarica e poi salva altrove” come passaggio separato. La variante di archiviazione su WorkDrive (il percorso /store) supporta flussi in cui l’API salva il risultato in un repository gestito. È un cambiamento significativo nelle best practice attuali: meno passaggi, maggiore chiarezza di responsabilità e migliore tracciabilità—soprattutto per chi utilizza già WorkDrive.
Cosa fa l’endpoint “Insert Images”
L’endpoint Insert Images in PDF serve per sovrapporre immagini a un PDF esistente. La tua richiesta include:
CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?
- Un PDF in input (file caricato oppure URL pubblicamente accessibile)
- Una o più immagini (file caricati oppure URL pubblicamente accessibili)
- Impostazioni di output (ad esempio il nome del file modificato)
- Impostazioni di posizionamento (
input_options) che definiscono dove appaiono le immagini e su quali pagine applicarle
Vincoli principali da considerare:
- Dimensione PDF in input: fino a 50 MB
- Immagini per richiesta: fino a 10
- Formati immagine: PNG e JPEG
- Dimensione immagine: fino a 10 MB per immagine
Requisiti prima di chiamare l’API
Scegliere il dominio del data center corretto
Le API Zoho sono specifiche per data center. La richiesta addimages deve puntare al dominio base corretto per l’account Zoho. Trattalo come configurazione, non come costante.
Consiglio pratico: salva il dominio base come variabile d’ambiente (o impostazione per tenant se supporti più account). Così potrai cambiare dominio senza modificare il codice.
Creare un token OAuth con lo scope corretto
Il token OAuth deve includere lo scope:
ZohoWriter.pdfEditor.ALL
Se utilizzi l’endpoint di archiviazione su WorkDrive, serviranno anche gli scope WorkDrive pertinenti e l’account deve avere WorkDrive disponibile.
Endpoint da chiamare
Inserire immagini e scaricare in un secondo momento
Usa una richiesta POST al percorso addimages:
/pdfeditor/api/v1/pdf/addimages
Precedilo con il dominio base corretto per il tuo data center.
Inserire immagini e archiviare in WorkDrive
Usa una richiesta POST al percorso addimages/store:
/pdfeditor/api/v1/pdf/addimages/store
Questo percorso è pensato per salvare il PDF finale in WorkDrive (invece di restituire solo un flusso di download).
Come funziona il body della richiesta (multipart/form-data)
L’API si aspetta multipart/form-data, tipicamente con quattro parti principali: file, image_files, output_settings e input_options.
Input PDF: file
Puoi fornire il PDF in due modi:
- Caricare il file PDF come parte binaria del form
- Fornire un URL del PDF pubblicamente accessibile come stringa
L’approccio “URL” è utile quando il PDF è già ospitato in una posizione accessibile ai server di Zoho e vuoi evitare download e re-upload nella tua infrastruttura. L’approccio “upload file” è più sicuro quando i PDF sono privati, generati al volo o protetti da autenticazione.
Input immagini: image_files
Puoi fornire le immagini in due modi:
- Caricare uno o più file immagine come parti binarie
- Fornire URL delle immagini pubblicamente accessibili come stringa separata da virgole
Questa flessibilità semplifica sia i flussi “file locali” sia i flussi “asset in cloud”. Ad esempio, potresti conservare loghi e timbri in uno storage a oggetti e passarli via URL, mentre carichi i PDF generati dinamicamente dalla tua applicazione.
Nome output: output_settings
Questo parametro è una stringa JSON che definisce il nome del file PDF modificato:
{ "name": "ModifiedFile.pdf" }
Quando usi la variante WorkDrive, le impostazioni di output possono anche controllare il comportamento di archiviazione, come la cartella di destinazione e l’eventuale sovrascrittura di un file esistente (a seconda della configurazione WorkDrive scelta).
Regole di posizionamento: input_options
È il parametro più importante perché controlla dove vanno le immagini.
Il payload ti permette di definire:
image_rect: il rettangolo per posizionamento e dimensioni (top, left, width, height)page_ranges(opzionale): quali pagine ricevono l’immagineodd_or_even_pages(opzionale): applicazione solo su pagine pari o dispari
Comprendere image_rect
Definisci il rettangolo di posizionamento tramite proprietà come:
topleftwidthheight
Gli esempi Zoho spesso usano stringhe in stile pixelSi tratta di un frammento di codice che viene inserito sul vostro sito web a scopo di tracciamento. ... Leggi come "25px". Il concetto principale è che il posizionamento diventa deterministico dopo aver calibrato le coordinate per il tuo template PDF.
Se i tuoi PDF non sono coerenti (dimensioni pagina diverse, margini variabili, template diversi), potresti dover suddividere il flusso per tipo di template e applicare rettangoli differenti per ciascuno.
Usare page_ranges
La selezione delle pagine può essere espressa con vari schemi:
"1,2,5"per pagine specifiche"2-4,7-9"per più intervalli"-5"per “dalla prima pagina fino alla pagina 5”"7-"per “dalla pagina 7 fino all’ultima pagina”
Se page_ranges viene omesso o è vuoto, il posizionamento viene applicato a tutte le pagine.
Usare odd_or_even_pages
Puoi limitare l’applicazione alle pagine dispari o alle pagine pari. È particolarmente utile quando:
- I PDF vengono stampati fronte/retro e i margini cambiano a seconda del lato
- Vuoi timbri solo sulle pagine “viste dal cliente”
- Il layout del documento alterna posizioni tra le pagine
Se odd_or_even_pages viene omesso o è vuoto, il posizionamento viene applicato a tutte le pagine.
Un esempio pulito in curl (con struttura corretta)
Di seguito un esempio curl corretto e leggibile che rispetta le parti multipart richieste. Sostituisci il token e i percorsi file con i tuoi.
curl --location --request POST "<DOMINIO_BASE>/pdfeditor/api/v1/pdf/addimages" \
--header "Authorization: Zoho-oauthtoken <ACCESS_TOKEN>" \
--form 'file=@"/path/to/Sample.pdf"' \
--form 'image_files=@"/path/to/img.png"' \
--form 'output_settings={"name":"ModifiedFile.pdf"}' \
--form 'input_options={"image_rect":{"top":"25px","left":"25px","width":"200px","height":"200px"}}'
Un errore comune negli esempi più vecchi è una gestione errata delle virgolette attorno alle stringhe JSON o la confusione su dove vanno output_settings e input_options. Mantieni ogni valore JSON come singola stringa JSON valida nella sua parte del form.
Comprendere il flusso di risposta asincrono
Il modello di risposta basato su job
L’endpoint addimages restituisce un job asincrono invece di restituire subito il PDF finale. Ciò significa che la tua applicazione dovrebbe:
- Inviare la richiesta
- Ricevere una risposta contenente un URL di controllo stato e uno stato “in corso”
- Fare polling dell’URL di stato finché il job non termina
- Recuperare il PDF finale usando l’URL di download fornito quando lo stato diventa “success”
Questo approccio è comune per le API di elaborazione PDF perché i tempi dipendono da dimensione file, numero di pagine e numero di operazioni sulle immagini.
Progettare una strategia di polling robusta
Per evitare rate limit e ridurre traffico inutile:
- Usa un backoff crescente tra i tentativi (ad esempio 1s → 2s → 4s → 8s)
- Interrompi il polling dopo un timeout ragionevole e mostra un errore chiaro
- Registra job ID e URL di stato per diagnosi
Se la tua architettura supporta worker in background, è un caso d’uso perfetto per una coda: invia → metti in coda il task di polling → completa → salva output.
Casi d’uso reali che traggono vantaggio da addimages
Branding dei documenti in uscita
Molti team usano addimages per applicare un logo coerente a PDF generati da sistemi diversi. È utile quando il generatore a monte non inserisce bene gli asset di brand o quando devi aggiungere il branding a posteriori.
Aggiungere firme e timbri
Se acquisisci firme come immagini (ad esempio una firma su tablet), addimages può inserirla nel punto corretto della pagina di firma. Anche timbri come “APPROVATO”, “PAGATO”, “RISERVATO” o “BOZZA” sono molto comuni.
Sovrapposizioni di conformità e marcature di audit
Le organizzazioni in settori regolamentati spesso aggiungono badge di conformità o marcature di controllo documentale. Con regole di posizionamento e selezione pagine, puoi applicarle in modo uniforme su moduli standard.
Pipeline PDF basate su template
Se hai un insieme di template noti (fattura A, fattura B, contratto C), puoi salvare rettangoli di posizionamento per ciascun template e applicarli in modo deterministico. È qui che addimages diventa davvero “imposta e dimentica”.
Risoluzione problemi: controlli rapidi che risolvono la maggior parte degli errori
Vincoli su dimensione e formato
Verifica subito:
- Il PDF non supera 50 MB
- Non stai inserendo più di 10 immagini
- Ogni immagine è ≤ 10 MB
- Le immagini sono PNG o JPEG
Quando il sistema cresce, questi vincoli dovrebbero essere validati prima della chiamata API così gli errori diventano prevedibili e i messaggi agli utenti risultano chiari.
Problemi di token (401 Unauthorized)
Se ricevi un errore di autorizzazione, controlla:
- Il token non è scaduto
- Il token include
ZohoWriter.pdfEditor.ALL - Stai chiamando il dominio del data center corretto per l’account
Per l’endpoint /store, verifica anche scope WorkDrive e disponibilità WorkDrive.
Errore di richiesta (400 Bad Request)
Molti errori di formattazione dipendono dalle stringhe JSON:
output_settingsdeve essere JSON validoinput_optionsdeve essere JSON valido- Le virgolette interne al JSON devono essere correttamente gestite dal tuo client HTTP
- Il boundary multipart deve essere corretto (di solito lo gestiscono le librerie)
Se usi un linguaggio server-side, preferisci una libreria multipart affidabile e costruisci il JSON tramite oggetti nativi → serializzazione JSON, evitando concatenazioni manuali.
Best practice per l’affidabilità in produzione
Validare gli input prima di chiamare l’API
Crea un livello di validazione che controlli dimensione file, numero immagini e formato. Così risparmi tempo e riduci chiamate destinate a fallire.
Trattare il posizionamento come una fase di calibrazione del template
Anche con rettangoli corretti, la qualità del posizionamento dipende da dimensioni pagina e coerenza del layout. Fai una calibrazione:
- Scegli un PDF rappresentativo per ogni template
- Testa il posizionamento con i rettangoli scelti
- Regola finché la sovrapposizione è stabile
- Salva i rettangoli in configurazione (non hard-coded nel codice)
Rendere configurabile il dominio base
Se supporti più account Zoho (o potresti migrare tra data center), mantieni il dominio base in configurazione. Evita deployment fragili e rende l’integrazione portabile.
Scegliere presto tra download e archiviazione
Se devi consegnare subito il PDF all’utente finale, il flusso job + download è semplice. Se ti serve conservazione e accesso centralizzato, il flusso WorkDrive può semplificare i passaggi a valle. L’importante è scegliere l’approccio che rispecchia il processo operativo, non solo quello più rapido da testare.
Conclusione
L’API addimages di Zoho PDF Editor è un modo pratico per automatizzare uno dei compiti più comuni nell’ultimo miglio dei PDF: posizionare immagini su un PDF esistente con regole di pagina e posizionamento coerenti. La documentazione moderna rende più chiari i limiti e la struttura—soprattutto sul massimo di 10 immagini per richiesta, sui formati supportati, sui vincoli di dimensione, sugli endpoint per data center e sul modello strutturato di input_options per selezione pagine e posizionamento.
Se vuoi, incolla il tuo JSON input_options (con l’obiettivo di posizionamento—logo, firma, timbro, ecc.) e lo riscrivo in un payload pulito e validato, pronto da usare nel tuo codice senza errori di virgolette.
© Crediti d’immagine a Steve Johnson
CERCHI UNA SOLUZIONE UNICA PER LA TUA CRESCITA DIGITALE?
