हस्ताक्षर सेशन और लिंक

प्राप्तकर्ता Bona Fide के हस्ताक्षर पेज पर हस्ताक्षर करते हैं: या तो https://sign.bonafidesign.com/s/… पर होस्ट किया गया पेज, या वही पेज <bf-signing> के साथ आपके प्रोडक्ट में एम्बेड किया गया। प्राप्तकर्ताओं को अकाउंट की ज़रूरत नहीं होती। उन्हें अंदर आने की अनुमति एक हस्ताक्षर सेशन देता है।

हस्ताक्षर सेशन

ईमेल डिलीवरी आपके लिए सेशन ख़ुद बनाती है (ईमेल में मौजूद लिंक)। एम्बेडेड या ख़ुद पहुँचाए जाने वाले हस्ताक्षर के लिए अपने बैकएंड से एक सेशन बनाएँ:

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

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

फ़ील्ड	टिप्पणी
recipient	लिफ़ाफ़े का ऐसा प्राप्तकर्ता जो अब भी हस्ताक्षर कर सकता है (CC नहीं, पूरा कर चुका नहीं)
mode	embedded (डिफ़ॉल्ट) या hosted। होस्टेड url का रूप …/s/<token> होता है, जिस पर रीडायरेक्ट करें या जिसे ख़ुद भेजें
allowedOrigins	अधिकतम 10 ओरिजिन, जो एम्बेड किए गए पेज को फ़्रेम में दिखा सकते हैं
returnUrl	हस्ताक्षर पूरा होने पर होस्ट किया गया पेज हस्ताक्षरकर्ता को कहाँ भेजे
ttlSeconds	60 से 3600, डिफ़ॉल्ट 600

सेशन सिर्फ़ एक बार इस्तेमाल होते हैं: प्राप्तकर्ता के सबमिट करते ही सेशन ख़र्च हो जाता है, और इस्तेमाल हो चुका या समय-सीमा पार कर चुका सेशन 410 Gone लौटाता है। हर बार अपना पेज रेंडर होने पर नया सेशन बनाएँ। सेशन तभी बनाए जा सकते हैं जब लिफ़ाफ़ा sent हो, और लिफ़ाफ़ा रद्द करने पर सभी सेशन समाप्त हो जाते हैं।

हस्ताक्षरकर्ता किन चरणों से गुज़रता है

हस्ताक्षर पेज (और उसी API पर आपके द्वारा बनाया गया कोई भी कस्टम UI) इन चरणों का पालन करता है:

1. एक्सचेंज: POST /v1/signing/exchange { "token": "bfs_…" } एक कम अवधि वाला एक्सेस टोकन (bfa_…) लौटाता है, जो मेमोरी में रखा जाता है। इसमें कोई कुकी शामिल नहीं होती, इसलिए iframe में थर्ड-पार्टी कुकी ब्लॉक होने से कोई फ़र्क नहीं पड़ता।
2. लोड: GET /v1/signing/session हस्ताक्षरकर्ता का व्यू लौटाता है (लिफ़ाफ़े का शीर्षक, भेजने वाला, प्राप्तकर्ता की भूमिका और फ़ील्ड, पहले से भरे मान, उपभोक्ता प्रकटीकरण) और पहली बार recipient.viewed दर्ज करता है। GET /v1/signing/document दिखाया जाने वाला PDF है।
3. सत्यापन (सिर्फ़ email_otp के साथ): POST /v1/signing/otp छह अंकों का कोड ईमेल करता है (10 मिनट के लिए मान्य) और POST /v1/signing/otp/verify उसकी जाँच करता है। ग़लत कोड पर बचे हुए प्रयासों के साथ verified: false लौटता है। जब प्राप्तकर्ता के तरीके में कोड की ज़रूरत नहीं होती, तो व्यू का verification.verified पहले से true होता है।
4. सबमिट: POST /v1/signing/submit, फ़ील्ड के values (बनाए गए, टाइप किए गए या अपलोड किए गए हस्ताक्षर), प्रकटीकरण पर सहमति, और viewedDocumentHash के साथ: ठीक उस PDF का SHA-256 जो दिखाया गया था। अगर तब से दस्तावेज़ बदल गया है, तो सबमिट अस्वीकार कर दिया जाता है (409)।
5. या मना करें: POST /v1/signing/decline { "reason": "…" } लिफ़ाफ़े को समाप्त कर देता है (envelope.declined)।

