PDF-Formular mit NextPDF Connect ausfüllen (Pro)

Auf einen Blick

Füllen Sie interaktive PDF-Formularfelder mit XFDF (XML Forms Data Format) über NextPDF Connect aus. Das Signatur- und Formular-Tool heißt fill_form. Der Pro-Tool-Provider registriert new FillFormTool() unter dem Protokollnamen fill_form. fill_form ist ein Pro-Tool. Beim Start prüft der Server mit class_exists(), ob das Pro-Paket vorhanden ist, und registriert das Tool nur dann. Bei einer reinen Core-Installation fehlt fill_form in der Registry.

Installation

composer require nextpdf/server
composer require nextpdf/pro

Binden Sie einen Transport an. Prüfen Sie mit diagnostic.capabilities, ob das Tool vorhanden ist (siehe environment-diagnostics). Gehen Sie nicht von einem festen Toolset aus.

Konzeptioneller Überblick

XFDF weist Feldnamen über <field>-Elemente Werte zu. Jeder Name muss einem AcroForm-Feld entsprechen, das im Zieldokument bereits definiert ist. Im Felddictionary des interaktiven Formulars ist jedes Feld enthalten (ISO 32000-2 §12.7), und der übergebene Wert wird zum Wert des Felds (ISO 32000-2 §12.7). Ein Name, der keinem Feld entspricht, wird übersprungen, statt als Fehler behandelt zu werden. Das Tool meldet, wie viele Felder ausgefüllt und wie viele übersprungen wurden.

API-Oberfläche

Tool	Stufe	Rolle	Risikostufe
`create_pdf`	Core	Die Sitzung öffnen	Sicher
`fill_form`	Pro	XFDF-Werte auf AcroForm-Felder anwenden	Vorsicht
`output_pdf`	Core	Das PDF rendern und zurückgeben	Genehmigung erforderlich / Prüfung (base64)

Tool-Namen sind die Protokollnamen in der Registry. Der Tool-Katalog ist maßgeblich. Welche Tools verfügbar sind, hängt von der installierten Stufe ab. Pro-Tools erscheinen nur, wenn das Pro-Paket installiert ist.

Codebeispiel — Schnellstart

create_pdf (oder laden Sie eine Vorlage, die bereits Formularfelder enthält).
fill_form mit xfdf_data, das Feldnamen Werte zuordnet.
output_pdf → base64.

Das Ergebnis meldet fields_filled, fields_skipped sowie die Namen der übereinstimmenden Felder.

Codebeispiel — Produktion

Verwenden Sie eine Vorlage, deren AcroForm-Feldnamen unter Ihrer Kontrolle stehen. Validieren Sie das XFDF anhand des XFDF-Schemas, bevor Sie es senden. Prüfen Sie fields_skipped und die zurückgegebene Liste der Namen, um Abweichungen bei den Namen zu erkennen (bei Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden). Bleiben Sie bei großen Befüllungen unter dem XFDF-Größenlimit und teilen Sie die Daten bei Bedarf auf.

Grenzfälle & Fallstricke

Fehlerhaftes XFDF. Ein Parsing-Fehler nennt die fehlerhafte Stelle. Maskieren Sie XML-Entities und geben Sie das Attribut xmlns an.
Namensabweichung. Ein nicht übereinstimmender Feldname wird stillschweigend übersprungen, und fields_skipped wird erhöht. Bei Feldnamen wird zwischen Groß- und Kleinschreibung unterschieden.
Keine Formularfelder. Ein Dokument ohne AcroForm führt zu null ausgefüllten Feldern.
XFDF zu groß. Der Server weist Daten ab, die das Größenlimit überschreiten. Teilen Sie sie auf oder entfernen Sie den Leerraum.
Pro nicht vorhanden. Bei einer reinen Core-Installation ist fill_form nicht registriert, und ein Aufruf gibt einen Unknown-Tool-Fehler zurück. Prüfen Sie zuerst mit diagnostic.capabilities.

Performance

Das Ausfüllen ist im Vergleich zum Rendering schnell. Die Ausgabe reicht von wenigen KB bis zu einigen zehn KB, abhängig von der Feldanzahl und der Schrifteinbettung. Das Profil ist structural.

Sicherheitshinweise

Feldwerte sind Dokumentinhalt. Legen Sie keine Geheimnisse in Formularfeldern ab, wenn Sie das PDF anschließend über einen nicht vertrauenswürdigen Kanal zurückgeben. Der base64-Pfad hat keine Nebenwirkungen auf das Dateisystem. Die Dateiausgabe ist abgesichert.

Konformität

Aussage	Spezifikation	Klausel	reference_id
Ein Formularfeld wird im Felddictionary des interaktiven Formulars geführt.	ISO 32000-2	§12.7
Die übergebenen Daten werden zum Wert des Felds.	ISO 32000-2	§12.7

Kommerzieller Kontext

fill_form ist ein Pro-Tool. Der Server registriert es nur, wenn das Pro-Paket beim Start aufgelöst wird (die class_exists()-Prüfung). Reine Core-Bereitstellungen stellen es nicht bereit.

Transportverfügbarkeit

Transport	Verfügbar	Hinweise
MCP (stdio)	Ja (Pro)	Nur verfügbar, wenn Pro installiert ist.
REST	Ja (Pro)	Dasselbe.
gRPC	Ja (Pro)	Dasselbe.

HITL-Risikostufe

fill_form ist der Stufe Vorsicht zugeordnet, weil es eine umkehrbare Inhaltsänderung vornimmt. output_pdf ist der Stufe Genehmigung erforderlich zugeordnet und im base64-Modus auf Prüfung herabgestuft (HITL-Risikostufen).

JSON-Envelope des Bestätigungs-Gates

Base64-Ausgabe:

{ "allowed": true }

Die Dateiausgabe gibt den Challenge-Envelope zurück, der in output-approval beschrieben ist.