Şablon JSON şeması

Tanımın şekli

Şablon tanımı iki parçalı tek bir nesne: sayfayı belirleyen page ve onun üzerine çizilen sıralı liste olan elements.

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

Sayfa boyutları: A4 · A3 · Letter. Yön portrait ya da landscape; kenar boşlukları inç başına 96 CSS pikseli.

Hangi öğe hangi alanı kabul eder

Her öğe id, type, placementMode alanlarını taşır. Gerisi tipe bağlı ve aşağıdaki tablo, doğrulayıcının okuduğu kural kümesinden üretiliyor — üründen geri kalamaz.

Tipinin satırında olmayan bir alan yok sayılmaz, doğrulamadan geçmez. Sessizce düşürülen alan daha kötüsü olurdu: belge eksik çıkar, istek ise başarılı görünür.

placementMode

Öğenin sayfadaki yerini nasıl bulduğu. Bu kip aynı zamanda layout.x ve layout.y değerlerinin okunup okunmayacağını da belirler.

• flow — sayfada birbiri ardına dizilir; x ve y yok sayılır ve öğe içeriğiyle birlikte büyür
• free — layout.x ve layout.y ile tam koyduğunuz yere yerleşir
• band — öğenin adlandırdığı bantta her sayfada tekrarlanır; üst bilgi ya da alt bilgi gibi

Veri kümesi öğesi

Veri kümesi, tablo olmayan bir koleksiyonu basar: ziyaret listesi, fotoğraflar ya da imzalar — sütunlarla değil, şablonun verdiği yerleşimle çizilir.

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

binding, tabloda olduğu gibi verinizdeki dizinin adıdır. Her öğe için neyin çizileceği layout ve style'dan gelir; yani aynı koleksiyon bir şablonda tablo, başka bir şablonda veri kümesi olabilir.

Veri kümesinin content alanı yoktur. Yalnız binding'den beslenir — content'te duran metin çıktıya hiç ulaşmıyordu, o yüzden alan yazmanın karşılığı olmayan bir yer olarak bırakılmak yerine kaldırıldı.

Üretimden önce veriyi denetleme

Doğrulama ucu, bir üretimin cevaplayacağı soruyu kota harcamadan cevaplıyor: bu veri şablonun istediğini karşılıyor mu?

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

Sık takılınan yerler

• Öğe tipine ait olmayan bir alan yok sayılmaz, doğrulamayı düşürür. Bu kasıtlı: sessizce düşen bir alan, eksik bir belge üretir ve kimse olmayan şeyi aramaz.
• Akış yerleşiminde layout.x ve layout.y hiç okunmaz. Onları verip hiçbir şeyin kımıldamamasına şaşırmak en sık sorulan şema sorusudur.
• Veri kümesinin content alanı yoktur; yalnız binding ile beslenir. content'e konan metin çıktıya hiç ulaşmaz.
• Kenar boşlukları ve ölçüler milimetre değil, inç başına 96 CSS pikselidir. Milimetre sanılarak yazılan 20, üç kat küçük çıkar.
• Verinin uyup uymadığını öğrenmek için üretim yapmak bir sayfaya mal olur. Doğrulama ucu aynı soruyu bedelsiz yanıtlar.