কুইকস্টার্ট

এই ধাপে ধাপে নির্দেশিকা একটি প্রকাশিত টেমপ্লেট থেকে শুরু করে একটি স্বাক্ষরিত, সিল করা PDF পর্যন্ত নিয়ে যায়। এতে একটি টেস্ট কী ব্যবহার করা হয়, তাই কোনো কিছুর বিল হয় না এবং প্রতিটি নথিতে TEST ওয়াটারমার্ক থাকে।

1. একটি API কী তৈরি করুন

   API কী ড্যাশবোর্ডে, সেটিংস › API কী-তে তৈরি করা হয়। এই নির্দেশিকার জন্য 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 ফেরত দেয়। ড্যাশবোর্ডে টেমপ্লেটের পৃষ্ঠায় একটি 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. সম্পন্ন হলে বিজ্ঞপ্তি পান

   সেটিংস › ওয়েবহুক-এ (অথবা 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"

   ইভেন্টের পুরো তালিকা, রিট্রাই এবং ম্যানুয়াল যাচাই: ওয়েবহুক।

লাইভে যাওয়া

টেস্ট কী-এর বদলে একটি bf_live_ কী ব্যবহার করুন। লাইভ খামে ওয়াটারমার্ক থাকে না, ইমেইল যেকোনো প্রাপকের কাছে যায়, এবং সম্পন্ন খাম আপনার প্ল্যানের হিসাবে গোনা হয় (প্ল্যান ও সীমা)। একটি কী যা কিছু তৈরি করে, সেগুলো ওই কী-এর মোডেই থাকে, এর তালিকায় শুধু সেই মোডই দেখা যায়, আর টেস্ট খাম শুধু টেস্ট মোডের ওয়েবহুক এন্ডপয়েন্টকে জানায়, তাই একটি লাইভ এন্ডপয়েন্টও নিবন্ধন করুন।