लिफ़ाफ़े और प्राप्तकर्ता

लिफ़ाफ़ा हस्ताक्षर की ओर बढ़ता हुआ एक अनुबंध है: आपके वेरिएबल के साथ रेंडर किया गया एक टेम्पलेट वर्ज़न, उस पर कार्रवाई करने वाले प्राप्तकर्ता, और जो कुछ भी होता है उसका साक्ष्य। इसे POST /v1/envelopes से बनाएँ।

लिफ़ाफ़ा बनाना

फ़ील्ड	प्रकार	टिप्पणी
template	tpl_…	आवश्यक
version	संख्या या "latest"	डिफ़ॉल्ट latest; बनाते समय तय और पिन किया जाता है। पब्लिश होना ज़रूरी है
variables	ऑब्जेक्ट	वर्ज़न के JSON Schema के अनुसार जाँचा जाता है
recipients	ऐरे	हर भूमिका के लिए एक (role, name, email; वैकल्पिक externalUserId, verification, फ़ील्ड id के अनुसार पहले से भरने के लिए fields, हस्ताक्षर का क्रम बदलने के लिए order)
subject, message	स्ट्रिंग	हस्ताक्षर ईमेल में इस्तेमाल होते हैं और हस्ताक्षर पेज पर दिखते हैं
delivery	email · embedded · none	डिफ़ॉल्ट email
expiresAt	RFC 3339	भविष्य का समय होना चाहिए; उस समय लिफ़ाफ़े की समय-सीमा समाप्त हो जाती है, और हस्ताक्षर व व्यूअर लिंक काम करना बंद कर देते हैं
cc	ऐरे	टेम्पलेट की CC भूमिकाओं के अलावा अतिरिक्त CC प्राप्तकर्ता (name, email); अधिकतम 50
viewers	ऐरे	वे लोग जो हस्ताक्षर किए बिना लिफ़ाफ़े पर नज़र रखते हैं (name, email, वैकल्पिक notifyOnSignature); प्रति लिफ़ाफ़ा संख्या प्लान के अनुसार सीमित
viewerDocumentAccess	बूलियन	व्यूअर को अपने स्टेटस पेज पर दस्तावेज़ खोलने दें। डिफ़ॉल्ट false (सिर्फ़ स्टेटस); Team प्लान और उससे ऊपर
reminders	ऑब्जेक्ट	{ "enabled": false } रिमाइंडर बंद करता है; { "enabled": true, "intervalHours": 24 } अंतराल बदलता है (1 से 720)
externalId	स्ट्रिंग	आपकी अपनी id, अधिकतम 200 वर्ण
dedupeOn	"external_id"	नया लिफ़ाफ़ा बनाने के बजाय इस externalId वाला मौजूदा लिफ़ाफ़ा लौटाएँ
metadata	स्ट्रिंग का ऑब्जेक्ट	हर मान अधिकतम 500 वर्ण; लिफ़ाफ़े पर और वेबहुक में लौटाया जाता है

हर प्राप्तकर्ता को वर्ज़न की कोई भूमिका चाहिए; हर गैर-CC भूमिका के लिए ठीक एक प्राप्तकर्ता चाहिए। एरर एक साथ बताए जाते हैं, /recipients/1/role या /recipients/0/fields/start_date जैसे पॉइंटर के साथ।

रिस्पॉन्स: लिफ़ाफ़े और Location हेडर के साथ 201; dedupeOn मेल खाने पर मौजूदा लिफ़ाफ़े और x-deduplicated: true के साथ 200; ?dry_run=true के लिए ड्राई-रन सारांश के साथ 200; जब किसी Free वर्कस्पेस ने अपने शामिल लिफ़ाफ़े इस्तेमाल कर लिए हों तो 402; जब व्यूअर प्लान की सीमा से ज़्यादा हों या viewerDocumentAccess प्लान में शामिल न हो तो 403 plan-upgrade-required (प्लान और सीमाएँ)। ड्राई रन भी प्लान की सीमाएँ जाँचते हैं।

पहली रिलीज़ के बाद जोड़ा गया हर फ़ील्ड वैकल्पिक है: इनके बिना भेजा गया अनुरोध ठीक पहले जैसा ही व्यवहार करता है।

