תבניות, תפקידים ושדות

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

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

המזהים הם מחרוזות עם קידומת (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); חותמות הזמן הן בפורמט RFC 3339 לפי UTC.

שתי דרכים לכתוב תבנית

מצב שכבת-על (source: "pdf") מתחיל ממסמך שהועלה. השדות הם מלבנים שממוקמים על העמודים שלו ביחידות נקודות PDF (1/72 אינץ’), כשנקודת הראשית בפינה השמאלית העליונה של העמוד, ואינדקס העמודים מתחיל ב-0. קובץ .docx שמועלה מומר ל-PDF פעם אחת (באמצעות LibreOffice, תוך שמירה על הפריסה של Word; גופנים שהקובץ לא מטמיע עשויים להיות מוחלפים), ומאותו רגע הוא PDF כמו כל PDF אחר: הקובץ מדווח convertedFrom: "docx". גרסאות שכבת-על יכולות לכלול גם עריכות תוכן (טקסט שנערך במקומו, כיסוי לבן, תיבות טקסט, תמונות, פעולות על עמודים) שמוחלות כשהגרסה מתפרסמת.

מצב מסמך (source: "document") שומר את החוזה עצמו כטקסט עשיר (ProseMirror JSON) עם שבבי משתנים כמו {{client.name}}, בלוקי שדות בתוך הטקסט, מקטעים מותנים (נשמרים רק כשביטוי showIf מתקיים) ומקטעים ושורות טבלה חוזרים (אחד לכל פריט במשתנה מסוג מערך). כל מעטפה מרנדרת PDF משלה, ומיקומי השדות נקראים מהרינדור הזה. בלוח הבקרה, מצב מסמך הוא “התחלה ממסמך ריק”. דרך ה-API אפשר גם לייבא קובץ Word למצב מסמך באמצעות POST /v1/templates/{id}/import: תגיות {{tags}} הופכות למשתנים או לשדות, ושורות חתימה (“Signature: ____”, “By: ____”, “Date: ____”) הופכות לבלוקי שדות.

בלוח הבקרה

תבנית חדשה מציעה שתי נקודות התחלה:

• העלאת מסמך: אזור גרירה אחד לקובצי .pdf ו-.docx בגודל של עד 25 MB. קובצי Word מומרים ל-PDF ונפתחים בעורך עם תזכורת לבדוק את הפריסה שהומרה לפני מיקום השדות. תיקונים קטנים נעשים במקום על ה-PDF (“עריכת תוכן”); לשכתוב גדול יותר, משנים את קובץ ה-Word ומעלים אותו שוב.
• התחלה ממסמך ריק: כותבים את החוזה במצב מסמך.

עריכות תוכן

מצב עריכת תוכן בעורך משנה את מה שהחותמים רואים בלי לגעת בקובץ שהועלה. כלי ברירת המחדל שלו, עריכת טקסט, מדגיש את בלוקי הטקסט של העמוד (שורות ופסקאות שמקובצות משכבת הטקסט של ה-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 אם הוא יכול לצייר כל תו בטקסט החדש, ואחרת גופן מצורף שתואם במידות (sans Arimo במקום Helvetica/Arial, serif Tinos במקום Times, mono Cousine במקום Courier, carlito Carlito במקום Calibri) במשקל ובסגנון התואמים. הטקסט נשבר לשורות בתוך הבלוק; כשהוא צריך יותר שורות מהמקור, העריכה מתרחבת לשטח הפנוי שמתחתיו, והעורך מסרב לשמור אותה כשאין שטח כזה (“הטקסט לא נכנס — יש לקצר אותו או להוסיף מקום”). העורך וה-API חולקים את קוד הפריסה והגופנים, כך שה-PDF שמתפרסם תואם את התצוגה המקדימה שורה אחר שורה.

עריכות יכולות לשנות רק טיוטה. הפרסום מחיל אותן על PDF בסיס חדש שה-SHA-256 שלו הוא ה-documentHash של הגרסה (הגיבוב של מה שהחותמים רואים); המקור שהועלה נשמר בתור ה-sourceFile של הגרסה, והטיוטה הבאה מתחילה ממנו עם אותן עריכות. כיסוי לבן מסתיר תוכן ויזואלית; הטקסט המקורי נשאר בקובץ מתחתיו, ולכן זו אינה השחרה (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) כדי לקשור את השדה או למלא אותו מראש;
• options עבור radio ו-dropdown;
• validation: pattern, min, max, maxLength, או format (email, phone, date, number, currency);
• showIf: תנאי על משתנים ועל שדות אחרים, כמו plan != "free";
• formula: ערך מחושב לקריאה בלבד;
• overflow: מה לעשות כשערך לא נכנס בתיבה: shrink (ברירת מחדל), wrap או reject.

משתנים

ה-variables של גרסה הוא JSON Schema (טיוטה 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. POST /v1/templates עם { "name": "Mutual NDA" }.
2. POST /v1/templates/{id}/files עם ה-PDF (או ה-.docx) בתור הגוף (Content-Type: application/pdf) או בתור שדה ה-multipart file. עד 25 MB. התגובה כוללת את מזהה הקובץ (tfl_…), מספר העמודים וגודלי העמודים.
3. PUT /v1/templates/{id}/draft עם roles, fields, variables (ו-file, או source: "document" עם content). טיוטות נשמרות כמו שהן; עדיין לא נבדק דבר.
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.