Yapılandırılmış belge oluşturma için JSON'dan PDF'ye API
Backend verilerinden DocumentRequest ile browser çalıştırmadan deterministik PDF üretin; yerleşim, PDF/A seçenekleri ve template_id geçişi açık kalır.
/api/v1/pdf/render Uygulamanızın yapılandırılmış verisini DocumentRequest içinde sayfalara, elementlere, stillere ve ayarlara çevirerek public JSON Render API üzerinden deterministik PDF çıktısı almak.
Bu API ne zaman kullanılır
- Yerleşimi kod veya backend servisi tarif ediyor.
- HTML-to-PDF veya headless browser çalıştırmadan PDF istiyorsunuz.
- PDF/A, metadata, barkodlar veya şablona geçiş gibi API düzeyindeki seçenekleri kontrol etmek istiyorsunuz.
- OpenAPI sözleşmesine bağlı, dil bağımsız bir render yüzeyi istiyorsunuz.
Neyin yerine geçmez
- Takımınızın her belgeyi gPdf Studio'da yayınlanmış şablon olarak yönetmesi gerekiyor. Template Render kullanın.
- Serbest biçimli website HTML'ini PDF'e çevirmek istiyorsunuz.
- Factur-X / ZUGFeRD e-invoice paketlemesine ihtiyacınız var. E-Invoice Render kullanın.
Hangi endpoint çağrılır
/api/v1/pdf/render
JSON Render bu iş akışı için varsayılan yoldur.
/api/v1/template-render
İş akışı ilgili API yoluna, template sözleşmesine veya capability sorgusuna ihtiyaç duyduğunda kullanın.
Minimum request
POST /api/v1/pdf/render - minimal DocumentRequest.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
gPdf neyi üstlenir
- DocumentRequest içinden PDF render işlemi.
- Metin, şekiller, tablolar, görseller, barkodlar, sayfa boyutları, metadata ve PDF/A ayarları.
- API error envelope, request ID ve binary PDF yanıtı.
- Yerleşim kararlı olduğunda template_id tabanlı Template Render'a geçiş yolu.
Sisteminiz neyi yönetir
- İş verisi, doğrulama, yetkilendirme ve render isteğinin ne zaman yapılacağı.
- Belge semantiği, kayıt tutma, teslimat ve kullanıcıya gösterilecek durum.
- Büyük toplu işlerde bölümlendirme, retry, kuyruklama ve depolama.
Production kontrol listesi
- DocumentRequest şemanızı OpenAPI ile doğrulayın.
- Gerçek veride uzun metinler, çok sayfalı belgeler ve uç durumları test edin.
- Her request için X-Request-Id üretin ve iş nesnesi ile eşleyin.
- Kararlı yerleşimleri template_id sözleşmesine taşımayı planlayın.
- PDF/A veya e-invoice gereksinimlerini endpoint seçimiyle açıkça ayırın.
İddia sınırları
- JSON Render iş akışı veya veritabanı değildir.
- gPdf payload'u render eder; iş doğrulaması ve alan semantiği çağıran sistemde kalır.
- PDF/A setting e-fatura paketi ile aynı şey değildir; Factur-X / ZUGFeRD için e-invoice yolu kullanılır.
JSON Render iş akışı nereye oturur
JSON Render, uygulama verisini açık bir DocumentRequest olarak gönderdiğiniz public render yoludur. Çağıran sistem sayfaları, elementleri, stilleri ve ayarları tarif eder; gPdf PDF’i render eder ve binary yanıt döner.
Bu model backend, serverless worker veya ERP entegrasyonu gibi farklı ortamlardan aynı HTTP sözleşmesi kullanmayı sağlar. OpenAPI şeması alan adları ve endpoint davranışı için tek doğru kaynak olarak kalır.
Template Render’a ne zaman geçilir
Yerleşim hâlâ değişiyorsa JSON Render hızlıdır. Yerleşim bir belge sözleşmesine dönüştüğünde, onu yayınlanmış şablona taşıyıp çağıran sistemlerin kararlı template_id ve data göndermesi daha temizdir.
Üretim şekli
Üretimde her render isteği izlenebilir olmalıdır: kaynak nesne ID’si, X-Request-Id, çıktı dosya adı ve doğrulama kanıtı birlikte saklanmalıdır. PDF/A veya e-invoice gibi profilleri endpoint niyetine göre açıkça ayırın.
SSS
- JSON Render ne zaman doğru seçimdir?
- Yerleşimi kod tarif ediyorsa veya yeni belge yapısını hızlıca deniyorsanız JSON Render doğru başlangıçtır.
- template_id ne zaman devreye girer?
- Yerleşim kararlı olduğunda ve çağıran sistemlerin yalnızca data göndermesi istendiğinde aynı belgeyi Template Render ile yayınlanmış template_id üzerinden çağırın.
- OpenAPI burada neden önemli?
- OpenAPI, request/response sözleşmesinin kaynağıdır. JSON alanları, endpoint'ler ve desteklenen ayarlar oradan doğrulanmalıdır.
- JSON Render PDF/A üretir mi?
- Evet, desteklenen PDF/A ayarları JSON Render içinden kullanılabilir. Legal e-fatura paketi gerekiyorsa E-Invoice Render kullanın.