प्राप्तकर्ता की बारी तभी आती है जब उससे पहले के सभी रूटिंग समूह पूरे हो चुके हों; उससे पहले व्यू में canSign: false होता है, और सबमिट करने पर 409 not-your-turn मिलता है।

हस्ताक्षरकर्ता सत्यापन

हर प्राप्तकर्ता का एक verification तरीका होता है: भूमिका का तरीका (टेम्पलेट डिज़ाइनर के भूमिका पैनल में सेट किया गया), जब तक कि लिफ़ाफ़ा उसे किसी प्राप्तकर्ता के लिए ओवरराइड न करे (भेजने वाली स्क्रीन, या recipients[].verification)।

तरीका	हस्ताक्षरकर्ता क्या करता है	कब इस्तेमाल करें
none (डिफ़ॉल्ट)	यूनिक हस्ताक्षर लिंक खोलता है और हस्ताक्षर करता है	लिंक उन्हें ईमेल किया जाता है: वह सिर्फ़ उसी के पास होता है जिसकी उस इनबॉक्स तक पहुँच है
email_otp	लिंक खोलता है, फिर उसी पते पर ईमेल किया गया छह अंकों का कोड डालता है	जब आप हस्ताक्षर के समय एक दूसरा, ताज़ा प्रमाण चाहते हैं (बड़े मूल्य वाले अनुबंध, साझा इनबॉक्स)
integrator_asserted	आपके प्रोडक्ट में हस्ताक्षर करता है, जो उनकी पहचान की पुष्टि करता है (externalUserId)	आपके अपने लॉगिन के पीछे एम्बेडेड हस्ताक्षर

none डिफ़ॉल्ट इसलिए है, क्योंकि Bona Fide जो लिंक ईमेल करता है, वह अपने आप में प्राप्तकर्ता के लिए यूनिक है और उसका अनुमान नहीं लगाया जा सकता: उसे खोलना ईमेल पते पर नियंत्रण दिखाता है, और इलेक्ट्रॉनिक हस्ताक्षर क़ानून इसी एट्रिब्यूशन पर निर्भर करते हैं (अमेरिका में ESIGN / UETA, eIDAS के तहत साधारण इलेक्ट्रॉनिक हस्ताक्षर)। तुलनीय प्रोडक्ट भी यही डिफ़ॉल्ट रखते हैं। email_otp के साथ पब्लिश किए गए टेम्पलेट इसे बनाए रखते हैं, और स्पष्ट रूप से दिया गया email_otp हर जगह काम करता रहता है।

दो फ़्लो कभी सिर्फ़ लिंक पर निर्भर नहीं होते:

• हमेशा चालू हस्ताक्षर लिंक (/l/…): विज़िटर अपना पता ख़ुद टाइप करता है, इसलिए लिफ़ाफ़ा बनने से पहले वह हमेशा ईमेल किए गए कोड की पुष्टि करता है, टेम्पलेट में चाहे जो भी हो।
• आपके द्वारा बनाए गए सेशन (POST /v1/envelopes/{id}/sessions) में ईमेल पते का कोई प्रमाण नहीं होता: यह आपके लॉगिन का काम है, इसलिए उनके लिए integrator_asserted (externalUserId के साथ) या email_otp इस्तेमाल करें।

पूर्णता प्रमाणपत्र हर हस्ताक्षरकर्ता के लिए दर्ज करता है कि वास्तव में क्या इस्तेमाल हुआ:

