מפתחות API ו-Client ID

מפתח API מאפשר לתוכנה שלכם, ולכלים כמו Zapier, ‏n8n, ‏Make והתוסף ל-WordPress, לשלוח הודעות WhatsApp מהמספרים של סביבת העבודה שלכם. הקוד שלכם שולח את המפתח בכותרת Authorization: Bearer; אינטגרציות מבקשות שני ערכים מהדף מפתחות API: ה-Client ID של סביבת העבודה ואחד מהמפתחות שלה. באותו דף נמצא גם הסוד שבו אנחנו חותמים על ה-Webhooks.

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

פתחו את מפתחות API תחת אינטגרציות בסרגל הצד, או עברו אל הגדרות ← מפתחות API.

לכל מפתח מוצגים השם שלו, מתי הוא נוצר (נוצר ב-…), ארבעת התווים האחרונים של המפתח (למשל •••• 7f3a), העתקת המפתח ומחיקה. המפתח החדש ביותר מופיע ראשון.

יצירת מפתח API#

1. לחיצה על יצירת מפתח

   בדף הגדרות ← מפתחות API, לחצו על יצירת מפתח בפינה השמאלית העליונה של הכרטיס.

2. מתן שם (לא חובה)

   תחת שם (לא חובה), הקלידו את שם האפליקציה שתשתמש בו, למשל n8n או Website (עד 50 תווים). אם תשאירו את השדה ריק, המפתח יקבל שם כמו "API Key 3", כפי שכתוב ברמז שמתחת לשדה.

3. יצירה

   לחצו על יצירת מפתח.

   

4. העתקת המפתח

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

   

• עד 10 מפתחות לכל סביבת עבודה. כשיש 10, הכפתור יצירת מפתח אפור, וכשמצביעים עליו מוצג "אפשר להחזיק עד 10 מפתחות API. כדי ליצור מפתח חדש, יש למחוק אחד."
• המפתחות לא פגים, ואי אפשר לשנות את השם שלהם או לכבות אותם: מפתח עובד עד שמוחקים אותו.
• מפתח אחד לכל אפליקציה. תנו לכל מפתח את שם האפליקציה שמשתמשת בו, כדי שתוכלו להחליף או למחוק מפתח אחד בלי לשבור את האחרים.
• איזו סביבת עבודה: מפתח שייך לסביבת העבודה שנבחרה כשיצרתם אותו, וכל בקשה שנשלחת איתו פועלת על סביבת העבודה הזו: על המספרים, ההודעות והתוכנית שלה. כדי לשלוח מסביבת עבודה אחרת, עברו אליה וצרו בה מפתח.

מה להזין באפליקציה שלכם#

איפה מזינים אותם:

• הקוד שלכם: בכותרת Authorization: Bearer YOUR_API_KEY בכל בקשה (מומלץ). המפתח מציין את סביבת העבודה שלו, ולכן אפשר לוותר על client_id; אם תשלחו אותו, הוא עדיין חייב להיות של סביבת העבודה הזו. ראו שליחת המפתח בכותרת, ואת שליחת הודעה להודעה ראשונה ב-cURL, ‏Python, ‏Node.js ו-PHP.
• Zapier: ה-Client ID ומפתח ה-API, כשמחברים את החשבון.
• n8n: השדות Client ID, ‏API Key ו-WhatsApp Client ID ב-credential של WbizTool.
• Make, ‏Pabbly Connect וכלים אחרים: הגוף של בקשת HTTP.
• WordPress: בדף WbizTool → Settings, תחת API Configuration.

Google Sheets ו-Shopify מוגדרים בלוח הבקרה ולא צריכים מפתח.

שליחת המפתח בכותרת#

כל endpoint של /api/v1/ מקבל את המפתח בכותרת Authorization, כמו שיעשה גם API v2 שבדרך:

Authorization: Bearer YOUR_API_KEY

• client_id לא חובה עם הכותרת: המפתח קובע את סביבת העבודה. אם תשלחו גם client_id, הוא חייב להיות ה-Client ID של סביבת העבודה הזו, כמו קודם.
• שלחו את המפתח במקום אחד. עם הכותרת, השמיטו את api_key מהגוף, או שלחו את אותו מפתח. אם הם שונים, נעשה שימוש במפתח שבכותרת כשהוא מפתח תקף; אם בכותרת יש משהו אחר (למשל טוקן של כלי אחר), נעשה שימוש ב-api_key שבגוף.
• מפתחות בגוף עדיין עובדים (client_id ו-api_key כ-JSON או כשדות טופס), כך ששום דבר לא משתנה לאפליקציות ולאינטגרציות ששולחות אותם כך. הכותרת עדיפה, כי גוף הבקשה מגיע ללוגים, לשרתי proxy ולהיסטוריה של כלים לבניית טפסים לעתים קרובות יותר מכותרות.
• שדות טופס, העלאות multipart וגוף JSON עובדים כולם עם הכותרת.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

בדיקת המפתח#

קראו לבדיקת פרטי התחברות (POST /api/v1/me/) עם המפתח שלכם ואם תרצו גם whatsapp_client. התשובה "status": 1 עם "message": "Okay" פירושה שהם עובדים יחד. הבדיקה לא שולחת כלום ולא מנצלת הודעות, אבל היא לא בודקת שנותרו לכם הודעות או שהמספר מחובר.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

מפתח שעובד מחזיר {"status": 1, "message": "Okay", "name": "…"}.

העתקה חוזרת של מפתח#

