Şablonlar, roller ve alanlar

Şablon, yeniden kullanılabilir bir sözleşmedir. Bir adı, tek bir taslağı ve istenen sayıda yayımlanmış sürümü vardır. Zarflar her zaman yayımlanmış ve değiştirilemez bir sürümden oluşturulur: bir şablonu düzenlemek, yeni bir taslak kaydedip onu sonraki sürüm olarak yayımlamak anlamına gelir. Zaten gönderilmiş zarflar sabitledikleri sürümü korur.

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Kimlikler ön ekli dizelerdir (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); zaman damgaları UTC cinsinden RFC 3339 biçimindedir.

İki yazım yöntemi

Yerleşim modu (source: "pdf") yüklenen bir belgeyle başlar. Alanlar, sayfalarına PDF noktası (1/72 inç) cinsinden yerleştirilen dikdörtgenlerdir; başlangıç noktası sayfanın sol üst köşesidir, sayfa dizini 0’dan başlar. Yüklenen bir .docx dosyası bir kez PDF’e dönüştürülür (LibreOffice ile, Word düzeni korunarak; dosyanın gömmediği yazı tiplerinin yerine başkaları kullanılabilir) ve o andan itibaren diğer PDF’ler gibi bir PDF olur: dosya convertedFrom: "docx" bildirir. Yerleşim sürümleri, sürüm yayımlandığında uygulanan içerik düzenlemeleri (yerinde düzenlenen metin, beyazlatma, metin kutuları, görseller, sayfa işlemleri) de taşıyabilir.

Belge modu (source: "document") sözleşmenin kendisini zengin metin (ProseMirror JSON) olarak saklar; {{client.name}} gibi değişken etiketleri, satır içi alan blokları, koşullu bölümler (yalnızca bir showIf ifadesi doğru olduğunda tutulur) ve tekrarlanan bölümler ile tablo satırları (bir dizi değişkenindeki her öğe için bir tane) içerir. Her zarf kendi PDF’ini oluşturur ve alan konumları bu çıktıdan okunur. Panelde Belge modu “Boş belgeyle başla” seçeneğidir. API üzerinden bir Word dosyası POST /v1/templates/{id}/import ile Belge moduna da aktarılabilir: {{tags}} değişkenlere veya alanlara, imza satırları (“Signature: ____”, “By: ____”, “Date: ____”) ise alan bloklarına dönüşür.

Panelde

Yeni şablon iki başlangıç sunar:

Belge yükle: 25 MB’a kadar .pdf ve .docx dosyaları için tek bir bırakma alanı. Word dosyaları PDF’e dönüştürülür ve alanları yerleştirmeden önce dönüştürülen düzeni kontrol etmenizi hatırlatan bir notla tasarımcıda açılır. Küçük düzeltmeler PDF üzerinde yerinde yapılır (“İçeriği düzenle”); daha kapsamlı bir yeniden yazım için Word dosyasını değiştirip yeniden yükleyin.
Boş belgeyle başla: sözleşmeyi Belge modunda yazın.

İçerik düzenlemeleri

Tasarımcının İçeriği düzenle modu, yüklenen dosyaya dokunmadan imzacıların gördüğünü değiştirir. Varsayılan aracı olan Metni düzenle, sayfanın metin bloklarını (PDF’in metin katmanından gruplanan satırlar ve paragraflar) vurgular; birini tıklayın veya Tab ile ona gelip Enter’a basın ve aynı konum, boyut, renk, hizalama ve yazı tipiyle yerinde düzenleyin. Ctrl/Cmd+Enter kaydeder, Esc iptal eder ve her düzenleme düzenlemeler listesinden geri alınabilir. Düzenlemeler diğer tüm değişiklikler gibi geri alınabilir. Diğer araçlar beyazlatma, metin kutuları ve görseller ekler; sayfa ekler, siler, yeniden sıralar veya döndürür.

Yerinde bir metin düzenlemesi, bir group değerini paylaşan iki öğe olarak saklanır: orijinal bloğun üzerinde bir beyazlatma (sayfanın arka plan renginde) ve bloğun satır yüksekliği ile ilk taban çizgisini kullanarak blok içine yerleştirilen bir metin öğesi:

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face yazı tipini seçer: yeni metnin her karakterini çizebiliyorsa PDF’in gömülü yazı tipi, aksi hâlde eşleşen kalınlık ve stilde, birlikte gelen ölçü uyumlu bir yazı tipi (Helvetica/Arial için sans Arimo, Times için serif Tinos, Courier için mono Cousine, Calibri için carlito Carlito). Metin blok içinde kaydırılır; orijinalden daha fazla satır gerektiğinde düzenleme altındaki boş alana doğru büyür, boş alan yoksa tasarımcı kaydetmeyi reddeder (“metin sığmıyor — kısaltın veya yer açın”). Tasarımcı ve API aynı düzen ve yazı tipi kodunu paylaşır; böylece yayımlanan PDF önizlemeyle satır satır eşleşir.