भेजते समय के विकल्प

टेम्पलेट तय करता है कि कौन किस क्रम में हस्ताक्षर करेगा। किसी एक लिफ़ाफ़े के लिए आप टेम्पलेट को छुए बिना इसे बदल सकते हैं:

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

• क्रम: recipients[].order वह चरण है जिसमें प्राप्तकर्ता हस्ताक्षर करता है; एक ही संख्या वाले प्राप्तकर्ता एक साथ हस्ताक्षर करते हैं। इसके बिना टेम्पलेट से भूमिका का order लागू होता है। क्रम धनात्मक पूर्णांक होते हैं; CC भूमिकाओं का क्रम तय नहीं किया जा सकता; हर भूमिका को अब भी अपना प्राप्तकर्ता चाहिए (ताकि टेम्पलेट के फ़ील्ड का हस्ताक्षरकर्ता बना रहे); कम से कम एक प्राप्तकर्ता का हस्ताक्षर करना ज़रूरी है। envelope.created इवेंट में routingOverridden: true दर्ज होता है।
• CC: अतिरिक्त CC प्राप्तकर्ताओं को पूरे हुए दस्तावेज़ का ईमेल मिलता है और वे कभी हस्ताक्षर नहीं करते। वे recipients में kind: "cc" और भूमिका _cc के साथ दिखते हैं।
• रिमाइंडर: जिसकी बारी है, उसे हर intervalHours पर याद दिलाया जाता है (डिफ़ॉल्ट: डिप्लॉयमेंट का REMINDER_INTERVAL_HOURS, 72), अधिकतम तीन बार; enabled: false कोई रिमाइंडर नहीं भेजता। रिमाइंडर email डिलीवरी पर लागू होते हैं।
• हस्ताक्षरकर्ता का ऑथेंटिकेशन हर प्राप्तकर्ता के लिए अलग होता है: verification भूमिका के तरीके को ओवरराइड करता है। none (सिर्फ़ यूनिक हस्ताक्षर लिंक, उन भूमिकाओं के लिए डिफ़ॉल्ट जो कोई तरीका तय नहीं करतीं) और email_otp (लिंक के साथ ईमेल किया गया कोड) आज उपलब्ध हैं; passkey और id_check अभी उपलब्ध न होने के कारण अस्वीकार किए जाते हैं। हस्ताक्षरकर्ता सत्यापन देखें।
• भाषा: किसी प्राप्तकर्ता, CC या व्यूअर पर locale (या लिफ़ाफ़े पर, उन सबके लिए जिनकी अपनी भाषा तय नहीं है) उनके हस्ताक्षर पेज और ईमेल की भाषा तय करता है, जो 50 हस्ताक्षर भाषाओं में से एक होती है। इसके बिना हस्ताक्षर पेज ब्राउज़र की भाषा अपनाता है और ईमेल अंग्रेज़ी में होते हैं।

डैशबोर्ड की भेजने वाली स्क्रीन में भी यही विकल्प हैं: चरणों को आगे या पीछे करें, एक साथ हस्ताक्षर करें पर टिक करें, CC और व्यूअर जोड़ें, हर हस्ताक्षरकर्ता का ऑथेंटिकेशन (सिर्फ़ ईमेल लिंक या ईमेल लिंक + कोड) और भाषा चुनें, और समय-सीमा की तारीख व रिमाइंडर का शेड्यूल सेट करें।

डिलीवरी

• email: हर प्राप्तकर्ता को उसकी बारी आने पर होस्ट किए गए हस्ताक्षर पेज का लिंक ईमेल किया जाता है। जिन प्राप्तकर्ताओं ने हस्ताक्षर नहीं किए हैं, उन्हें हर कुछ दिनों में एक रिमाइंडर मिलता है (अधिकतम तीन), और लिफ़ाफ़ा पूरा होने पर सभी को ईमेल किया जाता है।
• embedded: हस्ताक्षरकर्ताओं को कोई ईमेल नहीं। जब हस्ताक्षरकर्ता आपके प्रोडक्ट में हो, तब एक हस्ताक्षर सेशन बनाएँ। व्यूअर को उनका स्टेटस लिंक तब भी ईमेल किया जाता है।
• none: कोई ईमेल नहीं (व्यूअर को भी नहीं); इसका इस्तेमाल तब करें जब आप लिंक ख़ुद पहुँचाते हैं (होस्टेड सेशन)।

