חתימה מוטמעת

<bf-signing> מרנדר את דף החתימה של Bona Fide בתוך iframe מבודד (sandbox) בדף שלכם, מתאים את גודלו למסמך, ומדווח על מה שהחותם עושה כאירועי DOM. הוא אינו תלוי בשום framework; עטיפות דקות ל-React ול-Vue כלולות.

1. יוצרים את המעטפה עם delivery: "embedded", כדי שהנמענים לא יקבלו אימייל.

2. יוצרים סשן בשרת שלכם כשהחותם פותח את הדף, עם המקור (origin) של האתר שלכם ב-allowedOrigins. הדף המוטמע מסרב לתקשר עם כל דף אב שאינו מופיע שם.

   // Your backend (never expose the API key to the browser)
   const res = await fetch(`https://api.bonafidesign.com/v1/envelopes/${envelopeId}/sessions`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ recipient: recipientId, mode: 'embedded', allowedOrigins: ['https://app.example.com'] }),
   });
   const { token } = await res.json(); // 'bfs_…', single-use, 10 minutes by default

3. מרנדרים את הרכיב עם הטוקן.

   HTML

   <script type="module" src="https://js.bonafidesign.com/v1"></script>
   
   <bf-signing session="bfs_…" theme="auto" min-height="480" max-height="90vh"></bf-signing>
   
   <script>
     const el = document.querySelector('bf-signing');
     el.addEventListener('completed', (e) => {
       // e.detail = { type: 'completed', envelope: 'env_…' }
       window.location.href = '/onboarding/next';
     });
     el.addEventListener('session_expiring', () => refreshSession());
     el.addEventListener('error', (e) => console.error(e.detail.code, e.detail.message));
   </script>

   React

   import { BonaFideSigning } from '@bona-fide/embed/react';
   
   export function SignContract({ token }: { token: string }) {
     return (
       <BonaFideSigning
         session={token}
         theme="auto"
         minHeight={480}
         maxHeight="90vh"
         onCompleted={(e) => console.log('envelope completed', e.envelope)}
         onDeclined={(e) => console.log('declined', e.reason)}
         onSessionExpiring={() => refreshSession()}
         onError={(e) => console.error(e.code, e.message)}
       />
     );
   }

   Vue

   <script setup lang="ts">
   import { BonaFideSigning } from '@bona-fide/embed/vue';
   defineProps<{ token: string }>();
   const done = (e: { envelope: string }) => console.log('envelope completed', e.envelope);
   </script>
   
   <template>
     <BonaFideSigning :session="token" theme="auto" :min-height="480" max-height="90vh" @completed="done" />
   </template>

4. מאשרים בשרת שלכם. יש להתייחס לאירוע בדפדפן כאות לממשק בלבד ולהסתמך על ה-webhook envelope.completed (או על GET /v1/envelopes/{id}) לגבי התוצאה.

מאפיינים

מאפיין (prop ב-React / Vue)	ברירת מחדל	הערות
session		הטוקן bfs_…. שינוי שלו טוען מחדש את ה-frame
base-url (baseUrl)	https://sign.bonafidesign.com/s/	נתיב החתימה המאוחסן של הפריסה
theme	auto	auto, light או dark
locale		מועבר לדף החתימה
min-height, max-height (minHeight, maxHeight)	480, 90vh	פיקסלים או vh. ה-frame גדל עם המסמך בין שני הערכים, ואז נגלל מבפנים
timeout	30000	מספר אלפיות השנייה להמתנה לדף לפני error עם הקוד load_timeout
frame-title	Document signing	הכותרת הנגישה של ה-iframe

לרכיב יש גם מתודה reload(), למשל אחרי יצירת סשן חדש.

אירועים

האירועים מבעבעים (bubble), חוצים shadow roots ונושאים את המטען ב-event.detail. האירוע bf-event נורה עבור כולם.

אירוע	detail
ready	{ type: 'ready' }: דף החתימה נטען
field_completed	{ type, field }: שדה מולא
signed	{ type, recipient }: הנמען הזה שלח
completed	{ type, envelope }: המעטפה הושלמה
declined	{ type, reason? }
session_expiring	{ type, expiresAt }: יש ליצור סשן חדש בקרוב
error	{ type, code, message }, כולל load_timeout ו-invalid_base_url

ה-props של React הם onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError ו-onEvent; ב-Vue נפלטים שמות האירועים (@completed, @session_expiring, …) ו-event.

מודל האבטחה

• הטוקן עובר במקטע ה-fragment של כתובת ה-URL של ה-iframe (#session=…), שלעולם אינו מגיע לשרת או לכותרת Referer. דף החתימה קורא אותו, מסיר אותו מכתובת ה-URL ומההיסטוריה, ומחליף אותו בטוקן גישה שנשמר בזיכרון. אין שימוש בקובצי cookie.
• ה-iframe מבודד (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) עם referrerpolicy="strict-origin".
• הדף שלכם מקבל הודעה רק כשהיא מגיעה מה-iframe של הרכיב עצמו וגם מהמקור של base-url וגם מתפרשת כהודעת bona-fide.embed/1 במרחב השמות. כל השאר מתעלמים ממנו.
• דף החתימה שולח הודעות למקור המדויק שלכם (לעולם לא *), ורק אם המקור הזה נמצא ב-allowedOrigins של הסשן. גם ה-API דוחה קריאות של סשן מוטמע ממקורות שאינם מורשים.

ובמקום זאת: מאוחסן

אם אתם מעדיפים לא להטמיע, יוצרים את הסשן עם "mode": "hosted" ומפנים ל-url שלו; מגדירים returnUrl כדי להחזיר את החותם אליכם. ראו סשני חתימה.

Note

כתובת ה-URL של הסקריפט שלמעלה היא זו שקטע קוד ההטמעה בלוח הבקרה משתמש בה. הרכיב והעטיפות שלו מגיעים מחבילה אחת, @bona-fide/embed: נקודת הכניסה הראשית רושמת את <bf-signing>, ו-@bona-fide/embed/react ו-@bona-fide/embed/vue מייצאים את BonaFideSigning.