לחצו על העתקת המפתח ליד המפתח. המפתח המלא מועתק ללוח בלי שיוצג בדף; תראו, למשל, ""חיבור ל-Zapier" הועתק.", והכפתור מציג הועתק ✓ לרגע. אין צורך במפתח חדש רק כי איבדתם את הישן.

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

מחיקת מפתח#

1. לחיצה על מחיקה

   לחצו על מחיקה ליד המפתח.

2. אישור

   החלון "למחוק את "…"?" מזהיר: "כל מה שמשתמש במפתח הזה יפסיק לעבוד מיד: Zaps ב-Zapier, תרחישים ב-n8n וב-Make, התוסף ל-WordPress וקריאות ה-API שלכם. כדאי לתת להם מפתח אחר קודם. אי אפשר לבטל את הפעולה." לחצו על מחיקת המפתח. תופיע ההודעה ""…" נמחק."

מאותו רגע, בקשות עם המפתח הזה מקבלות Auth Error: invalid api key. מה שהוא עשה קודם נשאר: הודעות שהוא הכניס לתור עדיין יוצאות (בטלו אותן בדוחות אם צריך), ותזכורות שהוא יצר ממשיכות לפעול. גם טריגר Incoming WhatsApp Message של Zapier שהוגדר איתו ממשיך לקבל הודעות, כי ה-Webhook שלו כבר מוגדר במספר: כבו את ה-Zap ב-Zapier כדי לעצור אותו.

החלפת מפתח#

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

1. יצירת מפתח חדש

   צרו מפתח והעתיקו אותו. אם יש 10 מפתחות, מחקו קודם אחד שאתם כבר לא משתמשים בו.

2. עדכון האפליקציות

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

3. מחיקת המפתח הישן

   מחקו אותו. הוא מפסיק לעבוד מיד.

4. בדיקת שימוש לרעה (אחרי דליפה)

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

שמירה על המפתחות#

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

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

ה-Client ID לבדו אינו סוד, אבל התייחסו לכל מפתח כמו לסיסמה.

מפתחות API v2#

ל-API v2 יש מפתחות משלו, שיוצרים בכרטיס מפתחות API v2 באותה לשונית. הם בטוחים יותר מהמפתחות שלמעלה:

• מוצגים פעם אחת. המפתח המלא (wbz_live_…) מוצג רק כשיוצרים אותו; WbizTool שומרת רק טביעת אצבע שלו. אם איבדתם אותו, בטלו את תוקפו וצרו מפתח חדש.
• רק מה שצריך. סמנו מה המפתח רשאי לעשות (שליחת הודעות, קריאת הודעות, תזכורות, מספרים, מדיה, בדיקת מספרים), הגבילו אותו לחלק מהמספרים שלכם, ואם תרצו, תנו לו תאריך תפוגה.
• מפתחות בדיקה. מפתח בדיקה (wbz_test_…) בודק כל בקשה כמו מפתח פעיל, אבל לא שולח כלום – לבנייה ולניסוי של אינטגרציה.
• שימוש אחרון. לכל מפתח מוצג מתי ומאיפה נעשה בו שימוש לאחרונה. ביטול תוקף עוצר אותו מיד, וגם את ה-endpoints של ה-Webhooks שהוגדרו איתו.

המפתחות שלמעלה עובדים רק עם API v1, ומפתחות API v2 רק עם v2. ראו מעבר מ-v1 ל-v2.

חתימות Webhook#

WbizTool חותמת על כל Webhook שהיא שולחת לכם, כדי שה-endpoint שלכם יוכל לוודא שהבקשה באמת הגיעה מאיתנו ולא שונתה בדרך: ה-Webhook של סטטוס ההודעה (נשלחה, נכשלה, בוטלה, פגה), אירועי החיבור של מספרים וה-Webhooks של תיבת ההודעות. הגוף נשאר כמו קודם; נוספות שתי כותרות:

החתימה מכסה בדיוק את הבתים שאנחנו שולחים: את שדות הטופס כפי שהם מגיעים, את כל גוף ה-multipart כשמצורפת תמונה של קוד QR, ואת ה-JSON של ה-Webhooks של תיבת ההודעות. מקבלים שמתעלמים מהכותרות ממשיכים לעבוד.

קבלת סוד החתימה#

בדף הגדרות ← מפתחות API, הכרטיס סוד החתימה ל-Webhooks שמתחת למפתחות מציג את ארבעת התווים האחרונים של הסוד, למשל •••• b70d. לכל סביבת עבודה יש סוד אחד לכל ה-Webhooks שלה; הוא נוצר עם ה-Webhook הראשון שאנחנו שולחים לכם.

1. לחיצה על הצגת סוד חדש

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

2. העתקת הסוד

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

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

אימות Webhook#

חשבו את החתימה מהגוף הגולמי (לפני שה-framework שלכם מפענח אותו), השוו אותה לכותרת בהשוואה בזמן קבוע, ודחו חותמות זמן ישנות מ-5 דקות, כדי שאי אפשר יהיה לשלוח שוב בקשה ישנה:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

החזירו 2xx כשהבדיקה עוברת ו-401 כשהיא נכשלת. Webhooks של תיבת ההודעות שיש להם סוד משלהם (סוד ה-Webhook של המספר) ממשיכים לשאת גם את X-Wbiztool-Signature; ‏WbizTool-Signature הוא אותה שיטה בכל Webhook.

פתרון בעיות#

מדריכים קשורים#

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