لفافے اور وصول کنندگان

لفافہ ایک ایسا معاہدہ ہے جو دستخط کے مراحل سے گزر رہا ہو: آپ کے ویری ایبلز کے ساتھ رینڈر کیا گیا ٹیمپلیٹ کا ایک ورژن، وہ وصول کنندگان جو اس پر کارروائی کرتے ہیں، اور جو کچھ بھی ہوتا ہے اس کا ثبوت۔ لفافہ 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 حروف؛ لفافے پر اور webhooks میں واپس آتا ہے

ہر وصول کنندہ کو ورژن کا کوئی کردار درکار ہے؛ 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 زبانوں میں سے ایک ہو۔ اس کے بغیر دستخط کا صفحہ براؤزر کی زبان اختیار کرتا ہے اور ای میلز انگریزی میں ہوتی ہیں۔

ڈیش بورڈ کی بھیجنے والی اسکرین یہی اختیارات دیتی ہے: مراحل کو آگے یا پیچھے کریں، Sign at the same time پر نشان لگائیں، CCs اور ناظرین شامل کریں، ہر دستخط کنندہ کی توثیق (Email link only یا Email link + code) اور زبان منتخب کریں، اور میعاد کی تاریخ اور یاد دہانیوں کا شیڈول مقرر کریں۔

ڈیلیوری

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} کسی ناظر کی رسائی منسوخ کرتا ہے: اسے بھیجا گیا ہر لنک فوراً کام کرنا بند کر دیتا ہے۔
لنکس ذاتی capability URLs ہیں۔ ہر لنک ٹوکن کا صرف SHA-256 محفوظ کیا جاتا ہے۔ لنک لفافے کی میعاد ختم ہونے تک (زیادہ سے زیادہ 90 دن)، لفافہ ختم ہونے کے بعد 30 دن تک کام کرتا ہے، اور ناظر کی رسائی منسوخ ہونے کے بعد کبھی نہیں۔
شامل کرنا، کھولنا (صفحے اور دستاویز کو پہلی بار دیکھنا) اور منسوخ کرنا آڈٹ ٹریل میں viewer.added، viewer.viewed، viewer.document_viewed اور viewer.revoked کے طور پر ریکارڈ ہوتے ہیں، اور یوں سرٹیفکیٹ پر بھی۔

ایک لفافے والے جوابات (بنانا، حاصل کرنا، کالعدم کرنا) ان کی فہرست دیتے ہیں:

{
  "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 چونسٹھ صفر ہوتا ہے۔ 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 }
}

webhook ایونٹ کی اقسام کے علاوہ، ٹریل میں صرف آڈٹ کے اندراجات بھی ہوتے ہیں، جیسے session.created، recipient.verified، recipient.reminded اور ناظرین کے ایونٹس (جب کوئی ناظر اپنا صفحہ کھولے تو actor kind viewer ہوتا ہے)۔

UI میں براہ راست اسٹیٹس کے لیے، GET /v1/envelopes/{id}/events/stream ایک server-sent events اسٹریم ہے: ہر فریم کے ایونٹ کا نام ایونٹ کا 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)۔