Compilare un modulo PDF con NextPDF Connect (Pro)

In sintesi

Compilare i campi interattivi di un modulo PDF con XFDF (XML Forms Data Format) tramite NextPDF Connect. Lo strumento per firme e moduli è fill_form. Il provider di strumenti Pro registra new FillFormTool(), il cui nome di protocollo è fill_form. fill_form è uno strumento del livello Pro. All’avvio, il server verifica la presenza del pacchetto Pro con class_exists() e registra lo strumento solo quando il pacchetto è presente. Con il solo Core, fill_form non è presente nel registro.

Installazione

composer require nextpdf/server
composer require nextpdf/pro

Associare un trasporto. Confermare la disponibilità dello strumento con diagnostic.capabilities (vedere environment-diagnostics). Non dare per scontato che l’insieme degli strumenti sia fisso.

Panoramica concettuale

XFDF associa i nomi dei campi ai valori tramite elementi <field>. Ogni nome deve corrispondere a un campo AcroForm già definito nel documento di destinazione. Il dizionario dei campi del modulo interattivo contiene ogni campo (ISO 32000-2 §12.7) e il valore fornito diventa il valore del campo (ISO 32000-2 §12.7). Un nome che non corrisponde ad alcun campo viene ignorato, anziché essere trattato come errore. Lo strumento indica quanti campi sono stati compilati e quanti ignorati.

Superficie API

Strumento	Livello	Ruolo	Livello di rischio
`create_pdf`	Core	Aprire la sessione	Sicuro
`fill_form`	Pro	Applicare i valori XFDF ai campi AcroForm	Attenzione
`output_pdf`	Core	Eseguire il rendering e restituire il PDF	Approvazione richiesta / Revisione (base64)

I nomi degli strumenti corrispondono ai nomi di protocollo del registro. Il catalogo degli strumenti è il catalogo di riferimento. L’insieme degli strumenti disponibili dipende dal livello installato. Gli strumenti Pro compaiono solo quando il pacchetto Pro è installato.

Esempio di codice — Avvio rapido

create_pdf (oppure caricare un modello che dispone già di campi modulo).
fill_form con xfdf_data che associa i nomi dei campi ai valori.
output_pdf → base64.

Il risultato riporta fields_filled, fields_skipped e i nomi dei campi corrispondenti.

Esempio di codice — Produzione

Usare un modello in cui i nomi dei campi AcroForm siano sotto controllo. Convalidare l’XFDF rispetto allo schema XFDF prima di inviarlo. Controllare fields_skipped e l’elenco dei nomi restituito per individuare eventuali mancate corrispondenze nei nomi (i nomi distinguono maiuscole e minuscole). Per compilazioni di grandi dimensioni, rimanere entro il limite di dimensione XFDF e suddividere i dati se necessario.

Casi limite e insidie

XFDF malformato. Un errore di analisi indica la posizione del problema. Eseguire l’escape delle entità XML e includere xmlns.
Mancata corrispondenza dei nomi. Un campo senza corrispondenza viene ignorato silenziosamente e fields_skipped viene incrementato. I nomi distinguono maiuscole e minuscole.
Nessun campo modulo. Un documento privo di AcroForm non produce alcun campo compilato.
XFDF troppo grande. Il server rifiuta i dati che superano il limite di dimensione. Suddividerli o ridurre gli spazi vuoti.
Pro assente. Con il solo Core, fill_form non è registrato e la sua chiamata restituisce un errore di strumento sconosciuto. Verificare prima con diagnostic.capabilities.

Prestazioni

La compilazione è rapida rispetto al rendering. L’output varia da pochi KB a decine di KB, in base al numero di campi e all’incorporamento dei font. Il profilo è structural.

Note sulla sicurezza

I valori dei campi fanno parte del contenuto del documento. Non inserire segreti nei campi del modulo se il PDF viene poi restituito su un canale non attendibile. Il percorso base64 non produce effetti collaterali sul file system. L’output su file è soggetto a controllo.

Conformità

Affermazione	Specifica	Clausola	reference_id
Un campo del modulo è contenuto nel dizionario dei campi del modulo interattivo.	ISO 32000-2	§12.7
I dati forniti diventano il valore del campo.	ISO 32000-2	§12.7

Contesto commerciale

fill_form è uno strumento del livello Pro. Il server lo registra solo quando il pacchetto Pro risulta disponibile all’avvio (sonda class_exists()). Le implementazioni Core non lo espongono.

Disponibilità del trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì (Pro)	Presente solo quando Pro è installato.
REST	Sì (Pro)	Stesso comportamento.
gRPC	Sì (Pro)	Stesso comportamento.

Livello di rischio HITL

fill_form ha livello Attenzione, perché è una mutazione di contenuto reversibile. output_pdf è Approvazione richiesta, declassato a Revisione in modalità base64 (livelli di rischio HITL).

Envelope JSON del gate di conferma

Output base64:

{ "allowed": true }

L’output su file restituisce l’envelope di sfida descritto in output-approval.