Sesi & tautan penandatanganan

Penerima menandatangani di halaman penandatanganan Bona Fide: baik halaman yang di-hosting di https://sign.bonafidesign.com/s/…, maupun halaman yang sama yang disematkan di produk Anda dengan <bf-signing>. Penerima tidak memerlukan akun. Yang memberi mereka akses adalah sesi penandatanganan.

Sesi penandatanganan

Pengiriman lewat email membuat sesi untuk Anda (tautan di dalam email). Untuk penandatanganan tersemat atau yang Anda kirimkan sendiri, buat sesi dari backend Anda:

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

Kolom	Catatan
`recipient`	Penerima amplop yang masih dapat menandatangani (bukan CC, belum selesai)
`mode`	`embedded` (default) atau `hosted`. `url` untuk mode hosted berbentuk `…/s/<token>`, untuk dialihkan atau dikirim sendiri
`allowedOrigins`	Hingga 10 origin yang boleh membingkai halaman tersemat
`returnUrl`	Tujuan halaman yang di-hosting mengarahkan penanda tangan setelah selesai
`ttlSeconds`	60 hingga 3600, default 600

Sesi bersifat sekali pakai: setelah penerima mengirimkan, sesi tersebut habis, dan sesi yang sudah dipakai atau kedaluwarsa menjawab 410 Gone. Buat sesi baru setiap kali halaman Anda dirender. Sesi hanya dapat dibuat selama amplop berstatus sent, dan membatalkan amplop akan mengakhiri semuanya.

Langkah-langkah yang dilalui penanda tangan

Halaman penandatanganan (dan UI kustom apa pun yang Anda bangun di atas API yang sama) mengikuti langkah-langkah berikut:

Penukaran: POST /v1/signing/exchange { "token": "bfs_…" } mengembalikan token akses berumur pendek (bfa_…) yang disimpan di memori. Tidak ada cookie yang terlibat, sehingga pemblokiran cookie pihak ketiga tidak berpengaruh di dalam iframe.
Memuat: GET /v1/signing/session mengembalikan tampilan penanda tangan (judul amplop, pengirim, peran dan kolom penerima, nilai yang sudah diisi sebelumnya, pengungkapan konsumen) dan mencatat recipient.viewed pada kali pertama. GET /v1/signing/document adalah PDF yang ditampilkan.
Verifikasi (hanya dengan email_otp): POST /v1/signing/otp mengirim kode enam digit lewat email (berlaku 10 menit) dan POST /v1/signing/otp/verify memeriksanya. Kode yang salah mengembalikan verified: false beserta sisa percobaan. verification.verified pada tampilan sudah bernilai true jika metode penerima tidak memerlukan kode.
Kirim: POST /v1/signing/submit dengan values kolom (tanda tangan yang digambar, diketik, atau diunggah), persetujuan atas pengungkapan, dan viewedDocumentHash: SHA-256 dari PDF persis yang ditampilkan. Jika dokumen telah berubah sejak itu, pengiriman ditolak (409).
Atau tolak: POST /v1/signing/decline { "reason": "…" } mengakhiri amplop (envelope.declined).

Giliran penerima baru tiba setelah setiap grup perutean sebelumnya selesai; sebelum itu, tampilan memiliki canSign: false, dan pengiriman menjawab 409 not-your-turn.

Verifikasi penanda tangan

Setiap penerima memiliki metode verification: metode milik peran (ditetapkan di panel peran pada desainer template), kecuali amplop menggantinya per penerima (layar kirim, atau recipients[].verification).

Metode	Yang dilakukan penanda tangan	Gunakan saat
`none` (default)	Membuka tautan penandatanganan unik lalu menandatangani	Tautan dikirim lewat email kepadanya: hanya orang yang memiliki akses ke kotak masuk itu yang memilikinya
`email_otp`	Membuka tautan, lalu memasukkan kode enam digit yang dikirim ke alamat yang sama	Anda menginginkan bukti kedua yang baru pada saat penandatanganan (kontrak bernilai tinggi, kotak masuk bersama)
`integrator_asserted`	Menandatangani di produk Anda, yang menjamin identitasnya (`externalUserId`)	Penandatanganan tersemat di balik login Anda sendiri

none menjadi default karena tautan yang dikirim Bona Fide lewat email itu sendiri unik bagi penerima dan tidak dapat ditebak: membukanya menunjukkan penguasaan atas alamat email, yaitu atribusi yang menjadi dasar undang-undang tanda tangan elektronik (ESIGN / UETA di AS, tanda tangan elektronik sederhana berdasarkan eIDAS). Produk sejenis juga menjadikannya default. Template yang dipublikasikan dengan email_otp tetap memakainya, dan email_otp yang ditetapkan secara eksplisit tetap berfungsi di mana pun.

Dua alur tidak pernah mengandalkan tautan saja:

Tautan penandatanganan yang selalu aktif (/l/…): pengunjung mengetik alamatnya sendiri, sehingga ia selalu mengonfirmasi kode yang dikirim lewat email sebelum amplop dibuat, apa pun pengaturan template.
Sesi yang Anda buat (POST /v1/envelopes/{id}/sessions) sama sekali tidak membawa bukti alamat email: itu tugas sistem login Anda, jadi gunakan integrator_asserted (dengan externalUserId) atau email_otp untuk sesi tersebut.

Sertifikat penyelesaian mencatat, untuk setiap penanda tangan, apa yang benar-benar digunakan:

