İçeriğe geç
bona fidedocs

İmzalama oturumları ve bağlantıları

Alıcılar Bona Fide’ın imzalama sayfasında imzalar: ya https://sign.bonafidesign.com/s/… adresindeki barındırılan sayfada ya da aynı sayfanın <bf-signing> ile ürününüze yerleştirilmiş hâlinde. Alıcıların hesaba ihtiyacı yoktur. Onların girişini sağlayan şey bir imzalama oturumudur.

İmzalama oturumları

Bölüm başlığı “İmzalama oturumları”

E-postayla teslimat oturumları sizin için oluşturur (e-postadaki bağlantı). Yerleşik veya kendi teslim ettiğiniz imzalama için arka ucunuzdan bir oturum oluşturun:

Terminal window
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"
}
Alan Notlar
recipient Zarfın hâlâ imzalayabilecek bir alıcısı (CC değil, işlemini bitirmemiş)
mode embedded (varsayılan) veya hosted. Barındırılan url değerleri …/s/<token> biçimindedir; yönlendirmek veya kendiniz göndermek içindir
allowedOrigins Yerleşik sayfayı çerçeveleyebilecek en fazla 10 kaynak
returnUrl İmzacı işini bitirdiğinde barındırılan sayfanın onu gönderdiği yer
ttlSeconds 60 ila 3600, varsayılan 600

Oturumlar tek kullanımlıktır: alıcı gönderim yaptığında oturum tükenir; kullanılmış veya süresi dolmuş bir oturum 410 Gone yanıtı verir. Sayfanız her oluşturulduğunda yeni bir oturum oluşturun. Oturumlar yalnızca zarf sent durumundayken oluşturulabilir ve zarfın iptal edilmesi tüm oturumları sonlandırır.

İmzacının izlediği adımlar

Bölüm başlığı “İmzacının izlediği adımlar”

İmzalama sayfası (ve aynı API üzerine kurduğunuz herhangi bir özel arayüz) şu adımları izler:

  1. Değişim: POST /v1/signing/exchange { "token": "bfs_…" } bellekte tutulan kısa ömürlü bir erişim belirteci (bfa_…) döndürür. Çerez kullanılmaz; bu nedenle bir iframe içinde üçüncü taraf çerezlerinin engellenmesi sorun oluşturmaz.
  2. Yükleme: GET /v1/signing/session imzacı görünümünü (zarf başlığı, gönderen, alıcının rolü ve alanları, ön doldurulmuş değerler, tüketici bilgilendirmesi) döndürür ve ilk seferde recipient.viewed kaydeder. GET /v1/signing/document görüntülenecek PDF’tir.
  3. Doğrulama (yalnızca email_otp ile): POST /v1/signing/otp e-postayla altı haneli bir kod gönderir (10 dakika) ve POST /v1/signing/otp/verify kodu kontrol eder. Yanlış kod, kalan deneme sayısıyla birlikte verified: false döndürür. Alıcının yöntemi kod gerektirmiyorsa görünümün verification.verified değeri zaten true olur.
  4. Gönderme: alan values değerleri (çizilen, yazılan veya yüklenen imzalar), bilgilendirmeye onay ve viewedDocumentHash ile POST /v1/signing/submit: gösterilen PDF’in ta kendisinin SHA-256 değeri. Belge o zamandan beri değiştiyse gönderim reddedilir (409).
  5. Ya da reddetme: POST /v1/signing/decline { "reason": "…" } zarfı sona erdirir (envelope.declined).

Alıcının sırası yalnızca önceki tüm yönlendirme grupları tamamlandığında gelir; o zamana kadar görünümde canSign: false bulunur ve gönderim 409 not-your-turn yanıtı verir.

İmzacı doğrulaması

Bölüm başlığı “İmzacı doğrulaması”

Her alıcının bir verification yöntemi vardır: zarf bunu alıcı bazında geçersiz kılmadıkça (gönderim ekranı veya recipients[].verification) rolün yöntemi (şablon tasarımcısının roller panelinde belirlenir) geçerlidir.

