বিষয়বস্তুতে যান
bona fidedocs

টেমপ্লেট, ভূমিকা ও ফিল্ড

একটি টেমপ্লেট হলো পুনর্ব্যবহারযোগ্য একটি চুক্তি। এর একটি নাম, একটিমাত্র খসড়া, এবং যেকোনো সংখ্যক প্রকাশিত ভার্সন থাকে। খাম সবসময় একটি প্রকাশিত ভার্সন থেকে তৈরি হয়, যা অপরিবর্তনীয়: টেমপ্লেট সম্পাদনা মানে একটি নতুন খসড়া সংরক্ষণ করে সেটিকে পরের ভার্সন হিসেবে প্রকাশ করা। আগেই পাঠানো খামগুলো তাদের পিন করা ভার্সনই রাখে।

GET /v1/templates/tpl_…
{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

Id হলো প্রিফিক্সযুক্ত স্ট্রিং (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); টাইমস্ট্যাম্প UTC-তে RFC 3339।

তৈরির দুটি উপায়

“তৈরির দুটি উপায়” শিরোনামের অংশ

Overlay মোড (source: "pdf") একটি আপলোড করা নথি থেকে শুরু হয়। ফিল্ড হলো এর পৃষ্ঠাগুলোর ওপর বসানো আয়তক্ষেত্র, PDF পয়েন্টে (1/72 ইঞ্চি), মূলবিন্দু পৃষ্ঠার ওপরের-বাঁ কোণে, পৃষ্ঠার ইনডেক্স 0 থেকে। একটি .docx আপলোড একবার PDF-এ রূপান্তরিত হয় (LibreOffice দিয়ে, Word লেআউট বজায় রেখে; ফাইলে এমবেড না করা ফন্টের জায়গায় অন্য ফন্ট বসতে পারে), এবং তারপর থেকে এটি অন্য যেকোনো PDF-এর মতোই: ফাইলটি convertedFrom: "docx" জানায়। Overlay ভার্সনে কনটেন্ট সম্পাদনাও থাকতে পারে (জায়গায় সম্পাদিত টেক্সট, হোয়াইট-আউট, টেক্সট বক্স, ছবি, পৃষ্ঠা অপারেশন), যা ভার্সন প্রকাশের সময় প্রয়োগ হয়।

Document মোড (source: "document") চুক্তিটিকেই রিচ টেক্সট (ProseMirror JSON) হিসেবে সংরক্ষণ করে, যাতে থাকে {{client.name}}-এর মতো ভেরিয়েবল চিপ, ইনলাইন ফিল্ড ব্লক, শর্তসাপেক্ষ সেকশন (শুধু তখনই রাখা হয় যখন একটি showIf এক্সপ্রেশন সত্য) এবং পুনরাবৃত্ত সেকশন ও টেবিলের সারি (একটি অ্যারে ভেরিয়েবলের প্রতিটি আইটেমের জন্য একটি)। প্রতিটি খাম নিজের PDF রেন্ডার করে, এবং ফিল্ডের অবস্থান সেই রেন্ডার থেকে পড়া হয়। ড্যাশবোর্ডে Document মোড হলো “ফাঁকা নথি থেকে শুরু করুন”। API দিয়ে একটি Word ফাইল POST /v1/templates/{id}/import দিয়ে Document মোডে ইমপোর্টও করা যায়: {{tags}} ভেরিয়েবল বা ফিল্ডে পরিণত হয় এবং স্বাক্ষরের লাইন (“Signature: ____”, “By: ____”, “Date: ____”) ফিল্ড ব্লকে পরিণত হয়।

ড্যাশবোর্ডে

“ড্যাশবোর্ডে” শিরোনামের অংশ

নতুন টেমপ্লেট শুরু করার দুটি উপায় দেয়:

  • নথি আপলোড করুন: 25 MB পর্যন্ত .pdf ও .docx ফাইলের জন্য একটি ড্রপজোন। Word ফাইল PDF-এ রূপান্তরিত হয় এবং ডিজাইনারে খোলে, সঙ্গে একটি রিমাইন্ডার থাকে যে ফিল্ড বসানোর আগে রূপান্তরিত লেআউট যাচাই করে নিন। ছোট সংশোধন PDF-এর ওপরেই জায়গায় করা হয় (“কনটেন্ট সম্পাদনা”); বড় পরিবর্তনের জন্য Word ফাইলটি বদলে আবার আপলোড করুন।
  • ফাঁকা নথি থেকে শুরু করুন: Document মোডে চুক্তিটি লিখুন।

কনটেন্ট সম্পাদনা

“কনটেন্ট সম্পাদনা” শিরোনামের অংশ

ডিজাইনারের কনটেন্ট সম্পাদনা মোড আপলোড করা ফাইল না ছুঁয়েই বদলে দেয় স্বাক্ষরকারীরা যা দেখেন। এর ডিফল্ট টুল, টেক্সট সম্পাদনা, পৃষ্ঠার টেক্সট ব্লকগুলো হাইলাইট করে (PDF-এর টেক্সট লেয়ার থেকে গুচ্ছবদ্ধ লাইন ও অনুচ্ছেদ); একটিতে ক্লিক করুন, অথবা Tab দিয়ে সেখানে গিয়ে Enter চাপুন, তাহলে একই অবস্থান, আকার, রং, অ্যালাইনমেন্ট ও ফন্টে সেটি জায়গায় সম্পাদনা করতে পারবেন। Ctrl/Cmd+Enter সংরক্ষণ করে, Esc বাতিল করে, এবং প্রতিটি সম্পাদনা সম্পাদনার তালিকা থেকে ফিরিয়ে নেওয়া যায়। সম্পাদনা অন্য যেকোনো পরিবর্তনের মতোই আনডু করা যায়। অন্য টুলগুলো হোয়াইট-আউট, টেক্সট বক্স ও ছবি যোগ করে, এবং পৃষ্ঠা যোগ, মুছে ফেলা, পুনর্বিন্যাস বা ঘোরানোর কাজ করে।

জায়গায় করা একটি টেক্সট সম্পাদনা দুটি আইটেম হিসেবে সংরক্ষিত হয়, যাদের group একই: মূল ব্লকের ওপর একটি হোয়াইট-আউট (পৃষ্ঠার ব্যাকগ্রাউন্ডের রঙে) এবং ব্লকের মধ্যে বসানো একটি টেক্সট আইটেম, ব্লকের লাইন হাইট ও প্রথম বেসলাইনসহ:

edits.items (excerpt)
[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face ফন্ট বেছে নেয়: PDF-এর এমবেড করা ফন্ট, যদি সেটি নতুন টেক্সটের প্রতিটি অক্ষর আঁকতে পারে, নইলে একটি বান্ডল করা মেট্রিক-সামঞ্জস্যপূর্ণ ফন্ট (Helvetica/Arial-এর জন্য sans Arimo, Times-এর জন্য serif Tinos, Courier-এর জন্য mono Cousine, Calibri-র জন্য carlito Carlito), মিলে যাওয়া ওজন ও স্টাইলে। টেক্সট ব্লকের মধ্যে র‍্যাপ হয়; যখন এর মূলের চেয়ে বেশি লাইন লাগে, সম্পাদনাটি নিচের খালি জায়গায় বেড়ে যায়, আর খালি জায়গা না থাকলে ডিজাইনার সেটি সংরক্ষণ করতে দেয় না (“টেক্সট আঁটছে না — ছোট করুন বা জায়গা বাড়ান”)। ডিজাইনার ও API লেআউট ও ফন্টের একই কোড ব্যবহার করে, তাই প্রকাশিত PDF প্রিভিউয়ের সঙ্গে লাইন ধরে ধরে মিলে যায়।

সম্পাদনা শুধু একটি খসড়া বদলাতে পারে। প্রকাশ করলে সেগুলো একটি নতুন বেস PDF-এ প্রয়োগ হয়, যার SHA-256 হলো ভার্সনের documentHash (স্বাক্ষরকারীরা যা দেখেন তার হ্যাশ); আপলোড করা মূল ফাইলটি ভার্সনের sourceFile হিসেবে রাখা হয়, এবং পরের খসড়া একই সম্পাদনাসহ সেখান থেকেই শুরু হয়। হোয়াইট-আউট কনটেন্টকে শুধু দৃশ্যত ঢেকে দেয়; মূল টেক্সট নিচে ফাইলেই থেকে যায়, তাই এটি নিরাপদ রিড্যাকশন নয়।

ভূমিকা

“ভূমিকা” শিরোনামের অংশ

ভূমিকা হলো চুক্তির পক্ষগুলো। একটি খামের প্রাপকদের key দিয়ে ভূমিকার সঙ্গে মেলানো হয়।

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }
প্রপার্টি অর্থ
key ছোট হাতের আইডেন্টিফায়ার (^[a-z][a-z0-9_]*$), যা ফিল্ড ও খামের প্রাপকেরা ব্যবহার করে
kind signer (একটি স্বাক্ষর বা আদ্যক্ষর ফিল্ড থাকতে হবে), approver, form_filler, অথবা cc (গ্রহণ করে, কখনো স্বাক্ষর করে না)
order 1 থেকে রাউটিং ক্রম। একই ক্রমের ভূমিকাগুলো সমান্তরালে স্বাক্ষর করে; সেগুলো শেষ হলে পরের ক্রম শুরু হয়
verification ভূমিকার প্রাপক কীভাবে নিজের পরিচয় প্রমাণ করেন: none (ডিফল্ট: শুধু অনন্য স্বাক্ষর লিংক) অথবা email_otp (লিংকের সঙ্গে ইমেইলে পাঠানো কোড)। প্রাপক এটি ওভাররাইড করতে পারেন; স্বাক্ষরকারী যাচাই দেখুন

passkey, id_check ও sms_otp স্কিমায় আছে, কিন্তু এখনো স্বাক্ষরের জন্য উপলব্ধ নয়: যে টেমপ্লেট passkey বা id_check ব্যবহার করে তা প্রকাশ করা যায় না, এবং SMS কোড এখনো পাঠানো হয় না।

ফিল্ড

“ফিল্ড” শিরোনামের অংশ
{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

ফিল্ডের ধরন: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp, এবং variable_text (প্রেরক একটি ভেরিয়েবল থেকে পূরণ করেন, স্বাক্ষরকারী নন)। ফিল্ডে আরও থাকতে পারে:

  • variable: ভেরিয়েবলের মধ্যে একটি JSON Pointer (/client/name), ফিল্ডটি বাঁধতে বা আগে থেকে পূরণ করতে;
  • radio ও dropdown-এর জন্য options;
  • validation: pattern, min, max, maxLength, অথবা একটি format (email, phone, date, number, currency);
  • showIf: ভেরিয়েবল ও অন্যান্য ফিল্ডের ওপর একটি শর্ত, যেমন plan != "free";
  • formula: একটি গণনা করা, শুধু-পড়ার মান;
  • overflow: মান বক্সে না আঁটলে কী করতে হবে: shrink (ডিফল্ট), wrap বা reject।

ভেরিয়েবল

“ভেরিয়েবল” শিরোনামের অংশ

একটি ভার্সনের variables হলো সেই ডেটার JSON Schema (draft 2020-12), যা আপনি প্রতিটি খামের সঙ্গে পাঠান; ভার্সনের sampleVariables হলো একটি উদাহরণ। POST /v1/envelopes আপনার variables এর সঙ্গে মিলিয়ে যাচাই করে এবং প্রতিটি সমস্যা একটি JSON Pointer-সহ জানায়:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

পাঠানোর আগে ফলাফল দেখতে, যেকোনো ভার্সনের ওয়াটারমার্কযুক্ত প্রিভিউ POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) দিয়ে রেন্ডার করুন, অথবা খামটি ?dry_run=true দিয়ে তৈরি করুন।

API দিয়ে টেমপ্লেট তৈরি

“API দিয়ে টেমপ্লেট তৈরি” শিরোনামের অংশ

বেশিরভাগ টিম ড্যাশবোর্ডের ডিজাইনারে টেমপ্লেট ডিজাইন করে। ডিজাইনার যা কিছু করে, তার সবই API-তে পাওয়া যায়:

  1. { "name": "Mutual NDA" } দিয়ে POST /v1/templates।
  2. POST /v1/templates/{id}/files, PDF (বা .docx) বডি হিসেবে (Content-Type: application/pdf) অথবা মাল্টিপার্ট ফিল্ড file হিসেবে। সর্বোচ্চ 25 MB। রেসপন্সে ফাইলের id (tfl_…), পৃষ্ঠার সংখ্যা ও পৃষ্ঠার আকার থাকে।
  3. roles, fields, variables (এবং file, অথবা content-সহ source: "document") দিয়ে PUT /v1/templates/{id}/draft। খসড়া যেমন আছে তেমনই সংরক্ষিত হয়; এখনো কিছু যাচাই করা হয় না।
  4. POST /v1/templates/{id}/publish। প্রকাশের সময় খসড়াটি লিন্ট করা হয়: প্রতিটি ফিল্ডের ভূমিকা আছে, প্রতিটি স্বাক্ষরকারী ভূমিকার একটি স্বাক্ষর ফিল্ড আছে, ফিল্ডগুলো পৃষ্ঠায় আঁটে, radio ও dropdown ফিল্ডে বিকল্প আছে, এক্সপ্রেশন পার্স হয়। সমস্যাগুলো /fields/3/rect-এর মতো পয়েন্টারসহ 422 হিসেবে ফেরত আসে।
Terminal window
curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

ভার্সন এন্ডপয়েন্ট একটি সংখ্যা, latest বা draft গ্রহণ করে: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (বেস PDF)। যে টেমপ্লেট কখনো কোনো খাম বা স্বাক্ষর লিংক ব্যবহার করেনি, সেটি মুছে ফেলা যায়; অন্যথায় DELETE উত্তর দেয় 409 in-use।