POST /v1/envelopes/{id}/recipients/{recipient}/resend उस प्राप्तकर्ता को नया लिंक ईमेल करता है जिसकी बारी है (अधिकतम एक मिनट में एक बार)।

जीवनचक्र

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

status	अर्थ
rendering	तैयार किया जा रहा है
sent	प्रगति में: प्राप्तकर्ता रूटिंग क्रम में हस्ताक्षर कर रहे हैं
completed	हर प्राप्तकर्ता ने अपना काम पूरा कर लिया। सीलिंग शुरू होती है
declined	किसी प्राप्तकर्ता ने मना कर दिया; लिफ़ाफ़ा समाप्त हो जाता है
voided	आपने इसे रद्द किया ({ "reason": "…" }); खुले हस्ताक्षर सेशन काम करना बंद कर देते हैं
expired	पूरा होने से पहले expiresAt बीत गया

seal सील किए गए PDF की स्थिति बताता है: not_started, pending (पूरा हो चुका, सील हो रहा है), sealed, या failed। सीलिंग कभी पूरा होने में रुकावट नहीं डालती: लिफ़ाफ़ा पहले पूरा होता है और उसके तुरंत बाद सील होता है।

प्राप्तकर्ता और रूटिंग

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

प्राप्तकर्ता का status pending (अभी उसकी बारी नहीं), sent, viewed, completed या declined होता है, और kind भूमिका का signer, approver, form_filler या cc होता है। रूटिंग order के अनुसार होती है (भूमिका का, या भेजते समय का ओवरराइड): सबसे कम अधूरे क्रम वाले सभी प्राप्तकर्ता एक साथ कार्रवाई करते हैं, और उनके पूरा करने पर अगला समूह शुरू होता है। CC प्राप्तकर्ता कभी रूटिंग नहीं रोकते।

व्यूअर

व्यूअर हस्ताक्षर किए बिना किसी लिफ़ाफ़े पर नज़र रखता है: कोई मैनेजर, पैरालीगल, या ग्राहक की ओर से अकाउंट का मालिक। व्यूअर प्राप्तकर्ता नहीं होते। उनकी न कोई भूमिका होती है न बारी, वे न कभी कुछ रोकते हैं न पूरा करते हैं, और प्रमाणपत्र में हस्ताक्षरकर्ताओं की सूची में कभी नहीं दिखते।

• जब लिफ़ाफ़ा भेजा जाता है (या जब आप उन्हें बाद में POST /v1/envelopes/{id}/viewers से जोड़ते हैं), तो हर व्यूअर को एक ब्रांडेड ईमेल मिलता है, जिसमें एक सिर्फ़ पढ़ने योग्य स्टेटस पेज का लिंक होता है: लिफ़ाफ़े का शीर्षक, भेजने वाला, और हर चरण के प्राप्तकर्ताओं के नाम, भूमिकाएँ, स्थिति और टाइमस्टैम्प, जो लोगों के हस्ताक्षर करते ही लाइव अपडेट होते हैं। प्राप्तकर्ताओं के ईमेल पते नहीं दिखाए जाते।
• लिफ़ाफ़ा पूरा होने, अस्वीकार होने या रद्द होने पर व्यूअर को फिर से ईमेल किया जाता है, और अगर notifyOnSignature true हो (डिफ़ॉल्ट रूप से बंद), तो हर हस्ताक्षर के बाद भी।
• दस्तावेज़ पेज पर तभी होता है जब आप viewerDocumentAccess: true सेट करते हैं (Team प्लान और उससे ऊपर): प्रगति के दौरान मूल दस्तावेज़, और सील होने के बाद सील किया गया PDF। वरना व्यूअर सिर्फ़ स्टेटस देखते हैं।
• DELETE /v1/envelopes/{id}/viewers/{viewer} किसी व्यूअर की पहुँच रद्द करता है: उन्हें भेजा गया हर लिंक तुरंत काम करना बंद कर देता है।
• लिंक व्यक्तिगत कैपेबिलिटी URL होते हैं। हर लिंक टोकन का सिर्फ़ SHA-256 संग्रहीत किया जाता है। लिंक तब तक काम करता है जब तक लिफ़ाफ़े की समय-सीमा समाप्त न हो (अधिकतम 90 दिन), लिफ़ाफ़ा पूरा होने के बाद 30 दिन तक, और व्यूअर की पहुँच रद्द होने के बाद कभी नहीं।
• जोड़ना, खोलना (पेज और दस्तावेज़ को पहली बार देखना) और पहुँच रद्द करना ऑडिट ट्रेल में viewer.added, viewer.viewed, viewer.document_viewed और viewer.revoked के रूप में दर्ज होते हैं, और इसलिए प्रमाणपत्र पर भी।

