NextPDF Connect ile ilk PDF'inizi oluşturun

Bir bakışta

Bu reçete, NextPDF Connect ile boş bir oturumdan işlenmiş bir PDF’e ulaşmanın en kısa yolunu gösterir. Tek sayfalık bir A4 belgesi oluşturur, başlık ve alt başlık ekler, ardından dosyayı base64 olarak döndürürsünüz. İşi üç Core aracı yapar: create_pdf, add_text ve output_pdf. Yazı tiplerine, görüntülere veya lisanslı bir katmana ihtiyacınız yoktur.

Connect taşıma katmanı, her araç çağrısını bir istek olarak gönderir ve aracın sonucunu bir yanıt olarak döndürür. Taşıma katmanı, aracın bildirdiği sonuçtan bağımsızdır (PSR-18 §p2).

Kurulum

NextPDF Server’ı kurun ve bir taşıma katmanı bağlayın:

composer require nextpdf/server

Sunucuyu, ana makinenizin beklediği taşıma katmanıyla çalıştırın: stdio üzerinden Model Context Protocol, REST veya gRPC. Aşağıdaki Taşıma katmanı kullanılabilirliği bölümüne bakın. Bu reçetedeki araçlar Core araçlarıdır; sunucuyla birlikte gelirler, bu nedenle bir Pro veya Enterprise paketine ihtiyacınız yoktur.

Kavramsal genel bakış

Bir Connect oturumu, bir document_id ile anahtarlanan sunucu tarafındaki bir belge deposudur. create_pdf bir oturum açar ve id’yi döndürür. Sonraki her araç çağrısı bu id’yi kullanır. Belge tek bir boş sayfayla başlar. Sayfa ağacı, okuyucunun her sayfaya ulaşmak için kullandığı yapıdır (ISO 32000-2 §7.7.3). output_pdf oturumu bir PDF’e işler. Varsayılan olarak, bunu yaptıktan sonra belleği boşaltmak için oturumu yok eder.

Bir add_text çağrısını açık bir x veya y olmadan yaptığınızda, metin yerine akar. Mevcut imleç konumundan başlar ve imleç her çağrıdan sonra ilerler.

API yüzeyi

Araç kayıt defteri, sunucu başladığında bu araçları çözer. Burada gösterilen adlar, kayıt defterindeki protokol adlarıdır. Resmi katalog, birleştirilmiş araç kataloğudur. Kullanılabilir araçlar kurulu katmana bağlıdır, ancak bu üçü her zaman Core’da bulunur.

Araç	Rol	Risk katmanı
create_pdf	Bir belge oturumu açar	Güvenli
add_text	Belgeye metin yazar	Dikkat
output_pdf	PDF’i işler ve döndürür	Onay gerekli (dosya modu) / İnceleme (base64)

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

Ana makine üç araç çağrısı yapar. Sırasıyla:

1. Önce create_pdf aracını page_size: "A4", orientation: "portrait" ile ve belgenin başlığı ve yazarıyla çağırın. Sunucu bir document_id döndürür.
2. Ardından add_text aracını o document_id ile, başlık metniyle, büyük bir font_size ile, width: 0 (tüm içerik genişliği) ve alignment: "center" ile çağırın.
3. Son olarak output_pdf aracını document_id ile çağırın. file_path belirtilmediğinde sunucu PDF’i base64 olarak döndürür ve oturumu yok eder.

En küçük create_pdf bağımsız değişken nesnesi şöyledir:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Yanıt, document_id değerini, sayfa sayısını ve sayfa geometrisini içerir. id’yi opak bir değer olarak ele alın ve ondan anlam çıkarmayın.

Kod örneği — üretim

Üretim ortamındaki çağıran taraf, bir sonraki çağrıyı yapmadan önce her yanıtı denetler. document_id değerini, output_pdf oturumu yok ettikten sonra asla yeniden kullanmaz.

1. create_pdf — yanıtın bir document_id içerdiğini doğrulayın. Sunucu oturum sınırı hatasını döndürürse, kullanılmayan oturumları serbest bırakın ve yeniden deneyin.
2. add_text (başlık) — yanıtın bir position döndürdüğünü doğrulayın.
3. add_text (alt başlık) — daha küçük bir font_size kullanın; imleç başlığın altından devam eder.
4. output_pdf — base64 alanını okuyun ve bayt dizisine çözün. destroyed bayrağı oturumun kaybolduğunu doğrular.

