इसे छोड़कर कंटेंट पर जाएं
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 होते हैं।

बनाने के दो तरीके

Section titled “बनाने के दो तरीके”

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: ____”) फ़ील्ड ब्लॉक बन जाती हैं।

डैशबोर्ड में

Section titled “डैशबोर्ड में”

नया टेम्पलेट शुरू करने के दो तरीके देता है:

  • दस्तावेज़ अपलोड करें: 25 MB तक की .pdf और .docx फ़ाइलों के लिए एक ड्रॉपज़ोन। Word फ़ाइलें PDF में बदली जाती हैं और डिज़ाइनर में एक रिमाइंडर के साथ खुलती हैं कि फ़ील्ड लगाने से पहले बदले गए लेआउट की जाँच कर लें। छोटे सुधार PDF पर अपनी जगह पर किए जाते हैं (“कंटेंट संपादित करें”); बड़े बदलाव के लिए Word फ़ाइल बदलें और उसे दोबारा अपलोड करें।
  • खाली दस्तावेज़ से शुरू करें: अनुबंध को Document मोड में लिखें।

कंटेंट संपादन

Section titled “कंटेंट संपादन”

डिज़ाइनर का कंटेंट संपादित करें मोड अपलोड की गई फ़ाइल को छुए बिना वह बदल देता है जो हस्ताक्षरकर्ता देखते हैं। इसका डिफ़ॉल्ट टूल, टेक्स्ट संपादित करें, पेज के टेक्स्ट ब्लॉक हाइलाइट करता है (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 के रूप में रखी जाती है, और अगला ड्राफ़्ट उन्हीं संपादनों के साथ उसी से शुरू होता है। व्हाइट-आउट कंटेंट को सिर्फ़ देखने में ढकता है; मूल टेक्स्ट फ़ाइल में नीचे मौजूद रहता है, इसलिए यह सुरक्षित रिडैक्शन नहीं है।

भूमिकाएँ

Section titled “भूमिकाएँ”

भूमिकाएँ अनुबंध के पक्ष हैं। लिफ़ाफ़े के प्राप्तकर्ता 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 कोड अभी डिलीवर नहीं होते।

फ़ील्ड

Section titled “फ़ील्ड”
{
  "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।

वेरिएबल

Section titled “वेरिएबल”

किसी वर्ज़न का 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 से टेम्पलेट बनाना

Section titled “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 फ़ील्ड में विकल्प हों, एक्सप्रेशन पार्स हों। समस्याएँ 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 होता है।