למה משתמשים ב-API

ה-API למפתחים מחבר שרת משלכם ללידנייט. אפשר לקרוא קמפיינים, פוסטים, חשבונות, יעדים, מדיה, נתוני ביצועים ופעילות פרסום; לנהל אנשי קשר ב-CRM; להעלות מדיה; וליצור, לפרסם או לעצור פעילות קמפיין שנבדקה ואושרה, בכפוף להרשאות. זהו חיבור בין שרתים, בנפרד ממחבר ה-AI העתידי ל-Claude ול-ChatGPT.

כתובת הבסיס לפעולות היא https://api.lead-knight.com/v1. משאירים את הקידומת /v1 בבקשות למשאבים. במפרט ה-API מפורטים הנתיבים והשדות המדויקים. מסמך OpenAPI החי נמצא מחוץ ל-/v1, אינו דורש מפתח ואינו מכיל נתוני חשבון; הוא אינו זמין כשה-API למפתחים מושבת.

לפני שמתחילים

מתחברים לחשבון שהאינטגרציה אמורה לפעול בשמו, בוחרים סביבת עבודה ומוודאים שהתפקיד והמושב הנוכחיים מאפשרים את הפעולות הרצויות.
מכינים שרת ומנהל סודות או משתני סביבה פרטיים. לא שומרים מפתח בקוד JavaScript בדפדפן, באפליקציה לנייד, בכתובת URL, במאגר קוד, במערכת ניתוח שימוש או ביומנים.
בוחרים הרשאה מצומצמת ככל האפשר. המפתח שייך לחשבון ולסביבת עבודה מסוימים; הוא אינו מעניק הרשאת מנהל כללית לכל סביבת העבודה.
לפני פרסום מחברים ומאשרים את החשבונות, היעדים והנמענים בפועל. מפתח לא מעניק גישה לחשבון שלא שותף, הסכמת נמענים, הרשאת שולח או זכאות לפרסום בפלטפורמה.

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

יוצרים מפתח בהגדרות

פותחים הגדרות → API למפתחים. בודקים את כתובת הבסיס של ה-API, ולפי הצורך פותחים את תיעוד ה-API ‏(OpenAPI).
לוחצים על יצירת מפתח API. בחלון בודקים את סביבת עבודה לפני שממשיכים; כותרת בקשה לא תוכל להעביר את המפתח לסביבה אחרת בהמשך.
מזינים שם המפתח שמזהה את האפליקציה או השרת. נדרשים 1–100 תווים, ללא תווי בקרה או Unicode לא תקין. אם השם אינו תקין, מתקנים את השדה לפני היצירה.
תחת הרשאות בוחרים אחת מהרמות בטבלה הבאה. ברירת המחדל היא קריאה בלבד.
תחת תוקף המפתח בוחרים 30 ימים, 90 ימים, 180 ימים, שנה או ללא תפוגה. ברירת המחדל היא 90 ימים. גם מפתח ללא תפוגה מפסיק לפעול לאחר ביטול, אובדן חברות או שינוי הרשאות שמונע את הפעולה.
לוחצים על יצירת מפתח API. לאחר הצלחה מופיע זה הזמן לשמור את מפתח ה-API, כולל סביבת העבודה. השדה מפתח API להצגה חד־פעמית הוא ההזדמנות היחידה לראות את הסוד.
לוחצים על העתקת המפתח ושומרים בשרת באופן פרטי. אם ההעתקה נכשלת, מעתיקים ידנית מהשדה המסומן או מנסים שוב את הכפתור. לא סוגרים לפני השמירה.
לוחצים על שמרתי את המפתח. ב־מפתחות ה-API שלך בודקים שם, סביבת עבודה, הרשאות, תחילת המפתח וארבע הספרות או האותיות האחרונות, תוקף ושימוש אחרון. טעינת מפתחות נוספים מציגה את המשך הרשימה.

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

בוחרים תקרת הרשאה מתאימה

האפשרות בהגדרות	הערך ב-API	מה היא מאפשרת, בכפוף לגישה הנוכחית
קריאה בלבד	`read`	פעולות הקריאה הנתמכות, בלי העלאה, שינוי CRM או פרסום.
קריאה וכתיבה	`write`	גם קריאה, יצירה ועדכון של אנשי קשר והערות, העלאות, קמפיינים עצמאיים כטיוטה ופוסטים שטרם אושרו או התחילו.
קריאה, כתיבה ופרסום	`publish`	גם קריאה וכתיבה, פרסום מפורש, השהיה, חידוש, העברה לארכיון ושינויים בפעילות שכבר אושרה או התחילה.

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

שולחים בקשת קריאה ראשונה מהשרת

