Mengisi formulir PDF melalui NextPDF Connect (Pro)

Sekilas pandang

Isi bidang formulir PDF interaktif melalui NextPDF Connect menggunakan XML Forms Data Format (XFDF). Alat untuk penandatanganan dan formulir adalah fill_form. Penyedia alat Pro mendaftarkan new FillFormTool(); nama protokolnya adalah fill_form. fill_form adalah alat tingkat Pro. Saat boot, server memeriksa keberadaan paket Pro dengan class_exists() dan hanya mendaftarkan alat tersebut ketika paket itu tersedia. Jika hanya menggunakan Core, fill_form tidak ada dalam registri.

Pemasangan

composer require nextpdf/server
composer require nextpdf/pro

Ikat satu transport. Lalu pastikan alat tersebut tersedia melalui diagnostic.capabilities (lihat environment-diagnostics). Jangan mengasumsikan kumpulan alatnya selalu tetap.

Tinjauan konseptual

XFDF memetakan nama bidang ke nilainya menggunakan elemen <field>. Setiap nama harus cocok dengan bidang AcroForm yang sudah ada di dokumen target. Kamus bidang formulir interaktif menyimpan tiap bidang (ISO 32000-2 §12.7), dan nilai yang diberikan menjadi nilai bidang tersebut (ISO 32000-2 §12.7). Jika suatu nama tidak cocok dengan bidang mana pun, alat ini melewatinya alih-alih memperlakukannya sebagai kesalahan. Alat ini melaporkan berapa banyak bidang yang diisi dan berapa banyak yang dilewati.

Permukaan API

Alat	Tingkat	Peran	Tingkat risiko
`create_pdf`	Core	Membuka sesi	Aman
`fill_form`	Pro	Menerapkan nilai XFDF ke bidang AcroForm	Hati-hati
`output_pdf`	Core	Merender dan mengembalikan PDF	Persetujuan Diperlukan / Tinjauan (base64)

Nama alat adalah nama protokol di registri. Katalog alat adalah katalog resmi. Tingkat yang terpasang menentukan alat mana yang tersedia. Alat Pro hanya muncul ketika paket Pro terpasang.

Contoh kode — Mulai cepat

create_pdf (atau muat templat yang sudah memiliki bidang formulir).
fill_form dengan xfdf_data yang memetakan nama bidang ke nilainya.
output_pdf → base64.

Hasilnya melaporkan fields_filled, fields_skipped, dan nama-nama bidang yang cocok.

Contoh kode — Produksi

Gunakan templat dengan nama bidang AcroForm yang Anda kendalikan. Validasikan XFDF terhadap skema XFDF sebelum Anda mengirimkannya. Periksa fields_skipped dan daftar nama yang dikembalikan untuk menangkap ketidakcocokan nama (nama bersifat peka huruf besar-kecil). Untuk pengisian data berukuran besar, pastikan tetap di bawah batas ukuran XFDF, dan pecah datanya jika diperlukan.

Kasus tepi & jebakan

XFDF salah format. Kesalahan penguraian menunjukkan lokasi yang bermasalah. Lakukan escape pada entitas XML dan sertakan xmlns.
Ketidakcocokan nama. Bidang yang tidak cocok dilewati tanpa pemberitahuan, dan fields_skipped bertambah. Nama bersifat peka huruf besar-kecil.
Tidak ada bidang formulir. Dokumen tanpa AcroForm menghasilkan nol bidang yang terisi.
XFDF terlalu besar. Server menolak data yang melampaui batas ukuran. Pecah data atau pangkas spasi kosongnya.
Pro tidak tersedia. Jika hanya menggunakan Core, fill_form tidak terdaftar, dan memanggilnya mengembalikan kesalahan alat-tidak-dikenal. Periksa dengan diagnostic.capabilities terlebih dahulu.

Performa

Pengisian berlangsung cepat dibandingkan rendering. Ukuran keluaran berkisar dari beberapa KB hingga puluhan KB, bergantung pada jumlah bidang dan penyematan fon. Profilnya adalah structural.

Catatan keamanan

Nilai bidang menjadi konten dokumen. Jangan masukkan rahasia ke bidang formulir jika PDF tersebut kemudian dikembalikan melalui kanal yang tidak tepercaya. Jalur base64 tidak memiliki efek samping pada sistem berkas. Keluaran berkas dibatasi oleh gerbang.

Kesesuaian

Pernyataan	Spesifikasi	Klausul	reference_id
Sebuah bidang formulir disimpan dalam kamus bidang formulir interaktif.	ISO 32000-2	§12.7
Data yang diberikan menjadi nilai bidang tersebut.	ISO 32000-2	§12.7

Konteks komersial

fill_form adalah alat tingkat Pro. Server hanya mendaftarkannya ketika paket Pro berhasil di-resolve saat boot (pemeriksaan class_exists()). Implementasi Core tidak mengeksposnya.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya (Pro)	Hanya tersedia ketika Pro terpasang.
REST	Ya (Pro)	Sama.
gRPC	Ya (Pro)	Sama.

Tingkat risiko HITL

fill_form termasuk kategori Hati-hati karena melakukan mutasi konten yang dapat dibatalkan. output_pdf termasuk kategori Persetujuan Diperlukan, dan diturunkan menjadi Tinjauan dalam mode base64 (tingkat risiko HITL).

Amplop JSON untuk gerbang konfirmasi

Keluaran base64:

{ "allowed": true }

Keluaran berkas mengembalikan amplop tantangan yang dijelaskan dalam output-approval.