Creare un documento multipagina con NextPDF Connect

In sintesi

Creare un documento multipagina con NextPDF Connect. add_page aggiunge una pagina che eredita la geometria predefinita del documento oppure ne sovrascrive l’orientamento. Dopo ogni add_page, il cursore viene riposizionato sul margine in alto a sinistra della nuova pagina. Per questo flusso si utilizzano quattro strumenti, tutti Core: create_pdf, add_text, add_page e output_pdf.

Installazione

composer require nextpdf/server

Associare quindi un trasporto: MCP stdio, REST o gRPC. Non è necessario alcun livello con licenza.

Panoramica concettuale

In un documento, le pagine formano un albero. Ogni pagina è un nodo raggiungibile attraverso tale albero (ISO 32000-2 §7.7.3). Ogni pagina contiene i propri attributi di geometria, incluso il media box che definisce l’area visibile (ISO 32000-2 §7.7.3.3). create_pdf crea automaticamente la prima pagina e add_page aggiunge ogni pagina successiva. Omettere page_size/orientation per ereditare i valori predefiniti del documento. Impostare orientation: "landscape" per ruotare una pagina A4 a 297×210 mm.

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Apre la sessione e crea la prima pagina	Sicuro
`add_text`	Scrive testo alla posizione del cursore	Attenzione
`add_page`	Aggiunge una pagina (eredita o sovrascrive)	Attenzione
`output_pdf`	Esegue il rendering e restituisce il PDF	Approvazione richiesta / Revisione (base64)

I nomi degli strumenti corrispondono ai nomi di protocollo del registro. Il catalogo degli strumenti fa da riferimento. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Avvio rapido

Sequenza in breve:

create_pdf (A4 verticale, titolo, autore) → document_id.
add_text (titolo, carattere grande, centrato), quindi add_text (paragrafo introduttivo, carattere del corpo).
add_page con il solo document_id → eredita A4 verticale. Viene restituito il nuovo page_number e il cursore si riposiziona.
add_text per l’intestazione di sezione e il corpo nella pagina 2.
add_page con orientation: "landscape" → una pagina A4 in larghezza.
add_text per il contenuto della pagina in larghezza.
output_pdf → base64.

Esempio di codice — Produzione

Convalidare ogni risposta. Dopo add_page, aspettarsi che il contenuto inizi in cima alla nuova pagina. Il riposizionamento del cursore è un comportamento previsto, non un difetto. Tenere traccia di position.page nelle risposte di add_text per rilevare quando il contenuto passa a una pagina successiva. Chiamare output_pdf esattamente una volta, quindi scartare il document_id.

Casi limite e insidie

Riposizionamento del cursore. Dopo add_page, il cursore si trova sul margine in alto a sinistra della nuova pagina. Aspettarsi che continui dal punto della pagina precedente è l’errore più comune.
document_id obbligatorio. Ogni strumento tranne create_pdf richiede il document_id. Ometterlo è un errore.
Orientamento non valido. Solo "portrait" e "landscape" sono validi.
Modifiche dopo l’output. Il tentativo di aggiungere contenuto dopo output_pdf con destroy: true fallisce, perché la sessione non esiste più.

Prestazioni

Un documento di testo multipagina rientra nel budget di pagine e l’output è di pochi KB. Il profilo è structural: il /ID del trailer e le marche temporali non sono stabili tra le esecuzioni.

Note sulla sicurezza

La modalità base64 non ha effetti collaterali. L’output su file è soggetto al gate (sezione HITL). Il document_id è un handle opaco. Non condividerlo tra richieste concorrenti.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Le pagine sono raggiunte attraverso l’albero delle pagine.	ISO 32000-2	§7.7.3
Un oggetto pagina definisce i propri attributi di geometria.	ISO 32000-2	§7.7.3.3

Contesto commerciale

Non applicabile — tutti gli strumenti sono Core.

Disponibilità del trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì	`tools/call` per strumento.
REST	Sì	Un’operazione per strumento.
gRPC	Sì	Una chiamata unaria per strumento.

Livello di rischio HITL

create_pdf è Sicuro; add_text e add_page sono Attenzione; output_pdf è Approvazione richiesta, declassato a Revisione in modalità base64. L’output su file resta in Approvazione richiesta. Consultare output-approval e livelli di rischio HITL.

Envelope JSON del gate di conferma

Output base64 in questo caso:

{ "allowed": true }

Il modulo di challenge è illustrato in output-approval.