חיבור okdoc למערכת פריוריטי (Priority): מדריך מלא

מה החיבור עושה בפועל

החיבור עובד בשני כיוונים. הראשון: כשלקוח חותם על מסמך ב-okdoc, ה-PDF החתום (עם תעודת הביקורת) נשמר אוטומטית בנספחים של הרשומה המתאימה ב-Priority, למשל בהזמנת הלקוח. השני: כשרשומה ב-Priority מגיעה לסטטוס שבחרתם, למשל הזמנה שאושרה לשליחה, okdoc שולח ללקוח את המסמך לחתימה במייל או בוואטסאפ. אף אחד לא מקליד פרטים פעמיים, ואף חוזה חתום לא נשאר שכוח בתיבת הדואר.

מה צריך לפני שמתחילים

בצד של okdoc: מסלול שכולל גישת API, כיום AGENCY, כי רק בו אפשר ליצור מפתח API. בצד של Priority: גרסה 17.2 ומעלה לכתיבת נתונים דרך ה-API, גרסה 19.1 ומעלה לאסימון גישה אישי (PAT), גרסה 21.0 ומעלה לצירוף קבצים, ומודול Webhooks אם רוצים גם את הכיוון השני. ובאמצע: מחבר שמקבל הודעה מצד אחד ופונה לצד השני. זה יכול להיות תרחיש ב-Make או ב-Zapier, תהליך ב-n8n או פונקציה קצרה בשרת שלכם.

שלב 1: מפתח API ב-okdoc

באפליקציה של okdoc פותחים את מסך המפתחים (Developers) ויוצרים מפתח חדש. המפתח מתחיל ב-ok_live_ ומוצג פעם אחת בלבד, אז שומרים אותו מיד במחבר, במקום מאובטח. כל פנייה ל-API של okdoc נשלחת עם הכותרת Authorization: Bearer ואחריה המפתח.

שלב 2: אסימון גישה ב-Priority

ב-Priority מגדירים אסימון גישה אישי (Personal Access Token) בטופס REST Interface Access Tokens, עבור משתמש שיש לו הרשאה לטפסים שהחיבור צריך. הפניות ל-Priority נשלחות באימות Basic: שם המשתמש הוא האסימון, והסיסמה היא פשוט המילה PAT. כתובת הבסיס של ה-API ייחודית לכל התקנה, ואיש ה-Priority שלכם יודע מהי.

שלב 3: הודעה מ-okdoc ברגע החתימה

באותו מסך מפתחים מוסיפים Webhook לכתובת ה-HTTPS של המחבר ומסמנים את האירוע document.signed. okdoc שולח רק לכתובות HTTPS, כי ההודעה כוללת את שם החותם ואת המייל שלו. לכל Webhook יש סוד שמתחיל ב-whsec_, ו-okdoc חותם בו כל הודעה: הכותרת X-OKDOC-Signature מכילה HMAC-SHA256 של גוף ההודעה. המחבר מחשב את אותו ערך ודוחה כל הודעה שלא תואמת. כך נראית ההודעה, וכך בודקים אותה:

POST https://your-connector.example.com/okdoc
X-OKDOC-Event: document.signed
X-OKDOC-Signature: <HMAC-SHA256 hex of the raw body, keyed with whsec_...>

{
  "event": "document.signed",
  "created_at": "2026-10-19T09:12:44.120Z",
  "data": {
    "document": { "id": "6f1c...", "title": "Order SO26000123", "status": "signed", "locale": "he" },
    "recipient": { "name": "Dana Levi", "email": "dana@example.com" }
  }
}

// Node.js: reject anything that was not signed with your webhook secret
import { createHmac, timingSafeEqual } from "crypto";
const expected = Buffer.from(createHmac("sha256", process.env.OKDOC_WEBHOOK_SECRET).update(rawBody).digest("hex"));
const received = Buffer.from(req.headers["x-okdoc-signature"] ?? "");
const valid = received.length === expected.length && timingSafeEqual(received, expected);

שלב 4: הורדת העותק החתום

ההודעה עצמה לא כוללת את הקובץ, רק את מזהה המסמך. המחבר פונה ל-okdoc עם המזהה ומקבל את הסטטוס, את פרטי החותם, את יומן האירועים וקישור להורדת ה-PDF החתום. הקישור תקף לשעה, ולכן מורידים את הקובץ מיד ולא שומרים את הקישור עצמו.

GET https://okdocai.com/api/v1/documents/6f1c...
Authorization: Bearer ok_live_...

200 OK
{
  "id": "6f1c...",
  "title": "Order SO26000123",
  "status": "signed",
  "signed_at": "2026-10-19T09:12:41Z",
  "signed_pdf_url": "https://...   (valid for one hour)",
  "recipient": { "name": "Dana Levi", "email": "dana@example.com", "status": "signed" },
  "events": [ { "type": "...", "at": "..." } ]
}

