Template, peran & kolom

Template adalah kontrak yang dapat digunakan ulang. Template memiliki nama, satu draf, dan sejumlah versi yang dipublikasikan. Amplop selalu dibuat dari versi yang dipublikasikan, yang tidak dapat diubah: mengedit template berarti menyimpan draf baru dan memublikasikannya sebagai versi berikutnya. Amplop yang sudah dikirim tetap memakai versi yang disematkannya.

GET /v1/templates/tpl_…

{
  "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"
}

Id berupa string berprefiks (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); stempel waktu berformat RFC 3339 dalam UTC.

Dua cara menyusun

Mode Overlay (source: "pdf") dimulai dari dokumen yang diunggah. Kolom adalah persegi panjang yang ditempatkan pada halaman-halamannya dalam satuan poin PDF (1/72 inci), dengan titik asal di kiri atas halaman dan indeks halaman mulai dari 0. Unggahan .docx dikonversi ke PDF satu kali (dengan LibreOffice, mempertahankan tata letak Word; font yang tidak disematkan dalam file mungkin diganti), dan sejak itu menjadi PDF seperti lainnya: file melaporkan convertedFrom: "docx". Versi Overlay juga dapat membawa edit konten (teks yang diedit di tempat, white-out, kotak teks, gambar, operasi halaman) yang diterapkan saat versi dipublikasikan.

Mode Dokumen (source: "document") menyimpan kontrak itu sendiri sebagai rich text (ProseMirror JSON) dengan chip variabel seperti {{client.name}}, blok kolom inline, bagian bersyarat (dipertahankan hanya jika ekspresi showIf bernilai benar), serta bagian dan baris tabel yang berulang (satu per item variabel array). Setiap amplop merender PDF-nya sendiri, dan posisi kolom dibaca dari hasil render tersebut. Di dasbor, mode Dokumen adalah “Mulai dari dokumen kosong”. Melalui API, file Word juga dapat diimpor ke mode Dokumen dengan POST /v1/templates/{id}/import: {{tags}} menjadi variabel atau kolom, dan baris tanda tangan (“Signature: ____”, “By: ____”, “Date: ____”) menjadi blok kolom.

Di dasbor

Template baru menawarkan dua cara memulai:

• Unggah dokumen: satu area letak untuk file .pdf dan .docx hingga 25 MB. File Word dikonversi ke PDF dan dibuka di desainer dengan pengingat untuk memeriksa tata letak hasil konversi sebelum menempatkan kolom. Perbaikan kecil dilakukan langsung pada PDF (“Edit konten”); untuk penulisan ulang yang lebih besar, ubah file Word lalu unggah lagi.
• Mulai dari dokumen kosong: tulis kontrak dalam mode Dokumen.

Edit konten

Mode Edit konten di desainer mengubah apa yang dilihat penanda tangan tanpa menyentuh file yang diunggah. Alat defaultnya, Edit teks, menyorot blok teks di halaman (baris dan paragraf yang dikelompokkan dari lapisan teks PDF); klik salah satunya, atau gunakan Tab untuk menujunya lalu tekan Enter, untuk mengeditnya di tempat dengan posisi, ukuran, warna, perataan, dan font yang sama. Ctrl/Cmd+Enter menyimpan, Esc membatalkan, dan setiap edit dapat dikembalikan dari daftar edit. Edit dapat di-undo seperti perubahan lainnya. Alat lainnya menambahkan white-out, kotak teks, dan gambar, serta menyisipkan, menghapus, mengurutkan ulang, atau memutar halaman.

Edit teks di tempat disimpan sebagai dua item yang berbagi group: white-out di atas blok asli (dalam warna latar halaman) dan item teks yang ditata di dalam blok, dengan tinggi baris dan baseline pertama milik blok tersebut:

edits.items (excerpt)

