فوری آغاز

یہ رہنمائی ایک شائع شدہ ٹیمپلیٹ کو دستخط شدہ، سیل شدہ PDF تک لے جاتی ہے۔ اس میں ٹیسٹ کلید استعمال ہوتی ہے، اس لیے کسی چیز کا بل نہیں بنتا اور ہر دستاویز پر TEST کا واٹر مارک ہوتا ہے۔

1. API کلید بنائیں

   API کیز ڈیش بورڈ میں Settings › API keys کے تحت بنائی جاتی ہیں۔ اس رہنمائی کے لیے Test منتخب کریں: کلید bf_test_ سے شروع ہوتی ہے۔ پوری کلید صرف ایک بار دکھائی جاتی ہے؛ اسے انوائرمنٹ ویری ایبل کے طور پر محفوظ کر لیں۔

   export BONA_FIDE_API_KEY=bf_test_…

   ہر درخواست اسے Authorization: Bearer … (یا x-api-key: …) کے طور پر بھیجتی ہے۔ دیکھیں توثیق۔

2. اپنا ٹیمپلیٹ تلاش کریں

   ٹیمپلیٹس ڈیش بورڈ میں ڈیزائن کیے جاتے ہیں (PDF یا Word دستاویز اپ لوڈ کر کے فیلڈز لگائیں، یا اسے Document موڈ میں لکھیں) اور پھر شائع کیے جاتے ہیں۔ id حاصل کرنے کے لیے ان کی فہرست منگوائیں:

   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 اور اس کے variables کا JSON Schema واپس کرتا ہے۔ ڈیش بورڈ میں ٹیمپلیٹ کے صفحے پر 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_…) اپنے صفحے کو دیں اور ویب کمپوننٹ رینڈر کریں:

   <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. تکمیل پر اطلاع حاصل کریں

   Settings › Webhooks میں (یا POST /v1/webhook-endpoints کے ذریعے) ایک webhook اینڈ پوائنٹ رجسٹر کریں اور 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 اینڈ پوائنٹس کو مطلع کرتے ہیں، اس لیے ایک لائیو اینڈ پوائنٹ بھی رجسٹر کریں۔