किस रूप में दर्ज होता है	कब
ईमेल लिंक (पते पर भेजा गया यूनिक लिंक)	none, ईमेल किए गए लिंक से हस्ताक्षर
ईमेल लिंक + वन-टाइम कोड (पते पर भेजा गया)	email_otp, ईमेल किए गए लिंक से हस्ताक्षर
हस्ताक्षर लिंक + वन-टाइम कोड (पते पर भेजा गया)	हमेशा चालू लिंक का विज़िटर
वन-टाइम कोड (पते पर भेजा गया)	आपके द्वारा बनाए गए सेशन में email_otp
भेजने वाले द्वारा जारी किया गया हस्ताक्षर सेशन	आपके द्वारा बनाए गए सेशन में none
इंटीग्रेटर का दावा	integrator_asserted

सार्वजनिक सत्यापन सारांश यही लेबल दिखाता है, पर बिना पते के।

भाषाएँ

हस्ताक्षर पेज, उसके ईमेल (अनुरोध, रिमाइंडर, कोड, पूरा हुआ, रद्द हुआ), हमेशा चालू लिंक का पेज और व्यूअर स्टेटस पेज 50 भाषाओं में उपलब्ध हैं। हस्ताक्षरकर्ता उन्हें इस प्राथमिकता क्रम में देखता है:

1. वह भाषा जो उसने पेज के भाषा मेन्यू से चुनी (उस डिवाइस पर याद रखी जाती है);
2. <bf-signing locale="…"> (एम्बेडेड हस्ताक्षर) या होस्ट किए गए लिंक पर ?locale=;
3. प्राप्तकर्ता का locale, जो लिफ़ाफ़ा बनाते समय सेट किया जाता है (recipients[].locale, या लिफ़ाफ़े पर locale, उन सबके लिए जिनकी अपनी भाषा तय नहीं है);
4. उसके ब्राउज़र की भाषा।

ईमेल को किसी के पेज खोलने से पहले ही भाषा चाहिए, इसलिए वे प्राप्तकर्ता के locale का इस्तेमाल करते हैं और उसके बिना अंग्रेज़ी में होते हैं। हमेशा चालू लिंक कोड वाला ईमेल उसी भाषा में भेजते हैं, जो विज़िटर के पेज पर दिख रही है।

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

मिलते-जुलते टैग स्वीकार किए जाते हैं और उसी भाषा के रूप में संग्रहीत होते हैं जिससे वे मेल खाते हैं (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); इसके अलावा कुछ भी वैलिडेशन एरर है। अनुवादित सहमति प्रकटीकरण में लिखा होता है कि अंग्रेज़ी पाठ मान्य है, और हस्ताक्षरकर्ता उस पर स्विच कर सकता है; जिस भाषा में प्रकटीकरण पढ़ा गया, वह हस्ताक्षर के साथ दर्ज होती है (recipient.signed ऑडिट इवेंट में consentLocale)।

