NextPDF Connect (Pro) ile PDF formunu doldurma

Genel bakış

Etkileşimli PDF form alanlarını NextPDF Connect üzerinden XML Forms Data Format (XFDF) ile doldurun. İmzalama ve form işlemleri için kullanılan araç fill_form’dur. Pro araç sağlayıcısı new FillFormTool() nesnesini kaydeder; bu nesnenin protokol adı fill_form’dur. fill_form, Pro katmanında bir araçtır. Sunucu, açılışta Pro paketini class_exists() ile denetler ve aracı yalnızca paket mevcut olduğunda kaydeder. Yalnızca Core kullanıldığında fill_form kayıt defterinde bulunmaz.

Kurulum

composer require nextpdf/server
composer require nextpdf/pro

Bir taşıma katmanı bağlayın. Ardından aracın var olduğunu diagnostic.capabilities ile doğrulayın (bkz. environment-diagnostics). Sabit bir araç kümesi varsaymayın.

Kavramsal genel bakış

XFDF, alan adlarını değerlere <field> öğeleriyle eşler. Her ad, hedef belgede zaten var olan bir AcroForm alanıyla eşleşmelidir. Etkileşimli form alan sözlüğü her alanı içerir (ISO 32000-2 §12.7) ve sağlanan değer alanın değeri olur (ISO 32000-2 §12.7). Bir ad hiçbir alanla eşleşmezse araç, bunu hata olarak ele almak yerine atlar. Araç, kaç alanı doldurduğunu ve kaçını atladığını bildirir.

API yüzeyi

Araç	Katman	Rol	Risk katmanı
`create_pdf`	Core	Oturumu açar	Güvenli
`fill_form`	Pro	XFDF değerlerini AcroForm alanlarına uygular	Dikkat
`output_pdf`	Core	PDF’yi işler ve döndürür	Onay gerekli / inceleme (base64)

Araç adları, kayıt defterinin protokol adlarıdır. Araç kataloğu resmi kayıt kataloğudur. Kullanılabilir araçları kurulu katman belirler. Pro araçları yalnızca Pro paketi kurulu olduğunda görünür.

Kod örneği — hızlı başlangıç

create_pdf (veya zaten form alanları olan bir şablon yükleyin).
fill_form, alan adlarını değerlere eşleyen xfdf_data ile.
output_pdf → base64.

Sonuç, fields_filled, fields_skipped ve eşleşen alan adlarını bildirir.

Kod örneği — üretim

Alan adları sizin denetiminizde olan AcroForm alanlarına sahip bir şablon kullanın. XFDF’yi göndermeden önce XFDF şemasına göre doğrulayın. Ad uyuşmazlıklarını yakalamak için fields_skipped değerini ve döndürülen ad listesini denetleyin (adlar büyük/küçük harfe duyarlıdır). Büyük doldurma işlemlerinde XFDF boyut sınırının altında kalın ve gerekirse veriyi bölün.

Uç durumlar ve tuzaklar

Hatalı biçimlendirilmiş XFDF. Bir ayrıştırma hatası, sorunlu konumu belirtir. XML varlıklarını kaçışlayın ve xmlns değerini ekleyin.
Ad uyuşmazlığı. Eşleşmeyen bir alan sessizce atlanır ve fields_skipped değeri bir artar. Adlar büyük/küçük harfe duyarlıdır.
Form alanı yok. AcroForm içermeyen bir belge, doldurulan alan sayısını sıfır olarak verir.
XFDF çok büyük. Sunucu, boyut sınırını aşan veriyi reddeder. Veriyi bölün veya boşlukları temizleyin.
Pro yok. Yalnızca Core kullanıldığında fill_form kaydedilmez ve onu çağırmak bilinmeyen araç hatası döndürür. Önce diagnostic.capabilities ile denetleyin.

Performans

Doldurma, işlemeye kıyasla hızlıdır. Çıktı, alan sayısına ve yazı tipi gömülmesine bağlı olarak birkaç KB ile onlarca KB arasında değişir. Profil structural’dır.

Güvenlik notları

Alan değerleri belge içeriği olur. PDF’yi daha sonra güvenilmeyen bir kanal üzerinden döndürecekseniz form alanlarına gizli bilgiler yerleştirmeyin. base64 yolu dosya sisteminde yan etki oluşturmaz. Dosya çıktısı onay kapısına tabidir.

Uygunluk

İfade	Spesifikasyon	Madde	reference_id
Bir form alanı, etkileşimli form alan sözlüğünde tutulur.	ISO 32000-2	§12.7
Sağlanan veri, alanın değeri olur.	ISO 32000-2	§12.7

Ticari bağlam

fill_form, Pro katmanında bir araçtır. Sunucu bu aracı yalnızca Pro paketi açılışta çözüldüğünde kaydeder (class_exists() yoklaması). Core dağıtımları onu açığa çıkarmaz.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet (Pro)	Yalnızca Pro kurulu olduğunda mevcuttur.
REST	Evet (Pro)	Aynı.
gRPC	Evet (Pro)	Aynı.

HITL risk katmanı

fill_form, geri alınabilir bir içerik değişikliği yaptığı için dikkat düzeyindedir. output_pdf, onay gerekli düzeyindedir ve base64 modunda inceleme düzeyine indirilir (HITL risk katmanları).

Onay kapısı JSON zarfı

base64 çıktısı:

{ "allowed": true }

Dosya çıktısı, output-approval bölümünde açıklanan sınama zarfını döndürür.