ٹیمپلیٹس، کردار اور فیلڈز

ٹیمپلیٹ ایک دوبارہ قابلِ استعمال معاہدہ ہے۔ اس کا ایک نام، ایک واحد مسودہ، اور کتنے ہی شائع شدہ ورژنز ہوتے ہیں۔ لفافے ہمیشہ کسی شائع شدہ ورژن سے بنتے ہیں، جو ناقابلِ تبدیل ہوتا ہے: ٹیمپلیٹ میں ترمیم کا مطلب ہے نیا مسودہ محفوظ کرنا اور اسے اگلے ورژن کے طور پر شائع کرنا۔ پہلے سے بھیجے گئے لفافے وہی ورژن برقرار رکھتے ہیں جو انہوں نے مقرر کیا تھا۔

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"
}

Ids سابقے والی سٹرنگز ہیں (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 ورژنز میں مواد کی ترامیم بھی ہو سکتی ہیں (اپنی جگہ پر ترمیم شدہ متن، white-out، ٹیکسٹ باکسز، تصاویر، صفحات کی کارروائیاں) جو ورژن شائع ہونے پر لاگو ہوتی ہیں۔

Document موڈ (source: "document") معاہدے کو بذاتِ خود رچ ٹیکسٹ (ProseMirror JSON) کے طور پر محفوظ کرتا ہے، جس میں {{client.name}} جیسے ویری ایبل چپس، ان لائن فیلڈ بلاکس، مشروط سیکشنز (جو صرف اس وقت رکھے جاتے ہیں جب showIf ایکسپریشن درست ہو) اور دہرائے جانے والے سیکشنز اور ٹیبل کی قطاریں (ارے ویری ایبل کے ہر آئٹم کے لیے ایک) ہوتی ہیں۔ ہر لفافہ اپنی PDF خود رینڈر کرتا ہے، اور فیلڈز کی پوزیشنز اسی رینڈر سے پڑھی جاتی ہیں۔ ڈیش بورڈ میں Document موڈ کا نام “Start from blank document” ہے۔ API کے ذریعے، Word فائل کو POST /v1/templates/{id}/import سے Document موڈ میں امپورٹ بھی کیا جا سکتا ہے: {{tags}} ویری ایبلز یا فیلڈز بن جاتے ہیں اور دستخط کی لائنیں (“Signature: ____”، “By: ____”، “Date: ____”) فیلڈ بلاکس بن جاتی ہیں۔

ڈیش بورڈ میں

New template دو طرح سے آغاز کی پیشکش کرتا ہے:

• Upload document: 25 MB تک کی .pdf اور .docx فائلوں کے لیے ایک ڈراپ زون۔ Word فائلیں PDF میں تبدیل ہو کر ڈیزائنر میں کھلتی ہیں، اس یاد دہانی کے ساتھ کہ فیلڈز لگانے سے پہلے تبدیل شدہ ترتیب کی جانچ کر لیں۔ چھوٹی اصلاحات PDF پر اپنی جگہ ہی کی جاتی ہیں (“Edit content”)؛ بڑی تبدیلی کے لیے Word فائل بدلیں اور اسے دوبارہ اپ لوڈ کریں۔
• Start from blank document: معاہدہ Document موڈ میں لکھیں۔

مواد کی ترامیم

ڈیزائنر کا Edit content موڈ اپ لوڈ کی گئی فائل کو چھوئے بغیر وہ بدلتا ہے جو دستخط کنندگان دیکھتے ہیں۔ اس کا ڈیفالٹ ٹول، Edit text، صفحے کے ٹیکسٹ بلاکس کو نمایاں کرتا ہے (PDF کی ٹیکسٹ لیئر سے گروپ کی گئی لائنیں اور پیراگراف)؛ کسی ایک پر کلک کریں، یا Tab سے اس تک جائیں اور Enter دبائیں، تاکہ اسی پوزیشن، سائز، رنگ، ترتیب اور فونٹ میں اپنی جگہ پر اس میں ترمیم کریں۔ Ctrl/Cmd+Enter محفوظ کرتا ہے، Esc منسوخ کرتا ہے، اور ہر ترمیم کو ترامیم کی فہرست سے واپس لیا جا سکتا ہے۔ کسی بھی دوسری تبدیلی کی طرح ترامیم undo کی جا سکتی ہیں۔ باقی ٹولز white-out، ٹیکسٹ باکسز اور تصاویر شامل کرتے ہیں، اور صفحات داخل، حذف، دوبارہ ترتیب یا گھماتے ہیں۔

اپنی جگہ پر کی گئی ٹیکسٹ ترمیم دو آئٹمز کے طور پر محفوظ ہوتی ہے جن کا group مشترک ہوتا ہے: اصل بلاک کے اوپر ایک white-out (صفحے کے پس منظر کے رنگ میں) اور بلاک میں ترتیب دیا گیا ایک ٹیکسٹ آئٹم، بلاک کی لائن کی اونچائی اور پہلی بیس لائن کے ساتھ:

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 کا ایمبیڈ کیا ہوا فونٹ نئے متن کا ہر حرف بنا سکے تو وہی، ورنہ ایک ساتھ شامل metric-compatible فونٹ (sans Helvetica/Arial کے لیے Arimo، serif Times کے لیے Tinos، mono Courier کے لیے Cousine، carlito Calibri کے لیے Carlito)، مطابقت رکھنے والے وزن اور انداز میں۔ متن بلاک کے اندر لپٹتا ہے؛ جب اسے اصل سے زیادہ لائنوں کی ضرورت ہو تو ترمیم اپنے نیچے خالی جگہ میں پھیل جاتی ہے، اور اگر خالی جگہ نہ ہو تو ڈیزائنر اسے محفوظ کرنے سے انکار کر دیتا ہے (“text doesn’t fit — shorten it or add space”)۔ ڈیزائنر اور API ترتیب اور فونٹ کا ایک ہی کوڈ استعمال کرتے ہیں، اس لیے شائع شدہ PDF پیش منظر سے لائن بہ لائن مطابقت رکھتی ہے۔

ترامیم صرف مسودے کو بدل سکتی ہیں۔ شائع کرنا انہیں ایک نئی بنیادی PDF پر لاگو کرتا ہے جس کا SHA-256 ورژن کا documentHash ہوتا ہے (جو دستخط کنندگان دیکھتے ہیں اس کا ہیش)؛ اپ لوڈ کی گئی اصل فائل ورژن کی sourceFile کے طور پر رکھی جاتی ہے، اور اگلا مسودہ انہی ترامیم کے ساتھ اسی سے شروع ہوتا ہے۔ White-out مواد کو صرف بصری طور پر ڈھانپتا ہے؛ اصل متن فائل میں نیچے موجود رہتا ہے، اس لیے یہ محفوظ redaction نہیں ہے۔

کردار

کردار معاہدے کے فریق ہیں۔ لفافے کے وصول کنندگان کو 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 کے ذریعے دستیاب ہے:

1. { "name": "Mutual NDA" } کے ساتھ POST /v1/templates۔
2. PDF (یا .docx) کو باڈی کے طور پر (Content-Type: application/pdf) یا multipart فیلڈ file کے طور پر بھیج کر POST /v1/templates/{id}/files۔ زیادہ سے زیادہ 25 MB۔ جواب میں فائل کی id (tfl_…)، صفحات کی تعداد اور صفحات کے سائز ہوتے ہیں۔
3. roles، fields، variables (اور file، یا content کے ساتھ source: "document") کے ساتھ PUT /v1/templates/{id}/draft۔ مسودے جیسے ہیں ویسے ہی محفوظ ہوتے ہیں؛ ابھی کسی چیز کی جانچ نہیں ہوتی۔
4. POST /v1/templates/{id}/publish۔ شائع کرنا مسودے کو lint کرتا ہے: ہر فیلڈ کا کردار موجود ہو، ہر signer کردار کی دستخط کی فیلڈ ہو، فیلڈز اپنے صفحات میں سمائیں، radio اور dropdown فیلڈز کے options ہوں، ایکسپریشنز پارس ہوں۔ مسائل 422 کے طور پر /fields/3/rect جیسے پوائنٹرز کے ساتھ واپس آتے ہیں۔

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 دیتا ہے۔