Kararlı belge sözleşmeleri için Şablon PDF API'si
Tekrarlanan yerleşimler bir kez sahiplenilip ERP, OMS, WMS veya SaaS çağıran sistemler tarafından yeniden kullanılacaksa kararlı template_id ve data array ile PDF render edin.
/api/v1/template-render Her çağıran sistemden her request'te sayfas, koordinatlar ve yerleşim elementler tarif etmesini istemek yerine kararlı template_id ve iş verisi array göndererek repeated PDFs render etmek.
Bu API ne zaman kullanılır
- Document yerleşim onaylandı ve birden çok çağıran sistem veya job tarafından yeniden kullanılıyor.
- Çağıran sistemler koordinat düzeyinde yerleşim JSON değil iş verisi göndermeli.
- Invoice, packing list, gönderi etiketi veya özel template çıktı gerekiyor.
- Active template revisions çağıran sistem dışında kontrol edilsin istiyorsunuz.
Neyin yerine geçmez
- Yerleşim hâlâ tasarlanıyor. Coordinates ve alanlar kararlı olana kadar JSON Render kullanın.
- Serbest biçimli HTML-to-PDF conversion gerekiyor.
- Embedded CII XML ile e-fatura PDF'i/A-3b paketleme gerekiyor.
Hangi endpoint çağrılır
/api/v1/template-render
Template Render bu iş akışı için varsayılan yoldur.
/api/v1/pdf/render
İş akışı ilgili API yoluna, template sözleşmesine veya capability sorgusuna ihtiyaç duyduğunda kullanın.
Minimum request
POST /api/v1/template-render - template'ten tek invoice render.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
gPdf neyi üstlenir
- Kararlı template_id ile template lookup.
- Her data item'ı active şablona karşı render etmek.
- Public endpoint limitleri içinde rendered sayfas'i tek PDF'te birleştirmek.
- Shared authentication, request ID ve error envelope behavior.
Sisteminiz neyi yönetir
- Şablon seçimi, alan eşlemesi, iş verisi ve çağıran sistem yetkilendirmesi.
- Template publication iş akışı, change communication ve test coverage.
- Çok sayıda belge render edilirken parçalama, kuyruklama ve retry'lar.
Production kontrol listesi
- template_id'yi opaque kararlı sözleşme olarak ele alın.
- Template Render çağırmadan önce veri alanlarını doğrulayın.
- Active template ve representative data için golden-PDF tests tutun.
- Large toplu iş'leri public Template Render limits'e göre bölün.
- İzlenebilirlik için template_id, request ID ve iş nesnesi IDs loglayın.
İddia sınırları
- Template Render tek başına design tool değildir; şablonlar zaten published olmalıdır.
- gPdf template'ten eksik iş verisi çıkarımı yapmaz.
- Template Render, E-Invoice Render endpoint'inin yerine geçmez.
Template Render üretim sözleşme katmanı’dır
JSON Render yerleşim tasarlanırken idealdir. Yerleşim sözleşme haline geldikten sonra kullanılacak katman Template Render’dır. Çağıran sistemler template_id ve data gönderir; aktif şablonun belge yapısı’ı sahiplenir.
Bu model çağıran sistemlerı küçültür ve template değişikliklerinin review, test ve rollout sürecini kolaylaştırır.
SSS
- Template Render'ı JSON Render yerine ne zaman kullanmalıyım?
- Yerleşim onaylandıktan ve çağıran sistemler yalnızca iş verisi göndermeli olduktan sonra Template Render kullanın.
- template_id kararlı mı?
- Evet. Template API dokümanları template_id'yi kararlı çağıran sisteme dönük tanımlayıcı olarak açıklar.
- Tek request birden çok data item render edebilir mi?
- Evet, Template Render public endpoint limitleri içinde data array kabul eder.
- Template Render e-invoice oluşturabilir mi?
- Hayır. Factur-X ve ZUGFeRD PDF/A-3b paketleme E-Invoice Render endpoint kullanır.