טוענים את המפתח ממאגר הסודות בצד השרת. המחרוזת מתחילה ב-lk_api_; לא מחליפים אותה באסימון כניסה לאפליקציה או באסימון MCP.
שולחים בקשת HTTPS מסוג GET אל https://api.lead-knight.com/v1/campaigns, עם הכותרת Authorization: Bearer <key>. מחליפים את מציין המקום באופן פרטי, ולא מכניסים מפתח לכתובת.
בודקים את קוד ה־HTTP, תשובת ה־JSON וכותרות מגבלת השימוש. תשובת רשימה מוצלחת כוללת items ו־nextCursor.
משאירים את השיוך לסביבת העבודה של המפתח. עדיף לא לשלוח X-Workspace-Id. ערך סותר גורם ל-400 workspace_mismatch, ולא מחליף סביבת עבודה.
ממשיכים לפעולת קריאה נוספת מהמפרט לפני שמפתחים שינוי או פרסום.

בקשות עם Origin,‏ Sec-Fetch-Site,‏ Sec-Fetch-Dest או Sec-Fetch-User נדחות ב-401 browser_request_not_allowed. זו הגנה מפני שימוש מקרי בדפדפן; לא פותרים אותה בהעברת המפתח למנגנון דפדפן אחר. מעבירים את הקריאה לשרת. כותרת Sec-Fetch-Mode לבדה, שנוספת לעיתים על ידי fetch בשרת, אינה גורמת לדחייה הזו.

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

מה אפשר לעשות ומה נשאר מחוץ ל-API

תחום	פעולות ותנאים
קמפיינים ופוסטים	קריאה, יצירת קמפיין עצמאי כטיוטה, יצירה או החלפה מלאה של פוסט שנבדק, שינוי שדות קמפיין מוגדרים, השהיה וחידוש של כל הכרטיסים או חלקם והעברה לארכיון. משתמשים במבנים המדויקים מהמפרט.
חשבונות ויעדים	איתור זהויות פייסבוק, חשבונות רשמיים מחוברים ויעדים מותרים. מזהה זהות פייסבוק אינו מזהה חשבון API רשמי. יעד קבוצה כולל את הזהויות שיכולות להגיע אליו.
מדיה	קריאת נכסים גלויים וניתנים לצירוף והעלאת קובץ יחיד בשדה multipart בשם `file`, ללא שדות נוספים. JPEG, PNG, WebP ו-GIF עד 10 MiB;‏ MP4 עד 256 MiB. נבדקים התוכן והסוג בפועל.
נתוני ביצועים ופעילות	ניתוח נתונים מחייב `from` ו-`to` בתאריך ושעה לפי ISO, כשהסיום מאוחר מההתחלה. לפעילות פרסום יש מסנני תאריך, תקופה ורשת ושדות המשך משלה.
CRM	קריאה, יצירה ועדכון של אנשי קשר גלויים; שינוי בעלות או בקשת העברה; יצירה ומחיקה של הערות; קריאת שלבים וחברי צוות. ביצירת איש קשר נדרש לפחות טלפון או אימייל. כללי פרטיות ונראות נשמרים.
אירועים יוצאים	עדכוני יצירה ועדכון של אנשי קשר ושינוי מצב קמפיין באמצעות Webhooks, שמגדירים בהגדרות.

אין כאן פעולות ליצירה או עריכה ישירה באמצעות AI בתשלום, חיוב, הוצאות על מודעות, יומן או שדות CRM ייעודיים לנדל״ן. נתמכים חמישה ערוצי קמפיין: פידים חברתיים, קבוצות פייסבוק, WhatsApp, אימייל ו-Marketplace, עם האישורים, החשבונות, השולחים, המדיה, ההסכמות ותנאי הזכאות הרגילים. אין נתיבי איתור של שולחי Gmail או חשבונות WhatsApp; לא ממציאים מזהי חשבונות ונמענים.

ממשיכים בין עמודי תוצאות

מתחילים קריאת רשימה ללא סמן. limit הוא 20 כברירת מחדל, בדרך כלל 1–50, ועד 500 ברשימת היעדים.
קוראים את items ושומרים את nextCursor. ערך null מציין שאין עמוד נוסף בהמשך הזה.
מעבירים סמן שהוחזר ללא שינוי לאותה רשימה, עם אותם מסננים רלוונטיים ובאותו חשבון וסביבת עבודה. לא מפענחים, מייצרים או מעגלים חותמות זמן. אורך הסמן מוגבל ל-2,048 תווים.
ברשימת פוסטים שומרים על אותו קמפיין אב, וביעדים על המסננים שאליהם הסמן קשור. אם מתקבל 400 invalid_cursor, מתחילים מחדש את הרשימה המתאימה ולא מנסים לתקן את הסמן.
מתייחסים לעימוד כאל מעבר ברשימה שמתעדכנת, ולא כאל צילום מצב קבוע. משאבים יכולים להשתנות בין בקשות.

