דלגו לתוכן
bona fidedocs

סשנים וקישורים לחתימה

נמענים חותמים בדף החתימה של Bona Fide: או בדף המאוחסן בכתובת https://sign.bonafidesign.com/s/…, או באותו דף כשהוא מוטמע במוצר שלכם באמצעות <bf-signing>. הנמענים אינם צריכים חשבון. מה שמכניס אותם הוא סשן חתימה.

סשני חתימה

Section titled “סשני חתימה”

מסירה באימייל יוצרת עבורכם סשנים (הקישור שבאימייל). לחתימה מוטמעת או למסירה עצמית, יוצרים סשן מהשרת שלכם:

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"
}
שדה הערות
recipient נמען של המעטפה שעדיין יכול לחתום (לא CC, ולא סיים)
mode embedded (ברירת מחדל) או hosted. כתובות url מאוחסנות הן בצורה …/s/<token>, להפניה אליהן או לשליחה בעצמכם
allowedOrigins עד 10 מקורות (origins) שרשאים להציג את הדף המוטמע בתוך frame
returnUrl לאן הדף המאוחסן שולח את החותם כשהוא מסיים
ttlSeconds 60 עד 3600, ברירת מחדל 600

הסשנים הם לשימוש חד-פעמי: ברגע שהנמען שולח, הסשן מנוצל, וסשן שנוצל או שתוקפו פג עונה 410 Gone. יוצרים סשן חדש בכל פעם שהדף שלכם מרונדר. אפשר ליצור סשנים רק כשהמעטפה במצב sent, וביטול המעטפה מסיים את כולם.

מה החותם עובר

Section titled “מה החותם עובר”

דף החתימה (וכל ממשק מותאם שתבנו על אותו API) עובר את השלבים האלה:

  1. החלפה: POST /v1/signing/exchange { "token": "bfs_…" } מחזיר טוקן גישה קצר חיים (bfa_…) שנשמר בזיכרון. אין שימוש בקובצי cookie, כך שחסימת cookies של צד שלישי לא משנה בתוך iframe.
  2. טעינה: GET /v1/signing/session מחזיר את תצוגת החותם (כותרת המעטפה, השולח, התפקיד והשדות של הנמען, ערכים שמולאו מראש, הגילוי הנאות לצרכן) ומתעד recipient.viewed בפעם הראשונה. GET /v1/signing/document הוא ה-PDF להצגה.
  3. אימות (רק עם email_otp): POST /v1/signing/otp שולח באימייל קוד בן שש ספרות (תקף 10 דקות) ו-POST /v1/signing/otp/verify בודק אותו. קוד שגוי מחזיר verified: false עם מספר הניסיונות שנותרו. בתצוגה, verification.verified כבר true כשהשיטה של הנמען אינה דורשת קוד.
  4. שליחה: POST /v1/signing/submit עם values של השדות (חתימות מצוירות, מוקלדות או מועלות), הסכמה לגילוי הנאות, ו-viewedDocumentHash: ה-SHA-256 של ה-PDF המדויק שהוצג. אם המסמך השתנה מאז, השליחה נדחית (409).
  5. או סירוב: POST /v1/signing/decline { "reason": "…" } מסיים את המעטפה (envelope.declined).

תורו של הנמען מגיע רק כשכל קבוצות הניתוב הקודמות הסתיימו; לפני כן התצוגה כוללת canSign: false, ושליחה עונה 409 not-your-turn.

אימות החותם

Section titled “אימות החותם”

לכל נמען יש שיטת verification: זו של התפקיד (שנקבעת בחלונית התפקידים בעורך התבניות), אלא אם המעטפה גוברת עליה לכל נמען (מסך השליחה, או recipients[].verification).

שיטה מה החותם עושה מתי להשתמש בה
none (ברירת מחדל) פותח את קישור החתימה הייחודי וחותם הקישור נשלח אליו באימייל: רק למי שיש גישה לתיבת הדואר הזו יש אותו
email_otp פותח את הקישור, ואז מזין קוד בן שש ספרות שנשלח באימייל לאותה כתובת רוצים הוכחה שנייה ועדכנית ברגע החתימה (חוזים בעלי ערך גבוה, תיבות דואר משותפות)
integrator_asserted חותם במוצר שלכם, שמעיד על זהותו (externalUserId) חתימה מוטמעת מאחורי מערכת הכניסה שלכם

none היא ברירת המחדל כי הקישור ש-Bona Fide שולחת באימייל הוא עצמו ייחודי לנמען ואי אפשר לנחש אותו: פתיחתו מראה שליטה בכתובת האימייל, וזה הייחוס שעליו מסתמכים חוקי החתימה האלקטרונית (ESIGN / UETA בארצות הברית, חתימות אלקטרוניות פשוטות לפי eIDAS). גם מוצרים דומים משתמשים בה כברירת מחדל. תבניות שפורסמו עם email_otp שומרות עליה, ו-email_otp שהוגדר במפורש ממשיך לפעול בכל מקום.

יש שני תהליכים שלעולם אינם מסתמכים על קישור בלבד:

  • קישורי חתימה קבועים (/l/…): המבקר מקליד את הכתובת שלו בעצמו, ולכן תמיד מאשר קוד שנשלח באימייל לפני שנוצרת מעטפה, בלי קשר למה שהתבנית קובעת.
  • סשנים שאתם יוצרים (POST /v1/envelopes/{id}/sessions) אינם נושאים שום הוכחה לכתובת האימייל: זה התפקיד של מערכת הכניסה שלכם, לכן יש להשתמש עבורם ב-integrator_asserted (עם externalUserId) או ב-email_otp.

אישור ההשלמה מתעד, לכל חותם, במה נעשה שימוש בפועל:

מתועד בתור מתי
קישור באימייל (קישור ייחודי שנשלח אל כתובת) none, נחתם מהקישור שנשלח באימייל
קישור באימייל + קוד חד-פעמי (נשלח אל כתובת) email_otp, נחתם מהקישור שנשלח באימייל
קישור חתימה + קוד חד-פעמי (נשלח אל כתובת) מבקר בקישור קבוע
קוד חד-פעמי (נשלח אל כתובת) email_otp בסשן שאתם יצרתם
סשן חתימה שהונפק על ידי השולח none בסשן שאתם יצרתם
הצהרת המשלב (integrator) integrator_asserted

סיכום האימות הציבורי מציג את אותן תוויות בלי הכתובת.

שפות

Section titled “שפות”

דף החתימה, האימיילים שלו (בקשה, תזכורות, קודים, השלמה, ביטול), דף הקישור הקבוע ודף הסטטוס של הצופה זמינים ב-50 שפות. החותם רואה אותם לפי סדר העדיפות הזה:

  1. השפה שבחר בתפריט השפות של הדף (נשמרת במכשיר הזה);
  2. <bf-signing locale="…"> (חתימה מוטמעת) או ?locale= בקישור מאוחסן;
  3. ה-locale של הנמען, שנקבע ביצירת המעטפה (recipients[].locale, או locale במעטפה עבור כל מי שאין לו ערך משלו);
  4. שפת הדפדפן שלו.

אימיילים צריכים שפה לפני שמישהו פותח דף, לכן הם משתמשים ב-locale של הנמען ונשלחים באנגלית בלעדיו. קישורים קבועים שולחים את אימייל הקוד בשפה שבה מוצג הדף של המבקר.

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

תגיות קרובות מתקבלות ונשמרות כשפה שאליה הן ממופות (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); כל ערך אחר הוא שגיאת אימות. גילויים נאותים מתורגמים לגבי ההסכמה מציינים שהנוסח האנגלי הוא הקובע, והחותם יכול לעבור אליו; השפה שבה נקרא הגילוי הנאות נרשמת עם החתימה (consentLocale באירוע הביקורת recipient.signed).

קוד שפה שם מקורי
ar ערבית العربية מימין לשמאל
hy ארמנית Հայերեն
bn בנגלית বাংলা
bg בולגרית Български
zh-Hans סינית (מפושטת) 简体中文
zh-Hant סינית (מסורתית) 繁體中文
hr קרואטית Hrvatski
cs צ’כית Čeština
da דנית Dansk
nl הולנדית Nederlands
en-GB אנגלית (בריטניה) English (UK)
en-US אנגלית (ארצות הברית) English (US)
et אסטונית Eesti
fil פיליפינית Filipino
fi פינית Suomi
fr צרפתית Français
fr-CA צרפתית (קנדה) Français (Canada)
de גרמנית Deutsch
el יוונית Ελληνικά
he עברית עברית מימין לשמאל
hi הינדי हिन्दी
hu הונגרית Magyar
id אינדונזית Bahasa Indonesia
it איטלקית Italiano
ja יפנית 日本語
ko קוריאנית 한국어
lv לטבית Latviešu
lt ליטאית Lietuvių
ms מלאית Bahasa Melayu
mr מראטהי मराठी
nb נורווגית Norsk bokmål
fa פרסית (פארסי) فارسی מימין לשמאל
pl פולנית Polski
pt-BR פורטוגזית (ברזיל) Português (Brasil)
pt-PT פורטוגזית (פורטוגל) Português (Portugal)
ro רומנית Română
ru רוסית Русский
sr-Latn סרבית (לטינית) Srpski
sk סלובקית Slovenčina
sl סלובנית Slovenščina
es-419 ספרדית (אמריקה הלטינית) Español (Latinoamérica)
es-ES ספרדית (ספרד) Español (España)
sw סווהילי Kiswahili
sv שוודית Svenska
te טלוגו తెలుగు
th תאית ไทย
tr טורקית Türkçe
uk אוקראינית Українська
ur אורדו اردو מימין לשמאל
vi וייטנאמית Tiếng Việt

קישורי חתימה קבועים

Section titled “קישורי חתימה קבועים”

קישור חתימה הוא כתובת URL קבועה לחוזים שאנשים רבים חותמים עליהם באותו אופן: כתב ויתור, הסכם קבלן, תנאים לפיילוט. כל מבקר שמשלים אותו מקבל מעטפה משלו.

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 הוא תפקיד החותם שהמבקר מקבל. קישורים תומכים במבקר אחד ולכל היותר חותם נגדי אחד: mode: "auto" חותם חתימה נגדית אוטומטית עם החותמת של פלטפורמת Bona Fide, mode: "person" מנתב את המעטפה אל ה-email שצוין. לכל תפקיד אחר שאינו CC לא יהיה נמען, ולכן תבניות כאלה נדחות.
  • המבקר מזין את שמו, את האימייל שלו ואת המשתנים של התבנית, ואז מאשר קוד שנשלח באימייל לפני שמשהו נוצר (POST /v1/links/{id}/start, ואז POST /v1/links/{id}/verify).
  • limits מגביל את השימוש לפי אימייל ליום (ברירת מחדל 3), לפי IP לשעה (ברירת מחדל 20), ליום בסך הכול, ולפי דומיין האימייל. עם dedupe (פעיל כברירת מחדל), כתובת אימייל שכבר חתמה מקבלת 409 already-signed.
  • PATCH /v1/signing-links/{id} משהה (active: false), ממשיך או מעביר את הקישור לגרסה חדשה יותר; מחיקת קישור שומרת את המעטפות שהוא יצר. כל שימוש פולט signing_link.used.