Faturalama ve finans sistemleri için fatura PDF API'si
Vergi ve muhasebe mantığı sisteminizde kalırken faturalama verisinden JSON Render veya Template Render ile sıradan fatura PDF'leri oluşturun.
/api/v1/pdf/render Faturalama, ERP veya SaaS sisteminden gelen fatura verisini okunabilir bir PDF faturaya dönüştürürken numaralandırmayı, vergiyi, ödeme durumunu ve muhasebe semantiğini çağıran sistemde tutmak.
Bu API ne zaman kullanılır
- Müşteriler, makbuzlar, hesap ekstreleri veya muhasebe dışa aktarımları için sıradan fatura PDF'leri gerekiyor.
- Sisteminiz fatura numarası, vergi hesaplaması, satır kalemleri ve ödeme durumuna zaten sahip.
- Browser çalıştırmadan tablolar, toplamlar, metadata ve isteğe bağlı PDF/A ayarları istiyorsunuz.
- Tekrarlanan fatura yerleşimleri için template_id sözleşmesi istiyorsunuz.
Neyin yerine geçmez
- Factur-X veya ZUGFeRD gibi legal e-fatura paketi gerekiyor. E-Invoice Render kullanın.
- gPdf'in vergi hesaplamasını, muhasebe kuralları doğrulamasını veya ödeme mutabakatı yapmasını bekliyorsunuz.
- Yapılandırılmış JSON veya şablonlar yerine serbest biçimli HTML fatura dönüşümü istiyorsunuz.
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.
/api/v1/e-invoice/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 fatura başlığı ve toplam.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
gPdf neyi üstlenir
- JSON sayfalarından veya şablon verisinden fatura PDF'i render işlemi.
- Metin, tablolar, toplam blokları, sayfalama, metadata ve isteğe bağlı PDF/A çıktısı.
- Birden çok sistemin kullandığı kararlı fatura yerleşimleri için Template Render.
- Binary PDF yanıtı ve tutarlı API error envelope.
Sisteminiz neyi yönetir
- Fatura numaraları, ödeme durumu, vergi hesaplaması, indirimler, alacaklar ve muhasebe kaydı anlamı.
- Müşteri ve düzenleyen verisi, satır kalemi eşlemesi, para birimleri ve yuvarlama kuralları.
- Saklama, teslimat, e-posta, ödeme linkleri ve muhasebe sistemi mutabakatı.
Production kontrol listesi
- Görünen her fatura alanının kaynak faturalama verisine eşlendiğini doğrulayın.
- Satır kalemi taşmalarını, uzun müşteri adları, çok sayfalı faturaları ve toplamlar test edin.
- Yerleşimin JSON Render'da mı yoksa yayınlanmış şablonda mı duracağına karar verin.
- Sıradan fatura PDF'i oluşturma ile legal e-invoice paketlemeyi ayrı tutun.
- Request ID'leri ve çıktı dosya adlarını fatura kayıtları ile saklayın.
İddia sınırları
- Sıradan fatura PDF'leri yasal e-invoice zorunlulukları ile aynı şey değildir.
- gPdf fatura belgesini render eder; vergi veya muhasebe durumu hesaplamaz.
- Factur-X / ZUGFeRD çıktısı POST /api/v1/e-invoice/render üzerindedir.
Sıradan faturalar ve e-invoice’lar
Sıradan fatura PDF’i, müşterinizin okuduğu belgedir. JSON Render veya Template Render ile üretilebilir. Fatura numarası, vergi, satır kalemleri, para birimi ve ödeme durumu kararları sizin sisteminizdedir; gPdf görünür PDF’i render eder.
Legal e-invoice farklıdır. Factur-X ve ZUGFeRD, okunabilir PDF/A-3b fatura ile gömülü EN 16931 CII XML’i birleştirir. Bu paket için POST /api/v1/e-invoice/render kullanın.
Template Render genellikle üretim endpoint’idir
Finans ekipleri her servisin fatura koordinatlarını yeniden kurmasını istemez. Yaygın yol faturayı bir kez tasarlamak, şablon olarak yayınlamak ve çağıran sistemlere kararlı template_id ve veri şeması vermektir. JSON Render özel yerleşimler, iç araçlar ve şablon prototipleme için kullanışlı kalır.
Muhasebe mantığını kaynak sistemde tutun
gPdf çözülmemiş muhasebe kararları değil, son gösterilecek değerleri almalıdır. Render API’yi çağırmadan önce vergiyi, indirimleri, yuvarlamayı, ödeme durumunu ve fatura uygunluğunu hesaplayın. Böylece PDF çıktısı deterministik olur ve finans sistemi tek doğru kaynak olarak kalır.
SSS
- Fatura PDF'i ile e-invoice aynı şey mi?
- Hayır. Sıradan fatura PDF'i insan tarafından okunabilir çıktıdır. Factur-X veya ZUGFeRD e-invoice ayrıca PDF/A-3b sarmalayıcı içinde EN 16931 CII XML gömer.
- Tekrarlanan faturalar hangi endpoint'i kullanmalı?
- Fatura yerleşimi kararlıysa ve çağıran sistemler yalnızca template_id ve data göndermeliyse Template Render kullanın. Yerleşim kodda duruyorsa JSON Render kullanın.
- gPdf vergi hesaplar mı?
- Hayır. Faturalama veya muhasebe sisteminiz vergi, toplamlar, indirimler ve ödeme durumunu render verisi göndermeden önce hesaplar.
- Fatura PDF'leri PDF/A kullanabilir mi?
- Evet, JSON Render PDF/A ayarları destekler. Fatura Factur-X veya ZUGFeRD olarak paketlenmeliyse özellikle E-Invoice Render kullanın.