מעטפות ונמענים

מעטפה היא חוזה אחד בדרך לחתימה: גרסת תבנית שרונדרה עם המשתנים שלכם, הנמענים שפועלים עליה, והראיות לכל מה שקורה. יוצרים מעטפה באמצעות POST /v1/envelopes.

יצירת מעטפה

שדה	סוג	הערות
template	tpl_…	חובה
version	מספר או "latest"	ברירת מחדל latest; נקבע ומקובע בזמן היצירה. חייבת להיות גרסה שפורסמה
variables	אובייקט	מאומת מול ה-JSON Schema של הגרסה
recipients	מערך	אחד לכל תפקיד (role, name, email; אופציונלית externalUserId, verification, fields למילוי מראש לפי מזהה שדה, order כדי לשנות את סדר החתימה)
subject, message	מחרוזת	משמשים באימיילים של החתימה ומוצגים בדף החתימה
delivery	email · embedded · none	ברירת מחדל email
expiresAt	RFC 3339	חייב להיות בעתיד; תוקף המעטפה פג במועד זה, וקישורי החתימה והצפייה מפסיקים לפעול
cc	מערך	נמעני CC נוספים (name, email) מעבר לתפקידי ה-CC של התבנית; עד 50
viewers	מערך	אנשים שעוקבים אחרי המעטפה בלי לחתום (name, email, אופציונלית notifyOnSignature); מספרם לכל מעטפה מוגבל לפי התוכנית
viewerDocumentAccess	בוליאני	מאפשר לצופים לפתוח את המסמך בדף הסטטוס שלהם. ברירת מחדל false (סטטוס בלבד); מתוכנית Team ומעלה
reminders	אובייקט	{ "enabled": false } מכבה את התזכורות; { "enabled": true, "intervalHours": 24 } משנה את המרווח (1 עד 720)
externalId	מחרוזת	מזהה משלכם, עד 200 תווים
dedupeOn	"external_id"	מחזיר את המעטפה הקיימת עם ה-externalId הזה במקום ליצור מעטפה נוספת
metadata	אובייקט של מחרוזות	עד 500 תווים לכל ערך; מוחזר עם המעטפה וב-webhooks

כל נמען צריך תפקיד מהגרסה; כל תפקיד שאינו CC צריך בדיוק נמען אחד. השגיאות מדווחות יחד, עם מצביעים כמו /recipients/1/role או /recipients/0/fields/start_date.

תגובות: 201 עם המעטפה וכותרת Location; 200 עם המעטפה הקיימת ו-x-deduplicated: true כש-dedupeOn מצא התאמה; 200 עם סיכום הרצת ניסיון עבור ?dry_run=true; 402 כשסביבת עבודה בתוכנית Free ניצלה את המעטפות הכלולות בה; 403 plan-upgrade-required כשהצופים חורגים מהמכסה של התוכנית או כש-viewerDocumentAccess לא כלול בתוכנית (תוכניות ומגבלות). גם הרצות ניסיון בודקות את מגבלות התוכנית.

כל שדה שנוסף אחרי הגרסה הראשונה הוא אופציונלי: בקשה בלעדיהם מתנהגת בדיוק כמו קודם.

אפשרויות בזמן השליחה

התבנית מגדירה מי חותם ובאיזה סדר. עבור מעטפה אחת אפשר לשנות זאת בלי לגעת בתבנית:

{
  "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 נדחות כי הן עדיין לא זמינות. ראו אימות החותם.
• שפה: locale בנמען, ב-CC או בצופה (או במעטפה, עבור כל מי שאין לו ערך משלו) קובע את השפה של דף החתימה והאימיילים שלו, אחת מ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, ולכן גם באישור.

התגובות של מעטפה בודדת (יצירה, קבלה, ביטול) מפרטות אותם:

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

מלבד סוגי האירועים של webhook, היומן כולל רשומות לביקורת בלבד כמו session.created, recipient.verified, recipient.reminded ואירועי הצופים (סוג המבצע viewer כשצופה פותח את הדף שלו).

לסטטוס בזמן אמת בממשק משתמש, GET /v1/envelopes/{id}/events/stream הוא זרם אירועים שנשלחים מהשרת (SSE): שם האירוע של כל מסגרת הוא ה-type של האירוע והמזהה שלה הוא ה-seq; מתחברים מחדש עם Last-Event-ID כדי להמשיך.

הצגת רשימות

GET /v1/envelopes מסנן לפי status, seal, template ו-q (טקסט חופשי בשמות הנמענים ובכתובות האימייל שלהם, ב-externalId ובמזהה המעטפה). כמו כל רשימה, היא מחולקת לעמודים באמצעות סמן (cursor):

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

מעבירים את nextCursor בחזרה בתור cursor; limit הוא 1 עד 100 (ברירת מחדל 20).

Tip

כדאי לשמור את ה-id של המעטפה (או להשתמש ב-externalId) אצלכם, ולהגיב ל-webhooks במקום לבצע תשאול חוזר.