API v2

API v2 הוא ה-REST API החדש של WbizTool: מפתח אחד לכל אפליקציה, רק עם הגישה שהיא צריכה, כתובות URL לפי משאבים, קודי סטטוס HTTP אמיתיים, Webhooks חתומים ב-JSON וניסיונות חוזרים בטוחים. הדף הזה מסביר מה משותף לכל הבקשות. דפי המשאבים מסבירים כל endpoint.

כתובת בסיס#

https://wbiztool.com/api/v2

בנתיבים אין לוכסן בסוף (/api/v2/messages), אבל גם נתיב עם לוכסן מתקבל. כתובת שלא קיימת מחזירה 404 עם הקוד not_found.

דוגמה מהירה#

בדקו את המפתח שלכם עם GET /me. זה עובד עם כל הרשאה ולא שולח כלום:

curl https://wbiztool.com/api/v2/me \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

import os
import requests

response = requests.get(
    "https://wbiztool.com/api/v2/me",
    headers={"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/me", {
  headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}` },
});
console.log(response.status, await response.json());

<?php
$ch = curl_init('https://wbiztool.com/api/v2/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);
$body = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n";
print_r($body);
curl_close($ch);

{
  "workspace": { "id": 5012, "name": "Acme Bakery" },
  "key": {
    "id": 7,
    "name": "Order system",
    "mode": "live",
    "scopes": ["messages:send", "messages:read"],
    "limited_to_numbers": false,
    "number_ids": [],
    "expires_at": null
  },
  "plan": { "name": "Starter" },
  "limits": {
    "requests_per_minute": 60,
    "requests_per_day": 10000,
    "messages_per_number_per_day": 1000,
    "messages_remaining": null
  }
}

‏messages_remaining הוא null כשהתוכנית שולחת הודעות ללא הגבלה. ‏plan הוא null כשאין לסביבת העבודה תוכנית פעילה.

מפתחות#

שלחו את המפתח שלכם בכותרת Authorization בכל בקשה:

Authorization: Bearer wbz_live_…

אין client_id: המפתח מציין את סביבת העבודה שלו. מפתח v2 מתחיל ב-wbz_live_ או ב-wbz_test_, ואחריו 38 אותיות וספרות. מפתחות v1 לא עובדים ב-v2 (הם מקבלים v1_key_on_v2), ומפתחות v2 לא עובדים ב-v1.

יצירת מפתח#

בעלים יוצרים מפתחות בדף הגדרות ← מפתחות API, בכרטיס מפתחות API v2: לחצו על יצירת מפתח v2, ואז בחרו:

• שם: האפליקציה שתשתמש בו, עד 50 תווים.
• סוג המפתח: פעיל שולח הודעות אמיתיות; בדיקה בודק הכול ולא שולח כלום (ראו מצב בדיקה).
• מה הוא יכול לעשות: ההרשאות, או הכול.
• המספרים שהוא יכול להשתמש בהם: כל המספרים, כולל מספרים שיתווספו בהמשך, או רק חלק מהם (ראו מפתחות שמוגבלים לחלק מהמספרים).
• תפוגה: אף פעם, או בעוד 30 יום, 90 יום או שנה.

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

בסביבת עבודה יכולים להיות עד 10 מפתחות v2 שהתוקף שלהם לא בוטל. בכרטיס מוצגים לכל מפתח ארבעת התווים האחרונים שלו, ההרשאות, המספרים, התפוגה, ומתי ומאיזו כתובת IP נעשה בו שימוש לאחרונה. ביטול תוקף עוצר מפתח מיד, ואיתו את ה-endpoints של ה-Webhooks שהוא יצר. מפתח שתאריך התפוגה שלו עבר מקבל api_key_expired.

הרשאות#

כל מפתח יכול לעשות רק מה שההרשאות (scopes) שלו מאפשרות. בקשה מחוץ להן מחזירה 403 עם missing_scope, ו-required_scope בשגיאה מציין איזו הרשאה נדרשת.

‏GET /me לא דורש הרשאה מסוימת. שליחה לאיש קשר שמור עם to.contact_id דורשת רק messages:send.

מפתחות שמוגבלים לחלק מהמספרים#

מפתח שמוגבל לחלק מהמספרים עובד רק איתם:

• הוא שולח רק מהמספרים האלה, ומציג, קורא ומבטל רק את ההודעות שלהם. מספר אחר ב-from מקבל number_not_allowed.
• ‏GET /numbers מציג רק את המספרים האלה. המפתח יכול לחבר אותם מחדש, אבל לא להוסיף מספר חדש.
• הוא רואה ומשנה רק את התזכורות שנשלחות מהמספרים האלה, ותזכורת חדשה חייבת לציין אחד מהם כ-from.
• הוא לא יכול לנהל endpoints של Webhooks בכלל, כי הם מקבלים את האירועים של כל סביבת העבודה.

‏GET /me מציג את limited_to_numbers ואת ה-number_ids שהמפתח רשאי להשתמש בהם.

בקשות#

• JSON בבקשה ובתגובה. שלחו את הגוף כ-Content-Type: application/json. היוצא מן הכלל היחיד הוא העלאת קובץ, שנשלחת כ-multipart/form-data. כל תגובה היא JSON, כולל שגיאות.
• שמות השדות הם ב-snake_case, ושדות לא מוכרים נדחים: שגיאת הקלדה כמו txt מחזירה validation_failed במקום שתתעלם ממנה.
• מספרי טלפון נכתבים בפורמט בינלאומי עם + (E.164), למשל ‎+919876543210. מותר להשתמש ברווחים ובמקפים; מספר בלי + נדחה עם invalid_phone.
• זמנים נכתבים ב-ISO 8601 עם היסט, למשל 2026-10-20T09:30:00+05:30 או 2026-10-20T04:00:00Z. זמן בלי היסט נדחה עם invalid_datetime. הזמנים בתגובות הם ב-UTC ומסתיימים ב-Z, חוץ מ-next_run_at של תזכורת, שהוא באזור הזמן של התזכורת.
• מזהים הם מספרים שלמים, כמו ה-id של מספר (ה-from כשאתם שולחים) או ה-id של הודעה.
• קודי הסטטוס אומרים בדיוק מה שהם אומרים: 200 בסדר, 201 נוצר, 202 התקבל (בתור), 400 הבקשה שגויה, 401 המפתח שגוי, 402 לא נותרו הודעות, 403 אסור, 404 לא נמצא, 409 התנגשות, 413 גדול מדי, 415 סוג תוכן שגוי, 422 אי אפשר להשתמש בערך, 429 יותר מדי בקשות, 5xx תקלה אצלנו.

התגובות נושאות את הכותרת Cache-Control: no-store.

שגיאות#

לכל השגיאות יש אותו מבנה:

{
  "error": {
    "code": "invalid_phone",
    "message": "This is not a valid phone number. Write it in international format with +, e.g. +919876543210.",
    "field": "to.phone",
    "docs": "https://wbiztool.com/docs/api/v2/errors/#invalid_phone",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817"
  }
}

• ‏code יציב: התבססו עליו בקוד שלכם. ‏message הוא טקסט באנגלית למפתחים ועשוי להשתנות.
• ‏field מציין את השדה שהשגיאה נוגעת לו (to.phone, ‏to[3].phone, ‏schedule.cron), או שהוא null.
• ‏docs מקשר לקוד בדף השגיאות.
• ‏request_id זהה לכותרת X-Request-Id. ציינו אותו אם אתם פונים אלינו.
• חלק מהשגיאות מוסיפות פרטים, למשל status ב-not_cancellable או used ו-limit ב-storage_full. כשיש בבקשה כמה בעיות, ‏errors מפרט את השאר, כל אחת עם field ו-message.

כל הקודים, סטטוס ה-HTTP של כל אחד ומה לעשות מופיעים בדף השגיאות.

Idempotency-Key#

שגיאת רשת או timeout משאירים אתכם בלי לדעת אם בקשה הצליחה. שלחו כותרת Idempotency-Key עם בקשת POST שיוצרת משהו, ותוכלו לשלוח אותה שוב בבטחה:

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{"to": {"phone": "+919876543210"}, "text": "Hi Asha, your order #1042 is ready."}'

• הערך שלכם: כל מחרוזת ייחודית באורך 1 עד 255 תווים שאפשר להדפיס, כמו UUID או מזהה הזמנה משלכם. צרו ערך חדש לכל בקשה חדשה, והשתמשו בו שוב רק בניסיון חוזר של אותה בקשה.
• ניסיון חוזר מקבל בחזרה את התגובה הראשונה עם הכותרת Idempotent-Replayed: true. שום דבר לא מתבצע פעמיים: אין הודעה שנייה, תזכורת, קובץ או endpoint.
• המפתחות נשמרים 24 שעות מהבקשה הראשונה, והם שייכים למפתח ה-API שלכם: מפתח API אחר של סביבת העבודה יכול להשתמש באותו ערך בלי התנגשות.
• אותו מפתח, בקשה אחרת: בקשה עם מפתח שכבר שימש לשיטה, לנתיב או לגוף אחרים מחזירה 422 idempotency_key_reused.
• עדיין בטיפול: כל עוד הבקשה הראשונה עם המפתח עדיין בטיפול, ניסיון חוזר מחזיר 409 idempotency_in_progress עם Retry-After: 1. חכו רגע ושלחו אותה שוב.
• שגיאות לא נשמרות. אם הבקשה הראשונה הסתיימה בשגיאה, שום דבר לא נשמר: תקנו את הבקשה ושלחו אותה שוב עם אותו מפתח.
• סודות לא מוחזרים שוב. ניסיון חוזר של POST /webhooks משמיט את ה-secret של ה-endpoint, שמוצג רק בתגובה הראשונה.

זה עובד ב-POST /messages, ‏POST /messages/batch, ‏POST /numbers, ‏POST /reminders, ‏POST /media, ‏POST /number-checks ו-POST /webhooks, ובכל אחד מהם זה לא חובה. בקשות אחרות מתעלמות מהכותרת. ערך ריק או ארוך מדי מחזיר 400 invalid_idempotency_key.

מגבלות קצב#

כל מפתח יכול לשלוח 60 בקשות בדקה ו-10,000 בקשות ביום. אלה חלונות קבועים: חלון הדקה מתחיל בתחילת הדקה בשעון, וחלון היום ב-00:00 UTC. מעבר למגבלה, הבקשה מחזירה 429 rate_limited.

תגובות לבקשות עם מפתח תקף נושאות את הכותרות האלה:

בנפרד מאלה:

• מפתחות שגויים: יותר מ-30 בקשות בדקה עם מפתח שגוי מכתובת IP אחת מחזירות 429 too_many_auth_failures עם Retry-After: 60.
• הודעות לכל מספר: מספר שולח לכל היותר 1,000 הודעות ב-24 שעות (שימוש הוגן). שליחה מעבר לכך מחזירה 429 number_daily_cap_reached.

חלוקה לדפים#

רשימות שיכולות לגדול (GET /messages, ‏/reminders, ‏/media, ‏/number-checks וה-/results של בדיקה) מגיעות בדפים, מהחדש לישן:

{
  "data": [ … ],
  "next_cursor": "eyJpZCI6OTgxNzI2MywidCI6IjIwMjYtMTAtMThUMTA6MTU6MDIuMzExWiIsImYiOiI0NGIxMzZmYTM1NWIifQ"
}

• ‏limit קובע את גודל הדף, מ-1 עד 100 (ברירת המחדל 25).
• כדי לקבל את הדף הבא, שלחו את אותה בקשה עם cursor שמוגדר ל-next_cursor של הדף הקודם. בדף האחרון, ‏next_cursor הוא null.
• השאירו את שאר המסננים כמו שהם: cursor שנשלח עם מסננים אחרים מחזיר 400 invalid_cursor. התחילו מחדש בלי cursor.
• התייחסו ל-cursor כמחרוזת אטומה. פריטים שנוספים בזמן שאתם עוברים בין הדפים לא מזיזים את הדפים.

curl "https://wbiztool.com/api/v2/messages?limit=100&cursor=eyJpZCI6OTgxNzI2MywidCI6..." \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

‏GET /numbers ו-GET /webhooks מחזירים הכול ברשימת data אחת.

מזהי בקשה#

לכל תגובה, כולל שגיאות, יש כותרת X-Request-Id כמו req_4f1c2a9b8e7d6c5b4a392817. שגיאות נושאות את אותו ערך כ-request_id. שמרו אותו בלוג, וציינו אותו אם אתם פונים אלינו: בעזרתו נמצא את הבקשה בלוגים שלנו, שמתעדים את המזהה של המפתח שלכם אבל אף פעם לא את המפתח עצמו.

אם תשלחו X-Request-Id משלכם (עד 100 תווים שאפשר להדפיס), הוא יחזור כ-X-Client-Request-Id, כדי שתוכלו להתאים תגובות ללוגים שלכם.

מצב בדיקה#

מפתח בדיקה (wbz_test_…) מאפשר לבנות ולבדוק אינטגרציה בלי לשלוח כלום. צרו אחד בדף הגדרות ← מפתחות API עם סוג המפתח: בדיקה. ‏GET /me מציג "mode": "test".

מה מפתח בדיקה עושה כמו מפתח פעיל:

• ‏POST /messages ו-POST /messages/batch בודקים את כל מה ששליחה אמיתית בודקת: את הנמען, הטקסט, המדיה, send_at ו-expires_at, המספר השולח, וההרשאות והמספרים של המפתח. אותן טעויות מקבלות אותן שגיאות.
• הרשאות, מספרים, מגבלות קצב ו-Idempotency-Key עובדים אותו דבר.
• כל קריאה של שאר סביבת העבודה (GET /me, ‏/numbers, ‏/reminders, ‏/media, ‏/number-checks, ‏/webhooks) מציגה את הנתונים האמיתיים שלה, לקריאה בלבד.

מה שונה:

• שום דבר לא נשלח. שליחת בדיקה נשמרת במקום זאת כהודעת בדיקה, והיא לא מנצלת את ההודעות של התוכנית או את 1,000 ההודעות היומיות של המספר, ולכן היא אף פעם לא מקבלת no_credits או number_daily_cap_reached.
• הסטטוס שלה מתקדם מעצמו: queued, אחרי 5 שניות sent, ו-delivered 15 שניות אחרי שנוצרה (בהודעה מתוזמנת, הזמן נספר מ-send_at). הודעה שה-expires_at שלה מגיע לפני שהיא הייתה נשלחת הופכת ל-expired. הודעות בדיקה אף פעם לא הופכות ל-read או ל-failed.
• מפתח בדיקה רואה רק את הודעות הבדיקה שלו. ‏GET /messages ו-GET /messages/{id} מציגים אותן ותו לא, ו-DELETE /messages/{id} מבטל אחת מהן כל עוד היא queued או scheduled. מפתחות פעילים אף פעם לא רואים הודעות בדיקה. המסנן status של GET /messages לא נתמך במפתחות בדיקה ומחזיר test_mode_unsupported; ‏number, ‏since ו-until עובדים.
• פעולות כתיבה אחרות נדחות עם 403 test_mode_unsupported: חיבור מספר, יצירה, שינוי או מחיקה של תזכורות, העלאה או מחיקה של מדיה, התחלת בדיקת מספרים, והוספה, הסרה, החלפת סוד או בדיקה של endpoints של Webhooks.
• לא נשלחים אירועי Webhook להודעות בדיקה.
• הודעות בדיקה נשמרות 30 יום.

משאבים#

• הודעות: שליחה עכשיו או מאוחר יותר, שליחה לעד 1,000 נמענים, קריאת ההיסטוריה, ביטול.
• מספרים: הצגת מספרי ה-WhatsApp וחשבונות ה-Telegram שלכם, וחיבור מספר WhatsApp עם קוד QR או קוד צימוד.
• תזכורות: הודעות חוזרות לפי לוח זמנים של cron.
• מדיה: העלאת קבצים פעם אחת ושליחתם לפי media_id.
• בדיקת מספרים: לברר אילו מספרים נמצאים ב-WhatsApp.
• Webhooks: אירועים חתומים כשהודעה נשלחת, נכשלת, מבוטלת או פגה.
• שגיאות: כל קודי השגיאה.
• מעבר מ-v1 ל-v2: כל endpoint ושדה של v1, והמקבילה שלהם ב-v2.