לפעילות פרסום מבנה אחר: activity,‏ nextCursor ו-bulkSendsNextCursor. שומרים את המסננים ואת limit עם הסמן; המשך השליחות הנפרד משתמש ב-network=whatsapp. רשימות שלבי CRM וחברי צוות כוללות items, אך אינן רשימות רגילות עם סמן. בודקים את מבנה התשובה של כל פעולה במפרט.

מכבדים את מגבלות השימוש

ברירת המחדל היא 60 בקשות בדקה לכל מפתח ו-1,000 בקשות ביום UTC לכל חשבון וסביבת עבודה, במשותף לכל המפתחות של אותו חשבון בסביבה. המפעילים יכולים לשנות את המגבלות, ולכן מסתמכים על הכותרות בתשובה. חלון הדקה נמשך 60 שניות מהבקשה הראשונה שהתקבלה בו; המכסה היומית מתאפסת בחצות UTC.

כותרת	משמעות
`X-RateLimit-Limit`,‏ `X-RateLimit-Remaining`,‏ `X-RateLimit-Reset`	מכסת הדקה למפתח, יתרה וזמן איפוס.
`X-RateLimit-Day-Limit`,‏ `X-RateLimit-Day-Remaining`,‏ `X-RateLimit-Day-Reset`	המכסה היומית המשותפת, יתרה וזמן איפוס.
`Retry-After`	כמה שניות להמתין לאחר חריגה מהמכסה.

זמני האיפוס הם שניות Unix epoch. קריאות מאומתות, ניסיונות חוזרים, דחיות הרשאה או מושב וכותרות סביבה סותרות צורכים מכסה. החלפת מפתח לא מאפסת את היום. דחיות מוקדמות של תעבורה או כתובת IP עשויות להגיע ללא כותרות המכסה. ב-429 ממתינים לפי ההנחיה; כשמנגנון המכסות אינו זמין מתקבל 503, ולא גישה ללא הגבלה.

מבצעים שינויים בלי ליצור כפילויות

שומרים זהות קבועה לפעולה

לפני יצירת קמפיין, שינוי קמפיין, כתיבת פוסט, השהיה, חידוש, העברה לארכיון או יצירת הערה, שומרים באחסון מתמשך את שיטת הבקשה, היעד, גוף הבקשה המדויק שנבדק ואת Idempotency-Key. המזהה כולל 1–255 תווי ASCII גלויים, ללא רווחים. משתמשים באותו מזהה רק לאותה פעולה עם גוף זהה. רישומי הפעולה נשמרים גם לאחר החלפת מפתח באותו חשבון ובאותה סביבת עבודה.

ביצירת איש קשר משתמשים במקום זאת ב-externalId חובה, באורך 1–200 תווי ASCII גלויים ללא רווחים. זו פעולת איתור או יצירה ברמת סביבת העבודה, לא עדכון: 201 מציין יצירה ו-200 מחזיר איש קשר קיים שניתן לקרוא, בלי לדרוס שדות. external_id_in_use לא חושף איש קשר שאין גישה אליו. duplicate_contact מציין התאמה נפרדת לטלפון או לאימייל קיימים, ועשוי לכלול contactId.

להעלאה אין הבטחת מניעת כפילות. שליחה חוזרת עשויה ליצור נכס נוסף. נכסים זמניים שלא נעשה בהם שימוש הופכים למועמדים לניקוי לאחר 24 שעות; לא מסתמכים על קישור העלאה או כתובת זמנית כאחסון קבוע.

בודקים את התוכן ומאשרים פרסום במפורש

יוצרים קמפיין כטיוטה ושומרים את המזהה שהוחזר.
מעלים מדיה ושומרים מזהים אמיתיים. בוחרים חשבונות, יעדים ונמענים שיש הרשאה והסכמה להשתמש בהם כרגע.
מרכיבים ובודקים את הפוסט המלא, את כל כרטיסי הערוצים הרצויים, את לוחות הזמנים, את הסכמות הנמענים ואת מכסות הנמענים. intent: "draft" שומר ללא אישור שליחה; intent: "publish" מאשר במפורש את התוכן וההגדרות שנשלחו. בחירה בפרסום מיידי עשויה ליצור מיד משימות שליחה.
בעדכון שומרים את expectedRevision שנבדק. PUT /v1/posts/{id} מחליף את המצב הרצוי של הפוסט והכרטיסים, ואינו שינוי חלקי. כוללים מזהי כרטיסים קיימים כדי לשמור אותם; השמטת כרטיס ישן פירושה הסרה מכוונת.
שומרים את ההגדרות המקוריות שנבדקו. GET ציבורי אינו כולל הגדרות כרטיס פרטיות, בחירת נמענים ושולחים, ולכן אינו תבנית לעריכה. לא מעתיקים GET ישירות ל־PUT ולא מצרפים מספר גרסה חדש לתוכן ישן בלי בדיקה.
בודקים תוצאה לכל כרטיס ואת הפעילות בהמשך. ערוץ שאינו זמין עשוי שלא להיכלל בשליחה גם כשבקשת הפרסום התקבלה. אישור תקף או כרטיס פעיל או שהסתיים אינם הוכחת מסירה חיצונית.

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

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