Düzenlemeler yalnızca bir taslağı değiştirebilir. Yayımlama, düzenlemeleri SHA-256 değeri sürümün documentHash değeri (imzacıların gördüğünün hash’i) olan yeni bir temel PDF’e uygular; yüklenen orijinal, sürümün sourceFile değeri olarak saklanır ve sonraki taslak aynı düzenlemelerle bu dosyadan başlar. Beyazlatma içeriği görsel olarak örter; orijinal metin dosyada altta kalır, bu nedenle güvenli bir karartma değildir.

Roller

Roller sözleşmenin taraflarıdır. Bir zarfın alıcıları rollerle key üzerinden eşleştirilir.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }

Özellik	Anlamı
`key`	Alanlar ve zarf alıcıları tarafından kullanılan küçük harfli tanımlayıcı (`^[a-z][a-z0-9_]*$`)
`kind`	`signer` (bir imza veya paraf alanı olmalıdır), `approver`, `form_filler` veya `cc` (alır, hiçbir zaman imzalamaz)
`order`	1’den başlayan yönlendirme sırası. Aynı sıradaki roller paralel imzalar; onlar bitirdiğinde sonraki sıra başlar
`verification`	Rolün alıcısının kimliğini nasıl kanıtladığı: `none` (varsayılan: yalnızca benzersiz imzalama bağlantısı) veya `email_otp` (bağlantı artı e-postayla gönderilen kod). Alıcı bunu geçersiz kılabilir; bkz. imzacı doğrulaması

passkey, id_check ve sms_otp şemada yer alır ancak henüz imzalama için kullanılamaz: passkey veya id_check kullanan bir şablon yayımlanamaz ve SMS kodları henüz gönderilmez.

Alanlar

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Alan türleri: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp ve variable_text (bir imzacı tarafından değil, gönderen tarafından bir değişkenden doldurulur). Alanlar ayrıca şunlara sahip olabilir:

variable: alanı bağlamak veya ön doldurmak için değişkenlerin içine işaret eden bir JSON Pointer (/client/name);
radio ve dropdown için options;
validation: pattern, min, max, maxLength veya bir format (email, phone, date, number, currency);
showIf: değişkenler ve diğer alanlar üzerinde plan != "free" gibi bir koşul;
formula: hesaplanan, salt okunur bir değer;
overflow: bir değer kutuya sığmadığında ne yapılacağı: shrink (varsayılan), wrap veya reject.

Değişkenler

Bir sürümün variables değeri, her zarfla gönderdiğiniz veriler için bir JSON Schema’dır (draft 2020-12); sürümün sampleVariables değeri bir örnektir. POST /v1/envelopes, variables değerlerinizi bu şemaya göre doğrular ve her sorunu bir JSON Pointer ile bildirir:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

Sonucu göndermeden önce görmek için herhangi bir sürümün filigranlı önizlemesini POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) ile oluşturun veya zarfı ?dry_run=true ile oluşturun.

API ile şablon oluşturma

Çoğu ekip şablonları paneldeki tasarımcıda tasarlar. Tasarımcının yaptığı her şey API üzerinden de kullanılabilir:

{ "name": "Mutual NDA" } ile POST /v1/templates.
Gövde olarak (Content-Type: application/pdf) veya file multipart alanı olarak PDF (veya .docx) ile POST /v1/templates/{id}/files. En fazla 25 MB. Yanıt dosya kimliğini (tfl_…), sayfa sayısını ve sayfa boyutlarını içerir.
roles, fields, variables (ve file veya content ile birlikte source: "document") ile PUT /v1/templates/{id}/draft. Taslaklar olduğu gibi kaydedilir; henüz hiçbir şey kontrol edilmez.
POST /v1/templates/{id}/publish. Yayımlama taslağı lint kontrolünden geçirir: her alanın rolü vardır, her imzacı rolünün bir imza alanı vardır, alanlar sayfalarına sığar, radio ve dropdown alanlarının seçenekleri vardır, ifadeler ayrıştırılabilir. Sorunlar /fields/3/rect gibi işaretçilerle bir 422 olarak döner.

curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Sürüm uç noktaları bir sayı, latest veya draft kabul eder: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (temel PDF). Hiçbir zarf veya imzalama bağlantısı tarafından kullanılmamış bir şablon silinebilir; aksi hâlde DELETE 409 in-use yanıtı verir.