স্বাক্ষর সেশন ও লিংক

প্রাপকেরা 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} হলো সেই পাবলিক বিবরণ, যা পৃষ্ঠাটি রেন্ডার করে: টেমপ্লেটের নাম, ভিজিটরের ফিল্ড এবং তিনি যে ভেরিয়েবলগুলো পূরণ করেন।