מבינים שגיאות ומתאוששים

השגיאה היא JSON שטוח עם error ו-message, ולא שגיאת ספק מקוננת. בשגיאת אימות קלט עשוי להופיע details.issues עם עד שמונה נתיבים והודעות בטוחים; requestId אינו מובטח. שומרים גם את קוד HTTP.

מצב או קוד	משמעות והמשך טיפול
400	קלט, כותרת או סמן לא תקינים. מסירים שדות לא מוכרים ומתקנים לפי המפרט; מתחילים מחדש רשימה עם סמן לא מתאים.
401	מפתח לא תקין, מבוטל או שפג תוקפו, אובדן חברות או קריאה מדפדפן. בודקים את הסוד בשרת ואת החברות בלי לחשוף את המפתח.
403	ההרשאה, התפקיד, הנראות או המושב אינם מאפשרים את הפעולה. מתקנים את הגישה במקום לחזור על אותה בקשה.
404	המשאב חסר או לא נגיש, או שה-API מושבת. בודקים כתובת, מזהים אמיתיים וזמינות.
409 `operation_key_conflict`	מזהה שכבר נוצל נשלח עם תוכן או פעולה אחרים. מאתרים את הבקשה המקורית; מזהה חדש מיועד לפעולה חדשה באמת.
409 `post_changed`	הגרסה שנבדקה התיישנה. בודקים מצב, משלבים את המידע עם ההגדרות ששמרתם, בודקים מחדש ושולחים פעולה חדשה. לא מעלים מספר גרסה אוטומטית.
409 `posting_busy` עם `retryable: true`	השינוי בוטל בגלל התנגשות בביטול עבודת פרסום. לאחר שחרור המשאב אפשר לנסות במכוון עם אותו גוף ומזהה.
409 `archive_cleanup_incomplete` עם `retryable: true`	הקמפיין בארכיון, אך ביטול העבודה טרם הושלם. שולחים שוב את אותה בקשת ארכיון ואותו מזהה כדי להשלים ניקוי, בלי להפעיל מחדש.
410	משאב שנוצר בפעולה המזוהה נמחק. שימוש חוזר במזהה לא ייצור תחליף.
413 / 415	הקובץ גדול מדי או שהסוג אינו נתמך. מכינים קובץ אמיתי ונתמך בגודל המותר.
422	סירוב עסקי, למשל שליחה שחורגת ממכסת הנמענים שאושרה. בודקים ומתקנים את הבקשה העסקית.
429	ממתינים לפי `Retry-After` וכותרות האיפוס.
500 או תוצאת כתיבה לא ברורה	ייתכן שהפעולה הושלמה. בודקים מצב לפני שחזור מכוון באותו מזהה.
503	שירות נדרש אינו זמין. שומרים את יומן הפעולה ונמנעים מלולאת ניסיונות בלתי מבוקרת.

השדה retryable לא מופיע בכל שגיאה. היעדרו אינו אישור לחזור על בקשת שינוי ללא שינוי.

מחליפים או מבטלים מפתח

יוצרים מפתח חלופי עם הרשאות ותוקף מתאימים.
שומרים באופן פרטי, מעדכנים את השרת ומוודאים שהחלופה מסוגלת לבצע את הקריאה הנדרשת.
ב־מפתחות ה-API שלך לוחצים על ביטול המפתח של המפתח הישן. קוראים את לבטל את המפתח {name}? ואת האזהרה שהגישה תאבד מיד.
מאשרים עם ביטול המפתח. המצב משתנה ל־בוטל, ואי אפשר לשחזר את המפתח. גם מפתח במצב פג תוקף אינו יכול לשמש להזדהות.
אם לא ברור שהביטול הצליח, לוחצים על רענון הרשימה לפני ניסיון נוסף. מפתח שנחשף מבטלים מיד ולא מחכים לתפוגה.

חתימות Webhooks ומדריכים קשורים

לקבלת אירועים חתומים מוסיפים Webhook בהגדרות, ולא שולחים מפתח API לשרת המקבל. מאמתים את webhook-id,‏ webhook-timestamp ו-webhook-signature על הגוף המקורי באמצעות סוד whsec_ נפרד. בודקים סטייה של עד חמש דקות, משווים HMAC בזמן קבוע ומונעים כפילויות באופן עמיד למשך 30 יום. במדריך Webhooks מפורטים מבנה החתימה וכללי המסירה.