Yöntem İmzacının yaptığı Ne zaman kullanılır
none (varsayılan) Benzersiz imzalama bağlantısını açar ve imzalar Bağlantı kendisine e-postayla gönderilir: yalnızca o gelen kutusuna erişimi olan kişi bağlantıya sahiptir
email_otp Bağlantıyı açar, ardından aynı adrese e-postayla gönderilen altı haneli kodu girer İmzalama anında ikinci, taze bir kanıt istediğinizde (yüksek değerli sözleşmeler, ortak gelen kutuları)
integrator_asserted Kim olduğuna kefil olan ürününüzde imzalar (externalUserId) Kendi girişinizin arkasında yerleşik imzalama

none varsayılandır, çünkü Bona Fide’ın e-postayla gönderdiği bağlantının kendisi alıcıya özgüdür ve tahmin edilemez: bağlantıyı açmak e-posta adresinin kontrolünü gösterir; elektronik imza mevzuatının dayandığı atıf da budur (ABD’de ESIGN / UETA, eIDAS kapsamında basit elektronik imzalar). Benzer ürünler de bunu varsayılan olarak kullanır. email_otp ile yayımlanan şablonlar bu yöntemi korur ve açıkça belirtilen email_otp her yerde çalışmaya devam eder.

İki akış hiçbir zaman yalnızca bağlantıya dayanmaz:

  • Kalıcı imzalama bağlantıları (/l/…): ziyaretçi kendi adresini yazar; bu nedenle şablonda ne yazarsa yazsın, bir zarf oluşturulmadan önce her zaman e-postayla gönderilen bir kodu onaylar.
  • Sizin oluşturduğunuz oturumlar (POST /v1/envelopes/{id}/sessions) e-posta adresine dair hiçbir kanıt taşımaz: bu sizin giriş sisteminizin işidir; bu yüzden onlar için integrator_asserted (externalUserId ile) veya email_otp kullanın.

Tamamlama sertifikası, her imzacı için gerçekte neyin kullanıldığını kaydeder:

Kayıt biçimi Ne zaman
E-posta bağlantısı (adrese gönderilen benzersiz bağlantı) none, e-postayla gönderilen bağlantıdan imzalandı
E-posta bağlantısı + tek kullanımlık kod (adrese gönderildi) email_otp, e-postayla gönderilen bağlantıdan imzalandı
İmzalama bağlantısı + tek kullanımlık kod (adrese gönderildi) Kalıcı bağlantı ziyaretçisi
Tek kullanımlık kod (adrese gönderildi) Sizin oluşturduğunuz bir oturumda email_otp
Gönderen tarafından verilen imzalama oturumu Sizin oluşturduğunuz bir oturumda none
Entegratör beyanı integrator_asserted

Herkese açık doğrulama özeti aynı etiketleri adres olmadan gösterir.

Diller

Bölüm başlığı “Diller”

İmzalama sayfası, e-postaları (talep, hatırlatmalar, kodlar, tamamlandı, iptal edildi), kalıcı bağlantı sayfası ve izleyici durum sayfası 50 dilde kullanılabilir. İmzacı bunları şu tercih sırasına göre görür:

  1. sayfanın dil menüsünden seçtiği dil (o cihazda hatırlanır);
  2. <bf-signing locale="…"> (yerleşik imzalama) veya barındırılan bir bağlantıda ?locale=;
  3. zarf oluşturulurken belirlenen alıcının locale değeri (recipients[].locale veya kendi değeri olmayan herkes için zarf üzerindeki locale);
  4. tarayıcısının dili.

E-postaların, kimse bir sayfayı açmadan önce bir dile ihtiyacı vardır; bu nedenle alıcının locale değerini kullanır, bu değer yoksa İngilizce olur. Kalıcı bağlantılar kod e-postasını ziyaretçinin sayfasında gösterilen dilde gönderir.

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

