Veri biçimleri · PDFgine

Verinizi hangi biçimde göndereceğinizi burada bulursunuz. PDFgine gönderdiğiniz değeri olduğu gibi basmaz; şablonun tanımladığı biçimlendiriciyi belgenin diline göre uygular.

Kural tek cümle: veri ham gelir, biçimlendirmeyi PDFgine yapar. Elle biçimlendirilmiş bir değer gönderirseniz belge tek dilde doğru, diğerinde yanlış görünür.

Alan tipi	Nasıl gönderilir	Örnek giriş	Çıktı
`date`	ISO 8601. Yalnız gün için YYYY-MM-DD, saat gerekiyorsa tam zaman damgası. Yerel biçime çevirmeyin.	`"2026-09-06"`	`6.09.2026`
`number`	JSON sayısı. Binlik ayracı, boşluk ya da tırnak koymayın; ondalık ayracı noktadır.	`24000`	`24.000,00`
`currency`	Tutar ham sayı olarak gönderilir. Para birimi tutarın içine yazılmaz; sütunun biçimlendiricisinde ISO 4217 kodu olarak durur.	`24000`	`24.000,00 TRY`
`percent`	Oran yüz üzerinden ham sayıdır: %18 için 18 gönderin. Yüzde işaretini belge ekler.	`18`	`%18,00`
`string`	Metin olduğu gibi basılır. Tarih, tutar ya da oranı metin olarak göndermeyin; biçimlendirme kaybolur.	`"Acme Teknoloji A.Ş."`	`Acme Teknoloji A.Ş.`
`boolean`	JSON true/false. Koşullu blokların ölçtüğü değerdir.	`true`	Koşul sonucu; metne çevrilmez

Biçimlendirici üç yerde tanımlanır: tablo sütununda ve özet satırında "format" alanı, tek değer basan öğede "dataRules.formatter", birden çok alanı birleştiren metinde ise format_date ve format_money işlevleri.

Veri ve şablon

{
  "issueDate": "2026-09-06",
  "currency": "TRY",
  "lineItems": [
    { "name": "Kurumsal web sitesi", "quantity": 1, "unitPrice": 24000, "total": 24000 }
  ]
}

// Sablon tarafinda:
// tablo sutunu:  "format": { "kind": "currency", "currency": "TRY", "decimals": 2 }
// tarih sutunu:  "format": { "kind": "date", "dateStyle": "short" }
// metin ogesi:   "{{ referenceNo }} · {{ format_date issueDate }}"

IBAN, telefon ve vergi numarası da kanonik gönderilir: IBAN boşluksuz, telefon E.164 (+905321234567). Gruplama bir sunum biçimidir, veride bulunmaz.

Belgenin indirileceği ad

İndirilen belge "{belge tipi} - {karşı taraf} - {referans no}" biçiminde adlandırılır. Üç parça gönderdiğiniz veriden gelir: document.title, customer ve referenceNo. Eksik olan atlanır; hiçbiri kullanılabilir bir ad üretemezse belge kendi kimliğine düşer, örneğin quote-doc_94812af2.pdf.

Cevap başlığı

Content-Disposition: attachment;
  filename="Teklif - Deniz Mimarlık Ltd. Şti. - TKF-2026-0042.pdf";
  filename*=UTF-8''Teklif%20-%20Deniz%20Mimarl%C4%B1k%20Ltd.%20%C5%9Eti.%20-%20TKF-2026-0042.pdf

Ad aynı başlıkta iki kez yazılır. Genişletilmiş alan belgenin kendi dilini korur; klasik alan, genişletilmiş alanı okuyamayan istemciler için adın okunabilir ASCII yazımını taşır. Dosya sisteminin kabul etmediği karakterler (slash, ters slash, iki nokta, yildiz, soru, tirnak, kucuktur, buyuktur, dikey cizgi) ve kontrol karakterleri temizlenir, ad her dosya sisteminde geçerli kalacak uzunlukta kesilir.

Görseller

Şablondaki görsel öğesi bir veri alanına bağlanabilir; o zaman görselin kaynağı istekte gelir. İki biçim kabul edilir: yüklenmiş bir varlığın kimliği (ast_… — tekrar eden logolar, damgalar, imzalar için; bir kez yüklenir, istekte yalnız kimlik gider) ve satır içi görsel (data:image/png;base64,… — tek seferlik görseller için). Alan boş ya da yoksa şablonun kendi görseli kullanılır; değer varsa ve kullanılamıyorsa istek 422 ile reddedilir ve cevap hangi veri alanının sorunlu olduğunu söyler.

İstek

{
  "templateCode": "invoice",
  "format": "pdf",
  "data": {
    "logo": "ast_9f1c7b1f0f6b4f5f9f0a0d1e2c3b4a59",
    "signature": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Sınırlar: satır içi görsel PNG, JPEG veya WebP olmalı; görsel başına en fazla 2 MB, bir belgedeki görsellerin toplamı en fazla 6 MB. Yüklenen varlık en fazla 10 MB. Geçici görseller için varlık yüklerken expiresInMinutes verin (1 dakika – 7 gün); süresi dolan varlık kendiliğinden silinir.

Varlıklar

Logo, imza ve yazı tipleri bir kez yüklenip kimliğiyle kullanılır. Yükleme, sınırlar ve yazı tipinin neye izin verdiği kendi sayfasında.

Varlıklar →

Sık takılınan yerler

Önceden biçimlendirilmiş değer geldiği gibi basılır. "1.234,56" bir dilde doğru, diğerinde yanlış okunur ve hiçbir biçimlendirici bunu sonradan düzeltemez.
Tarih ISO 8601 olmalı. Yerel biçim metin olarak gelir: biçimlenmez, sıralanmaz, çevrilmez.
Para birimi tutarın içinde durmaz. Sayıyı gönderin, ISO kodunu sütun biçimlendiricisi eklesin.
Oran yüz üzerinden gönderilir: %18 için 18. 0,18 göndermek yüzde sıfır virgül on sekiz yazar.
Koşul JSON mantıksal değerini okur. "false" metni boş olmayan bir yazıdır ve "var" sayılır.