कोड	भाषा	मूल नाम
ar	अरबी	العربية	दाएँ से बाएँ
hy	आर्मेनियाई	Հայերեն
bn	बांग्ला	বাংলা
bg	बल्गेरियाई	Български
zh-Hans	चीनी (सरलीकृत)	简体中文
zh-Hant	चीनी (पारंपरिक)	繁體中文
hr	क्रोएशियाई	Hrvatski
cs	चेक	Čeština
da	डेनिश	Dansk
nl	डच	Nederlands
en-GB	अंग्रेज़ी (यूके)	English (UK)
en-US	अंग्रेज़ी (अमेरिका)	English (US)
et	एस्टोनियाई	Eesti
fil	फ़िलिपिनो	Filipino
fi	फ़िनिश	Suomi
fr	फ़्रेंच	Français
fr-CA	फ़्रेंच (कनाडा)	Français (Canada)
de	जर्मन	Deutsch
el	ग्रीक	Ελληνικά
he	हिब्रू	עברית	दाएँ से बाएँ
hi	हिन्दी	हिन्दी
hu	हंगेरियाई	Magyar
id	इंडोनेशियाई	Bahasa Indonesia
it	इतालवी	Italiano
ja	जापानी	日本語
ko	कोरियाई	한국어
lv	लातवियाई	Latviešu
lt	लिथुआनियाई	Lietuvių
ms	मलय	Bahasa Melayu
mr	मराठी	मराठी
nb	नॉर्वेजियाई	Norsk bokmål
fa	फ़ारसी	فارسی	दाएँ से बाएँ
pl	पोलिश	Polski
pt-BR	पुर्तगाली (ब्राज़ील)	Português (Brasil)
pt-PT	पुर्तगाली (पुर्तगाल)	Português (Portugal)
ro	रोमानियाई	Română
ru	रूसी	Русский
sr-Latn	सर्बियाई (लैटिन)	Srpski
sk	स्लोवाक	Slovenčina
sl	स्लोवेनियाई	Slovenščina
es-419	स्पेनिश (लैटिन अमेरिका)	Español (Latinoamérica)
es-ES	स्पेनिश (स्पेन)	Español (España)
sw	स्वाहिली	Kiswahili
sv	स्वीडिश	Svenska
te	तेलुगु	తెలుగు
th	थाई	ไทย
tr	तुर्की	Türkçe
uk	यूक्रेनियाई	Українська
ur	उर्दू	اردو	दाएँ से बाएँ
vi	वियतनामी	Tiếng Việt

हमेशा चालू हस्ताक्षर लिंक

हस्ताक्षर लिंक उन अनुबंधों के लिए एक स्थायी URL है, जिन पर बहुत से लोग एक ही तरह से हस्ताक्षर करते हैं: कोई छूट-पत्र (waiver), कॉन्ट्रैक्टर एग्रीमेंट, किसी पायलट की शर्तें। इसे पूरा करने वाले हर विज़िटर को अपना अलग लिफ़ाफ़ा मिलता है।

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

• visitorRole वह हस्ताक्षरकर्ता भूमिका है, जो विज़िटर लेता है। लिंक एक विज़िटर और अधिकतम एक काउंटरसाइनर को सपोर्ट करते हैं: mode: "auto" Bona Fide प्लेटफ़ॉर्म सील के साथ अपने आप काउंटरसाइन करता है, mode: "person" लिफ़ाफ़े को दिए गए email पर भेजता है। बाकी किसी भी गैर-CC भूमिका का कोई प्राप्तकर्ता नहीं होगा, इसलिए ऐसे टेम्पलेट अस्वीकार किए जाते हैं।
• विज़िटर अपना नाम, ईमेल और टेम्पलेट के वेरिएबल डालता है, फिर कुछ भी बनने से पहले ईमेल कोड की पुष्टि करता है (POST /v1/links/{id}/start, फिर POST /v1/links/{id}/verify)।
• limits उपयोग को सीमित करता है: प्रति ईमेल प्रति दिन (डिफ़ॉल्ट 3), प्रति IP प्रति घंटा (डिफ़ॉल्ट 20), कुल प्रति दिन, और ईमेल डोमेन के अनुसार। dedupe (डिफ़ॉल्ट रूप से चालू) के साथ, जिस ईमेल पते ने पहले ही हस्ताक्षर कर दिए हैं, उसे 409 already-signed मिलता है।
• PATCH /v1/signing-links/{id} लिंक को रोकता है (active: false), फिर से शुरू करता है या नए वर्ज़न पर ले जाता है; लिंक हटाने पर उससे बने लिफ़ाफ़े बने रहते हैं। हर इस्तेमाल पर signing_link.used जारी होता है।

टिप्पणी

विज़िटर पेज लिंक के url (https://sign.bonafidesign.com/l/lnk_…) पर है। GET /v1/links/{id} वह सार्वजनिक विवरण है, जिसे यह पेज रेंडर करता है: टेम्पलेट का नाम, विज़िटर के फ़ील्ड और वे वेरिएबल जो वह भरता है।