Dicatat sebagai	Kapan
Tautan email (tautan unik dikirim ke alamat)	`none`, ditandatangani dari tautan email
Tautan email + kode sekali pakai (dikirim ke alamat)	`email_otp`, ditandatangani dari tautan email
Tautan penandatanganan + kode sekali pakai (dikirim ke alamat)	Pengunjung tautan yang selalu aktif
Kode sekali pakai (dikirim ke alamat)	`email_otp` dalam sesi yang Anda buat
Sesi penandatanganan yang diterbitkan oleh pengirim	`none` dalam sesi yang Anda buat
Pernyataan integrator	`integrator_asserted`

Ringkasan verifikasi publik menampilkan label yang sama tanpa alamat.

Bahasa

Halaman penandatanganan, email-emailnya (permintaan, pengingat, kode, selesai, dibatalkan), halaman tautan yang selalu aktif, dan halaman status pemantau tersedia dalam 50 bahasa. Penanda tangan melihatnya berdasarkan urutan preferensi berikut:

bahasa yang ia pilih dari menu bahasa halaman (diingat di perangkat tersebut);
<bf-signing locale="…"> (penandatanganan tersemat) atau ?locale= pada tautan yang di-hosting;
locale penerima, yang ditetapkan saat amplop dibuat (recipients[].locale, atau locale pada amplop untuk semua orang yang tidak memiliki nilainya sendiri);
bahasa browser-nya.

Email memerlukan bahasa sebelum ada yang membuka halaman, sehingga email menggunakan locale penerima dan berbahasa Inggris jika tidak ada. Tautan yang selalu aktif mengirim email kode dalam bahasa yang ditampilkan di halaman pengunjung.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

Tag yang mirip diterima dan disimpan sebagai bahasa yang dipetakannya (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); selain itu menghasilkan error validasi. Pengungkapan persetujuan yang diterjemahkan menyatakan bahwa teks bahasa Inggris yang berlaku, dan penanda tangan dapat beralih ke teks tersebut; bahasa yang digunakan saat membaca pengungkapan dicatat bersama tanda tangan (consentLocale dalam event audit recipient.signed).

Kode	Bahasa	Nama asli
`ar`	Arab	العربية	kanan-ke-kiri
`hy`	Armenia	Հայերեն
`bn`	Bengali	বাংলা
`bg`	Bulgaria	Български
`zh-Hans`	Tionghoa (Sederhana)	简体中文
`zh-Hant`	Tionghoa (Tradisional)	繁體中文
`hr`	Kroasia	Hrvatski
`cs`	Ceko	Čeština
`da`	Denmark	Dansk
`nl`	Belanda	Nederlands
`en-GB`	Inggris (Britania Raya)	English (UK)
`en-US`	Inggris (AS)	English (US)
`et`	Estonia	Eesti
`fil`	Filipino	Filipino
`fi`	Finlandia	Suomi
`fr`	Prancis	Français
`fr-CA`	Prancis (Kanada)	Français (Canada)
`de`	Jerman	Deutsch
`el`	Yunani	Ελληνικά
`he`	Ibrani	עברית	kanan-ke-kiri
`hi`	Hindi	हिन्दी
`hu`	Hungaria	Magyar
`id`	Indonesia	Bahasa Indonesia
`it`	Italia	Italiano
`ja`	Jepang	日本語
`ko`	Korea	한국어
`lv`	Latvia	Latviešu
`lt`	Lituania	Lietuvių
`ms`	Melayu	Bahasa Melayu
`mr`	Marathi	मराठी
`nb`	Norwegia	Norsk bokmål
`fa`	Persia (Farsi)	فارسی	kanan-ke-kiri
`pl`	Polandia	Polski
`pt-BR`	Portugis (Brasil)	Português (Brasil)
`pt-PT`	Portugis (Portugal)	Português (Portugal)
`ro`	Rumania	Română
`ru`	Rusia	Русский
`sr-Latn`	Serbia (Latin)	Srpski
`sk`	Slowakia	Slovenčina
`sl`	Slovenia	Slovenščina
`es-419`	Spanyol (Amerika Latin)	Español (Latinoamérica)
`es-ES`	Spanyol (Spanyol)	Español (España)
`sw`	Swahili	Kiswahili
`sv`	Swedia	Svenska
`te`	Telugu	తెలుగు
`th`	Thai	ไทย
`tr`	Turki	Türkçe
`uk`	Ukraina	Українська
`ur`	Urdu	اردو	kanan-ke-kiri
`vi`	Vietnam	Tiếng Việt

Tautan penandatanganan yang selalu aktif

Tautan penandatanganan adalah URL permanen untuk kontrak yang ditandatangani banyak orang dengan cara yang sama: surat pelepasan tanggung jawab, perjanjian kontraktor, ketentuan untuk program percontohan. Setiap pengunjung yang menyelesaikannya mendapat amplopnya sendiri.

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

visitorRole adalah peran penanda tangan yang diambil pengunjung. Tautan mendukung satu pengunjung dan paling banyak satu penanda tangan pendamping: mode: "auto" menandatangani pendamping secara otomatis dengan segel platform Bona Fide, mode: "person" merutekan amplop ke email yang diberikan. Peran non-CC lainnya tidak akan memiliki penerima, sehingga template seperti itu ditolak.
Pengunjung memasukkan nama, email, dan variabel template, lalu mengonfirmasi kode email sebelum apa pun dibuat (POST /v1/links/{id}/start, lalu POST /v1/links/{id}/verify).
limits membatasi pemakaian per email per hari (default 3), per IP per jam (default 20), per hari secara keseluruhan, dan berdasarkan domain email. Dengan dedupe (default aktif), alamat email yang sudah menandatangani mendapat 409 already-signed.
PATCH /v1/signing-links/{id} menjeda (active: false), melanjutkan, atau memindahkan tautan ke versi yang lebih baru; menghapus tautan tetap mempertahankan amplop yang telah dibuatnya. Setiap pemakaian memancarkan signing_link.used.