Yakın etiketler kabul edilir ve eşlendikleri dil olarak saklanır (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); diğer her şey doğrulama hatasıdır. Çevrilmiş onay bilgilendirmeleri İngilizce metnin geçerli olduğunu belirtir ve imzacı İngilizce metne geçebilir; bilgilendirmenin okunduğu dil imzayla birlikte kaydedilir (recipient.signed denetim olayındaki consentLocale).

Kod Dil Yerel adı
ar Arapça العربية sağdan sola
hy Ermenice Հայերեն
bn Bengalce বাংলা
bg Bulgarca Български
zh-Hans Çince (Basitleştirilmiş) 简体中文
zh-Hant Çince (Geleneksel) 繁體中文
hr Hırvatça Hrvatski
cs Çekçe Čeština
da Danca Dansk
nl Felemenkçe Nederlands
en-GB İngilizce (Birleşik Krallık) English (UK)
en-US İngilizce (ABD) English (US)
et Estonca Eesti
fil Filipince Filipino
fi Fince Suomi
fr Fransızca Français
fr-CA Fransızca (Kanada) Français (Canada)
de Almanca Deutsch
el Yunanca Ελληνικά
he İbranice עברית sağdan sola
hi Hintçe हिन्दी
hu Macarca Magyar
id Endonezce Bahasa Indonesia
it İtalyanca Italiano
ja Japonca 日本語
ko Korece 한국어
lv Letonca Latviešu
lt Litvanca Lietuvių
ms Malayca Bahasa Melayu
mr Marathi dili मराठी
nb Norveççe Norsk bokmål
fa Farsça فارسی sağdan sola
pl Lehçe Polski
pt-BR Portekizce (Brezilya) Português (Brasil)
pt-PT Portekizce (Portekiz) Português (Portugal)
ro Rumence Română
ru Rusça Русский
sr-Latn Sırpça (Latin) Srpski
sk Slovakça Slovenčina
sl Slovence Slovenščina
es-419 İspanyolca (Latin Amerika) Español (Latinoamérica)
es-ES İspanyolca (İspanya) Español (España)
sw Svahili dili Kiswahili
sv İsveççe Svenska
te Telugu dili తెలుగు
th Tayca ไทย
tr Türkçe Türkçe
uk Ukraynaca Українська
ur Urduca اردو sağdan sola
vi Vietnamca Tiếng Việt

Kalıcı imzalama bağlantıları

Bölüm başlığı “Kalıcı imzalama bağlantıları”

İmzalama bağlantısı, birçok kişinin aynı şekilde imzaladığı sözleşmeler için kalıcı bir URL’dir: bir feragat beyanı, bir yüklenici sözleşmesi, bir pilot uygulamanın koşulları. Bağlantıyı tamamlayan her ziyaretçi kendi zarfını alır.

Terminal window
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, ziyaretçinin üstlendiği imzacı rolüdür. Bağlantılar bir ziyaretçiyi ve en fazla bir karşı imzacıyı destekler: mode: "auto" Bona Fide platform mührüyle otomatik olarak karşı imza atar, mode: "person" zarfı verilen email adresine yönlendirir. CC olmayan diğer rollerin alıcısı olmayacağından bu tür şablonlar reddedilir.
  • Ziyaretçi adını, e-postasını ve şablonun değişkenlerini girer, ardından herhangi bir şey oluşturulmadan önce bir e-posta kodunu onaylar (POST /v1/links/{id}/start, ardından POST /v1/links/{id}/verify).
  • limits, kullanımı e-posta başına günlük (varsayılan 3), IP başına saatlik (varsayılan 20), toplamda günlük ve e-posta alan adına göre sınırlar. dedupe (varsayılan açık) ile zaten imzalamış bir e-posta adresi 409 already-signed alır.
  • PATCH /v1/signing-links/{id} bağlantıyı duraklatır (active: false), sürdürür veya daha yeni bir sürüme taşır; bir bağlantıyı silmek onun oluşturduğu zarfları korur. Her kullanım signing_link.used olayını yayar.