[
  { "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 memilih font: font tersemat PDF jika dapat menggambar setiap karakter teks baru, jika tidak, font bawaan yang kompatibel secara metrik (sans Arimo untuk Helvetica/Arial, serif Tinos untuk Times, mono Cousine untuk Courier, carlito Carlito untuk Calibri) dengan ketebalan dan gaya yang sesuai. Teks dibungkus di dalam blok; jika memerlukan lebih banyak baris daripada aslinya, edit akan membesar ke ruang kosong di bawahnya, dan desainer menolak menyimpannya jika tidak ada ruang (“teks tidak muat — persingkat atau tambahkan ruang”). Desainer dan API berbagi kode tata letak dan font, sehingga PDF yang dipublikasikan sama dengan pratinjau baris demi baris.

Edit hanya dapat mengubah draf. Publikasi menerapkannya ke PDF dasar baru yang SHA-256-nya menjadi documentHash versi tersebut (hash dari apa yang dilihat penanda tangan); file asli yang diunggah disimpan sebagai sourceFile versi, dan draf berikutnya dimulai dari file itu dengan edit yang sama. White-out menutupi konten secara visual; teks asli tetap ada di dalam file di bawahnya, sehingga ini bukan redaksi yang aman.

Peran

Peran adalah para pihak dalam kontrak. Penerima amplop dicocokkan dengan peran berdasarkan key.

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

Properti	Arti
key	Pengenal huruf kecil (^[a-z][a-z0-9_]*$) yang dipakai oleh kolom dan oleh penerima amplop
kind	signer (harus memiliki kolom tanda tangan atau paraf), approver, form_filler, atau cc (menerima, tidak pernah menandatangani)
order	Urutan perutean mulai dari 1. Peran dengan urutan yang sama menandatangani secara paralel; urutan berikutnya dimulai setelah mereka selesai
verification	Cara penerima peran membuktikan identitasnya: none (default: hanya tautan penandatanganan unik) atau email_otp (tautan ditambah kode yang dikirim lewat email). Penerima dapat menggantinya; lihat verifikasi penanda tangan

passkey, id_check, dan sms_otp muncul di skema tetapi belum tersedia untuk penandatanganan: template yang menggunakan passkey atau id_check tidak dapat dipublikasikan, dan kode SMS belum dikirimkan.

Kolom

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

Jenis kolom: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp, dan variable_text (diisi dari variabel oleh pengirim, bukan oleh penanda tangan). Kolom juga dapat memiliki:

• variable: JSON Pointer ke dalam variabel (/client/name) untuk mengikat atau mengisi kolom sebelumnya;
• options untuk radio dan dropdown;
• validation: pattern, min, max, maxLength, atau format (email, phone, date, number, currency);
• showIf: kondisi atas variabel dan kolom lain, seperti plan != "free";
• formula: nilai terhitung yang hanya-baca;
• overflow: apa yang dilakukan saat nilai tidak muat di kotak: shrink (default), wrap, atau reject.

Variabel

variables sebuah versi adalah JSON Schema (draft 2020-12) untuk data yang Anda kirim bersama setiap amplop; sampleVariables versi tersebut adalah contohnya. POST /v1/envelopes memvalidasi variables Anda terhadap skema ini dan melaporkan setiap masalah dengan JSON Pointer:

{
  "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'." }
  ]
}

Untuk melihat hasilnya sebelum mengirim, render pratinjau bertanda air dari versi mana pun dengan POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF), atau buat amplop dengan ?dry_run=true.

Membangun template dengan API

Sebagian besar tim merancang template di desainer dasbor. Semua yang dapat dilakukan desainer juga tersedia melalui API:

1. POST /v1/templates dengan { "name": "Mutual NDA" }.
2. POST /v1/templates/{id}/files dengan PDF (atau .docx) sebagai body (Content-Type: application/pdf) atau sebagai kolom multipart file. Hingga 25 MB. Responsnya berisi id file (tfl_…), jumlah halaman, dan ukuran halaman.
3. PUT /v1/templates/{id}/draft dengan roles, fields, variables (dan file, atau source: "document" dengan content). Draf disimpan apa adanya; belum ada yang diperiksa.
4. POST /v1/templates/{id}/publish. Publikasi menjalankan lint pada draf: peran setiap kolom ada, setiap peran penanda tangan memiliki kolom tanda tangan, kolom muat di halamannya, kolom radio dan dropdown memiliki opsi, ekspresi dapat di-parse. Masalah dikembalikan sebagai 422 dengan pointer seperti /fields/3/rect.

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

Endpoint versi menerima angka, latest, atau draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (PDF dasar). Template yang belum pernah dipakai oleh amplop atau tautan penandatanganan dapat dihapus; jika sudah, DELETE menjawab 409 in-use.