התחלה מהירה

המדריך הזה לוקח תבנית שפורסמה עד ל-PDF חתום ונעול. הוא משתמש במפתח בדיקה, כך ששום דבר לא מחויב וכל מסמך מקבל את סימן המים TEST.

1. יצירת מפתח API

   מפתחות API נוצרים בלוח הבקרה, תחת הגדרות › מפתחות API. בוחרים Test עבור המדריך הזה: המפתח מתחיל ב-bf_test_. המפתח המלא מוצג פעם אחת בלבד; יש לשמור אותו כמשתנה סביבה.

   export BONA_FIDE_API_KEY=bf_test_…

   כל בקשה שולחת אותו בתור Authorization: Bearer … (או x-api-key: …). ראו הזדהות.

2. איתור התבנית

   תבניות מעוצבות בלוח הבקרה (מעלים PDF או מסמך Word וממקמים שדות, או כותבים אותה במצב מסמך) ואז מתפרסמות. כדי לקבל את המזהה, מציגים את רשימת התבניות:

   curl

   curl https://api.bonafidesign.com/v1/templates \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY"

   TypeScript

   const res = await fetch('https://api.bonafidesign.com/v1/templates', {
     headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}` },
   });
   const { data } = await res.json(); // [{ id: 'tpl_…', name: 'Mutual NDA', latestVersion: 3, … }]

   Python

   import os, requests
   
   API = "https://api.bonafidesign.com"
   headers = {"Authorization": f"Bearer {os.environ['BONA_FIDE_API_KEY']}"}
   
   templates = requests.get(f"{API}/v1/templates", headers=headers).json()["data"]

   הקריאה GET /v1/templates/{id}/versions/latest מחזירה את roles ואת fields של הגרסה ואת ה-JSON Schema של variables. בדף התבנית בלוח הבקרה יש גם חלונית Use in API עם בקשה מוכנה לגרסה המדויקת הזו.

3. יצירת מעטפה

   הקריאה POST /v1/envelopes מרנדרת את התבנית עם המשתנים שלכם, מקבעת את הגרסה ומתחילה בניתוב. יש לתת נמען אחד לכל תפקיד (תפקידי CC הם אופציונליים). שולחים Idempotency-Key כדי שניסיון חוזר לא ישלח פעמיים.

   curl

   curl https://api.bonafidesign.com/v1/envelopes \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: onboarding-8841" \
     -d '{
       "template": "tpl_…",
       "version": "latest",
       "variables": {
         "client": { "name": "Acme Robotics, Inc." },
         "effective_date": "2026-10-13"
       },
       "recipients": [
         { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev" }
       ],
       "delivery": "embedded",
       "externalId": "user_8841",
       "dedupeOn": "external_id"
     }'

   TypeScript

   const res = await fetch('https://api.bonafidesign.com/v1/envelopes', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`,
       'Content-Type': 'application/json',
       'Idempotency-Key': 'onboarding-8841',
     },
     body: JSON.stringify({
       template: 'tpl_…',
       version: 'latest',
       variables: { client: { name: 'Acme Robotics, Inc.' }, effective_date: '2026-10-13' },
       recipients: [{ role: 'client', name: 'Jane Doe', email: 'jane@acme.dev' }],
       delivery: 'embedded',
       externalId: 'user_8841',
       dedupeOn: 'external_id',
     }),
   });
   if (res.status === 422) {
     // RFC 9457 problem: one entry per error, each with a JSON Pointer such as /variables/client/name
     console.error((await res.json()).errors);
   }
   const envelope = await res.json(); // { id: 'env_…', status: 'sent', recipients: [{ id: 'rcp_…', … }] }

   Python

   res = requests.post(
       f"{API}/v1/envelopes",
       headers={**headers, "Idempotency-Key": "onboarding-8841"},
       json={
           "template": "tpl_…",
           "version": "latest",
           "variables": {"client": {"name": "Acme Robotics, Inc."}, "effective_date": "2026-10-13"},
           "recipients": [{"role": "client", "name": "Jane Doe", "email": "jane@acme.dev"}],
           "delivery": "embedded",
           "externalId": "user_8841",
           "dedupeOn": "external_id",
       },
   )
   if res.status_code == 422:
       print(res.json()["errors"])  # [{"pointer": "/variables/client/name", "message": "…"}]
   envelope = res.json()

   התגובה היא 201 Created עם המעטפה:

   {
     "id": "env_8Gm2kQ4rT1",
     "organization": "org_…",
     "template": "tpl_…",
     "templateVersion": 3,
     "status": "sent",
     "seal": "not_started",
     "testMode": true,
     "recipients": [
       {
         "id": "rcp_5Jw0pLs9Xe",
         "role": "client",
         "name": "Jane Doe",
         "email": "jane@acme.dev",
         "order": 1,
         "status": "sent",
         "verification": "email_otp",
         "completedAt": null
       }
     ],
     "documentHash": "9f2c…",
     "sealedDocumentHash": null,
     "externalId": "user_8841",
     "metadata": {},
     "createdAt": "2026-10-13T13:58:04.512Z",
     "completedAt": null
   }

   לנסות בלי לשלוח

   מוסיפים ?dry_run=true כדי לאמת את המשתנים והנמענים ולרנדר את המסמך בלי לשמור, לשלוח או לחייב דבר. התגובה (200) כוללת את documentHash של המסמך שרונדר ואת מספר העמודים.

   השדה delivery קובע איך מגיעים לנמענים: email (ברירת המחדל) שולח לכל נמען קישור חתימה באימייל כשמגיע תורו; embedded ו-none לא שולחים אימייל, ואתם פותחים את סשני החתימה בעצמכם (השלב הבא).