שלב 5: צירוף ה-PDF לרשומה ב-Priority

ב-Priority מצרפים קובץ דרך טופס הנספחים של הרשומה (EXTFILES_SUBFORM): שולחים את הקובץ כ-data URL בקידוד base64. מגרסה 22.0 אפשר להוסיף את השדה SUFFIX עם הסיומת .pdf, ו-Priority ישתמש בה במקום לזהות את הקובץ לפי הסוג שלו. הדוגמה מצרפת את הקובץ להזמנת לקוח, ובאותה דרך מצרפים לכל טופס שיש לו נספחים.

POST {serviceRoot}/ORDERS('SO26000123')/EXTFILES_SUBFORM
Authorization: Basic base64("<your PAT>:PAT")
Content-Type: application/json

{
  "EXTFILEDES": "Signed via okdoc",
  "EXTFILENAME": "data:application/pdf;base64,JVBERi0xLjcK...",
  "SUFFIX": ".pdf"
}

// serviceRoot looks like: https://<server>/odata/Priority/<tabula.ini>/<company>

איך המחבר יודע לאיזו רשומה לצרף

צריך דרך לזהות את הרשומה ב-Priority מתוך המסמך ב-okdoc. הדרך הפשוטה: לכלול את מספר הרשומה בכותרת המסמך, למשל "הזמנה SO26000123", והמחבר שולף אותו מהכותרת. הדרך המדויקת יותר: כשהמסמך נוצר מתוך Priority (הכיוון השני), המחבר שומר את מזהה המסמך שחזר מ-okdoc יחד עם מספר הרשומה, וכשמגיעה הודעת החתימה הוא יודע בדיוק לאן לשייך אותה.

הכיוון השני: Priority שולח מסמך לחתימה

ב-Priority מגדירים את כתובת המחבר בטופס Webhook Definitions (במסלול System Management > System Maintenance > Periodic Maintenance > BPM Maintenance) ויוצרים אסימון אימות. האסימון מוסתר ברגע שעוזבים את השורה, אז מעתיקים אותו מיד. אחר כך מוסיפים כלל עסקי או כלל BPM לסטטוס הרצוי, בוחרים בפעולה Webhook וממלאים בגוף ההודעה את השדות שיישלחו: מספר הרשומה, שם הלקוח, המייל והטלפון שלו. Priority שולח את האסימון בכותרת priority-bpm-token, והמחבר מוודא שהוא תואם. משם המחבר פונה ל-okdoc: עם PDF שהופק מ-Priority הוא משתמש בנתיב ההעלאה, שמוסיף בלוק חתימה ושולח ללקוח קישור במייל, בוואטסאפ או בשניהם. בלי קובץ, אפשר ליצור מסמך טקסט דרך POST /api/v1/documents.

// What Priority sends (header priority-bpm-token carries your webhook token).
// The fields are the ones you put in the business rule message, for example:
{ "ORDERS": { "ORDNAME": "SO26000123", "CDES": "Dana Levi" } }

// Your connector then sends the PDF to okdoc for signature:
POST https://okdocai.com/api/v1/documents/upload
Authorization: Bearer ok_live_...
Content-Type: multipart/form-data

file             = SO26000123.pdf
title            = Order SO26000123
recipient_name   = Dana Levi
recipient_email  = dana@example.com      (optional: emails the signing link)
recipient_phone  = +972501234567         (optional: WhatsApps the signing link)

201 Created
{ "id": "6f1c...", "status": "sent", "signing_url": "https://...", "emailed": true, "whatsapped": true }

בונוס: סכום העסקה בדוחות של okdoc

okdoc מציג לכל מסמך את שווי העסקה ואת הכסף שעדיין פתוח. אם הסכום כבר קיים ב-Priority, המחבר מעדכן אותו במסמך, גם אחרי שהמסמך נשלח או נחתם.

PATCH https://okdocai.com/api/v1/documents/6f1c...
Authorization: Bearer ok_live_...
Content-Type: application/json

{ "deal_amount": 12500 }

מה לבדוק לפני שעוברים לעבודה שוטפת

שלחו לעצמכם מסמך בדיקה, חתמו עליו, ובדקו שה-PDF הופיע בנספחים של הרשומה הנכונה. תעדו במחבר כל הודעה שהתקבלה וכל פנייה שנכשלה, כדי שתקלה לא תעבור בשקט. ב-Priority, מגרסה 26.0, יש גם יומן שגיאות ל-Webhooks. שמרו את המפתחות רק במחבר, לעולם לא בדפדפן או בקוד גלוי, ותנו למשתמש ה-API ב-Priority הרשאות רק לטפסים שהוא באמת צריך.

שאלות נפוצות