Dosya satır içi olarak döner (base64 modu), bu nedenle dosya sistemi yan etkisi ya da insan onayı kapısı yoktur. HITL risk katmanı bölümüne bakın.

Sınır durumları ve püf noktaları

• Yok edilmiş oturum. output_pdf varsayılan destroy: true ile çalıştıktan sonra document_id artık geçerli değildir. Bu değeri kullanan sonraki herhangi bir çağrı, bilinmeyen belge hatası döndürür. Bunun yerine yeni bir oturum oluşturun.
• Bilinmeyen sayfa boyutu. Sunucu, tanımadığı bir page_size değerini reddeder ve net bir hata döndürür. Belgelenmiş bir boyut kullanın (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Boş metin. Boş bir text hata değildir; sıfır genişlikli bir giriş üretir. Çağrıdan önce girdinizi denetleyin.
• Oturum sınırı. Bellek içi depo, aynı anda kaç oturumun çalışacağını sınırlar. Oturumları output_pdf ile gecikmeden serbest bırakın.

Performans

Yalnızca metin içeren tek bir sayfa, sayfa bütçesinin çok altında işlenir ve çıktı genellikle 1–3 KB olur. Bu reçete, çift işlemeli yeniden üretilebilirlik profili structural kullanır. PDF, çalıştırmalar arasında değişen bir fragman (trailer) /ID ve zaman damgaları taşır; bu nedenle doğru karşılaştırma yapısal (normalleştirilmiş) karşılaştırmadır.

Güvenlik notları

base64 yolunda herhangi bir dosya sistemi yan etkisi yoktur. Dosya çıktısı yolunda ise bir yan etki vardır ve bu yol kapı denetimine tabidir. HITL bölümüne bakın. Döndürülen base64’ü güvenilir bir kanal olarak değil, belge içeriği olarak ele alın. Bunlar, araçların tam olarak ürettiği baytlardır.

Uygunluk

Beyan	Spesifikasyon	Madde	reference_id
Bir taşıma katmanı, sonuçtan bağımsız olarak bir istek gönderir ve bir yanıt alır.	PSR-18	§p2
Sayfalara, belgenin sayfa ağacı aracılığıyla ulaşılır.	ISO 32000-2	§7.7.3

Bu reçete, sunucunun çıktıyı nasıl ürettiğini açıklar. Profil uygunluğu iddiasında bulunmaz.

Ticari bağlam

Uygulanamaz — üç aracın üçü de Core’dur.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	Araç çağrıları MCP tools/call ile eşlenir.
REST	Evet	Her araç bir REST işlemidir; sonuç, yanıt gövdesidir.
gRPC	Evet	Her araç tekli (unary) bir çağrıdır.

Araç sonucu, taşıma katmanları arasında aynıdır; yalnızca çerçeveleme farklıdır. Başarısız bir sonuç, taşıma katmanı hatası değil, yine normal bir yanıttır (PSR-18 §p2).

HITL risk katmanı

Sunucu, her araç çağrısını insanın döngüde olduğu (HITL) risk merdivenine yerleştirir: Güvenli (0) → Dikkat (1) → İnceleme (2) → Onay gerekli (3). create_pdf Güvenli, add_text ise Dikkat düzeyindedir. output_pdf Onay gerekli düzeyindedir, ancak base64 modunda (file_path olmadan) İnceleme düzeyine düşer ve insan onayı olmadan çalışır. Bir dosyaya yazmak, onu Onay gerekli düzeyinde tutar. output-approval sayfasına ve HITL risk katmanları başvurusuna bakın.

Onay kapısı JSON zarfı

Bu reçete base64 modunda kalır, bu nedenle onay kapısı izin zarfını döndürür:

{ "allowed": true }

Sınama zarfı (allowed: false, bir challenge dizesi ve tek kullanımlık bir token ile) output-approval sayfasında belgelenmiştir.

Ayrıca bakınız

• Çok sayfalı belge
• Görüntü gömme
• Araç kataloğu
• HITL risk katmanları