4. החתימה של הנמען

   יוצרים סשן חתימה עבור הנמען מהשרת שלכם. הסשנים קצרי חיים (ttlSeconds, בין 60 ל-3600, ברירת מחדל 600) ולשימוש חד-פעמי.

   מוטמע

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

   מעבירים את ה-token שהוחזר (bfs_…) לדף שלכם ומרנדרים את ה-Web Component:

   <script type="module" src="https://js.bonafidesign.com/v1"></script>
   
   <bf-signing session="bfs_…"></bf-signing>
   <script>
     document.querySelector('bf-signing')
       .addEventListener('completed', (e) => console.log('signed', e.detail.envelope));
   </script>

   עטיפות React ו-Vue, אירועים ומודל האבטחה: חתימה מוטמעת.

   מאוחסן

   curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "hosted", "returnUrl": "https://app.example.com/done" }'

   מפנים את החותם אל ה-url שהוחזר (https://sign.bonafidesign.com/s/bfs_…). הדף המאוחסן מתוכנן קודם כול לנייד ואינו דורש חשבון.

   עם שיטת האימות email_otp שמוגדרת כברירת מחדל, החותם מאשר קוד בן שש ספרות שנשלח לאימייל שלו לפני השליחה. במצב בדיקה, אימייל נמסר רק לחברי הארגון שלכם, לכן כדאי להשתמש בכתובת שלכם בזמן הבדיקות.

5. קבלת התראה על השלמה

   רושמים נקודת קצה ל-webhook בהגדרות › Webhooks (או באמצעות POST /v1/webhook-endpoints) ושומרים את הסוד whsec_…. כשהנמען האחרון חותם מתקבל envelope.completed, עם כל משתנה וכל ערך שהוזן ב-data.values. קובץ ה-PDF הנעול מגיע אחר כך עם envelope.sealed.

   import express from 'express';
   import { Webhook } from 'standardwebhooks';
   
   const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!);
   const app = express();
   
   app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), async (req, res) => {
     const event = wh.verify(req.body, req.headers as Record<string, string>) as { type: string; data: any };
     if (event.type === 'envelope.completed') await saveValues(event.data.envelope.id, event.data.values);
     if (event.type === 'envelope.sealed') await fetchSealedPdf(event.data.envelope.id);
     res.sendStatus(204);
   });

   מורידים את ה-PDF הנעול (המסמך עם אישור ההשלמה, עם חותמת זמן):

   curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY"

   רשימת האירועים המלאה, ניסיונות חוזרים ואימות ידני: Webhooks.

מעבר לסביבה חיה

מחליפים את מפתח הבדיקה במפתח bf_live_. מעטפות חיות אינן מסומנות בסימן מים, האימייל נשלח לכל נמען, ומעטפות שהושלמו נספרות במסגרת התוכנית שלכם (תוכניות ומגבלות). כל מה שמפתח יוצר מקבל את המצב שלו, הרשימות שלו מציגות רק את המצב הזה, ומעטפות בדיקה שולחות התראות רק לנקודות קצה של webhook במצב בדיקה, לכן יש לרשום גם נקודת קצה חיה.