دستخط کے سیشنز اور لنکس

وصول کنندگان 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۔ ہوسٹڈ urls کی شکل …/s/<token> ہوتی ہے، جن پر ری ڈائریکٹ کیا جائے یا جو آپ خود بھیجیں
allowedOrigins	زیادہ سے زیادہ 10 origins جو ایمبیڈ کیے گئے صفحے کو فریم کر سکتے ہیں
returnUrl	فارغ ہونے پر ہوسٹ کیا گیا صفحہ دستخط کنندہ کو کہاں بھیجے
ttlSeconds	60 سے 3600، ڈیفالٹ 600

سیشنز صرف ایک بار استعمال ہوتے ہیں: جیسے ہی وصول کنندہ جمع کراتا ہے، سیشن ختم ہو جاتا ہے، اور استعمال شدہ یا میعاد ختم سیشن 410 Gone جواب دیتا ہے۔ ہر بار جب آپ کا صفحہ رینڈر ہو تو نیا سیشن بنائیں۔ سیشنز صرف اسی وقت بنائے جا سکتے ہیں جب لفافہ sent ہو، اور لفافہ کالعدم کرنے سے وہ سب ختم ہو جاتے ہیں۔

دستخط کنندہ کن مراحل سے گزرتا ہے

دستخط کا صفحہ (اور کوئی بھی کسٹم UI جو آپ اسی API پر بنائیں) یہ مراحل اختیار کرتا ہے:

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. جمع کرانا: فیلڈ کی values (بنائے گئے، ٹائپ کیے گئے یا اپ لوڈ کیے گئے دستخط)، انکشافی بیان پر رضامندی، اور viewedDocumentHash کے ساتھ POST /v1/signing/submit: یعنی اس عین 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 ہے جن پر بہت سے لوگ ایک ہی طرح دستخط کرتے ہیں: دستبرداری نامہ، کنٹریکٹر معاہدہ، کسی پائلٹ کی شرائط۔ اسے مکمل کرنے والے ہر وزیٹر کو اپنا الگ لفافہ ملتا ہے۔

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} وہ عوامی تفصیل ہے جسے یہ صفحہ رینڈر کرتا ہے: ٹیمپلیٹ کا نام، وزیٹر کی فیلڈز اور وہ ویری ایبلز جو وہ بھرتا ہے۔