NextPDF Connect で PDF フォームに入力する（Pro）

概要

NextPDF Connect では、XFDF（XML Forms Data Format）を使用して、インタラクティブな PDF フォームフィールドに入力できます。署名およびフォーム用のツールは fill_form です。Pro のツールプロバイダーは new FillFormTool() を登録し、そのプロトコル名は fill_form です。fill_form は Pro ティアのツールです。 サーバーは起動時に class_exists() で Pro パッケージを検査し、パッケージが存在する場合にのみツールを登録します。Core 単体では、fill_form はレジストリに存在しません。

インストール

composer require nextpdf/server
composer require nextpdf/pro

トランスポートをバインドします。diagnostic.capabilities でツールの存在を確認します（environment-diagnostics を参照）。固定のツールセットを前提にしないでください。

概念的な概要

XFDF は、<field> 要素でフィールド名と値を対応付けます。各名前は、対象ドキュメントにあらかじめ定義されている AcroForm フィールドと一致している必要があります。インタラクティブフォームのフィールド辞書が各フィールドを保持し（ISO 32000-2 §12.7）、指定した値がそのフィールドの値になります（ISO 32000-2 §12.7）。どのフィールドにも一致しない名前は、エラーとして扱われずスキップされます。このツールは、入力したフィールド数とスキップしたフィールド数を報告します。

API サーフェス

ツール	ティア	役割	リスクティア
`create_pdf`	Core	セッションを開く	Safe
`fill_form`	Pro	XFDF の値を AcroForm フィールドに適用	Caution
`output_pdf`	Core	PDF をレンダリングして返す	承認が必要/レビュー（base64）

ツール名はレジストリ上のプロトコル名です。ツールカタログが正式なカタログです。利用可能なツールの集合は、インストールされているティアに依存します。Pro のツールは、Pro パッケージがインストールされている場合にのみ表示されます。

コードサンプル — クイックスタート

create_pdf（または、すでにフォームフィールドを持つテンプレートの読み込み）。
フィールド名を値に対応付ける xfdf_data を指定して fill_form を実行する。
output_pdf → base64。

結果は、fields_filled、fields_skipped、および一致したフィールドの名前を報告します。

コードサンプル — 本番

AcroForm のフィールド名を自分で管理できるテンプレートを使用してください。送信前に、XFDF を XFDF スキーマに照らして検証してください。名前の不一致を検出するため、fields_skipped と返された名前リストを確認してください（名前は大文字と小文字を区別します）。入力が大量になる場合は、XFDF のサイズ上限を超えないようにし、必要に応じてデータを分割してください。

エッジケースと注意点

不正な XFDF。 パースエラーは問題のある箇所を示します。XML エンティティをエスケープし、xmlns を含めてください。
名前の不一致。 一致しないフィールドは黙ってスキップされ、fields_skipped が増加します。名前は大文字と小文字を区別します。
フォームフィールドなし。 AcroForm を持たないドキュメントでは、入力されるフィールドはゼロになります。
XFDF が大きすぎる。 サーバーはサイズ上限を超えるデータを拒否します。分割するか、空白を削ってください。
Pro なし。 Core のみの場合、fill_form は登録されておらず、呼び出すと未知ツールのエラーが返ります。まず diagnostic.capabilities で検査してください。

パフォーマンス

レンダリングに比べて、入力処理は高速です。出力はフィールド数とフォント埋め込みに応じて、数 KB から数十 KB の範囲になります。プロファイルは structural です。

セキュリティに関する注意

フィールドの値はドキュメントのコンテンツです。PDF を信頼できないチャネル経由で返す場合は、フォームフィールドに秘密情報を入れないでください。base64 のパスにはファイルシステムへの副作用がありません。ファイル出力はゲートされています。

適合性

ステートメント	仕様	箇条	reference_id
フォームフィールドは、インタラクティブフォームのフィールド辞書に保持	ISO 32000-2	§12.7
指定したデータがフィールドの値	ISO 32000-2	§12.7

商用コンテキスト

fill_form は Pro ティアのツールです。サーバーは、起動時に Pro パッケージが解決される場合にのみ、このツールを登録します（class_exists() による検査）。Core のデプロイでは公開されません。

トランスポートの可用性

トランスポート	利用可否	備考
MCP（stdio）	はい（Pro）	Pro がインストールされている場合にのみ存在。
REST	はい（Pro）	同上
gRPC	はい（Pro）	同上

HITL リスクティア

fill_form は、可逆的なコンテンツ変更であるため Caution です。output_pdf は承認が必要で、base64 モードではレビューに引き下げられます（HITL リスクティア）。

確認ゲートの JSON エンベロープ

base64 出力:

{ "allowed": true }

ファイル出力では、output-approval で説明されているチャレンジエンベロープが返されます。