एकल लिफ़ाफ़े वाले रिस्पॉन्स (create, get, void) उन्हें सूचीबद्ध करते हैं:

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

प्रति लिफ़ाफ़ा व्यूअर की संख्या प्लान पर निर्भर करती है (Free 1, Pay-as-you-go 2, Team 5, Business 20, Platform असीमित); CC प्राप्तकर्ता इसमें नहीं गिने जाते। जिन व्यूअर की पहुँच रद्द की गई है, उनकी जगह खाली हो जाती है।

दस्तावेज़

GET /v1/envelopes/{id}/document?version=… एक PDF डाउनलोड करता है, जिसका SHA-256 x-document-sha256 में होता है:

version	फ़ाइल
original (डिफ़ॉल्ट)	रेंडर किया गया दस्तावेज़, जैसा हस्ताक्षर के लिए भेजा गया था
sealed	अंतिम PDF: मान फ़्लैट किए गए, पूर्णता प्रमाणपत्र जोड़ा गया, दस्तावेज़ टाइमस्टैम्प। envelope.sealed के बाद
certificate	सिर्फ़ पूर्णता प्रमाणपत्र

लिफ़ाफ़े का documentHash मूल दस्तावेज़ का SHA-256 है और sealedDocumentHash सील की गई फ़ाइल का; सत्यापन इन्हीं को खोजता है।

ऑडिट ट्रेल

हर कार्रवाई हर लिफ़ाफ़े की अपनी हैश चेन में एक इवेंट होती है: hash = SHA-256(prevHash ‖ canonical JSON of the event), जिसमें पहला prevHash 64 शून्य होता है। GET /v1/envelopes/{id}/events इवेंट लौटाता है और चेन की जाँच करता है:

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

वेबहुक इवेंट प्रकारों के अलावा, ट्रेल में सिर्फ़ ऑडिट वाली एंट्री भी होती हैं, जैसे session.created, recipient.verified, recipient.reminded और व्यूअर इवेंट (जब कोई व्यूअर अपना पेज खोलता है, तो actor kind viewer होता है)।

UI में लाइव स्टेटस के लिए GET /v1/envelopes/{id}/events/stream एक सर्वर-सेंट इवेंट स्ट्रीम है: हर फ़्रेम का इवेंट नाम इवेंट का type होता है और उसकी id seq; फिर से शुरू करने के लिए Last-Event-ID के साथ दोबारा कनेक्ट करें।

सूची देखना

GET /v1/envelopes को status, seal, template और q (प्राप्तकर्ताओं के नाम और ईमेल, externalId और लिफ़ाफ़ा id में फ़्री टेक्स्ट खोज) से फ़िल्टर किया जा सकता है। हर सूची की तरह यह भी कर्सर से पेजिनेट होती है:

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

nextCursor को cursor के रूप में वापस भेजें; limit 1 से 100 तक होता है (डिफ़ॉल्ट 20)।

संकेत

लिफ़ाफ़े की id अपनी ओर सहेजें (या externalId इस्तेमाल करें), और बार-बार पोलिंग करने के बजाय वेबहुक पर प्रतिक्रिया दें।