क्विकस्टार्ट

यह वॉकथ्रू एक पब्लिश किए गए टेम्पलेट से शुरू होकर एक हस्ताक्षरित, सील किए गए 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_ कुंजी लगाएँ। लाइव लिफ़ाफ़ों पर वॉटरमार्क नहीं होता, ईमेल हर प्राप्तकर्ता को जाता है, और पूरे हुए लिफ़ाफ़े आपके प्लान में गिने जाते हैं (प्लान और सीमाएँ)। कोई कुंजी जो कुछ भी बनाती है, वह उसी कुंजी के मोड में होता है, उसकी सूचियों में सिर्फ़ वही मोड दिखता है, और टेस्ट लिफ़ाफ़े सिर्फ़ टेस्ट मोड वाले वेबहुक एंडपॉइंट को सूचना देते हैं, इसलिए एक लाइव एंडपॉइंट भी रजिस्टर करें।