מעבר מ-v1 ל-v2

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

מה משתנה בכל מקום#

• מפתחות: ה-client_id וה-api_key של v1 הופכים לכותרת אחת, Authorization: Bearer wbz_live_…. צרו מפתח v2 בדף הגדרות ← מפתחות API, בכרטיס מפתחות API v2, רק עם ההרשאות שהאפליקציה צריכה. מפתחות v1 לא עובדים ב-v2, ומפתחות v2 לא עובדים ב-v1.
• JSON בלבד: אין שדות טופס. העלאות קבצים נשלחות ל-POST /media (multipart) והקבצים נשלחים לפי media_id.
• שיטות וכתובות URL: ‏GET לקריאה, POST ליצירה, PATCH לשינוי, DELETE לביטול או למחיקה, תחת https://wbiztool.com/api/v2.
• קודי סטטוס HTTP במקום "status": 0 או 1 (ראו תגובות ושגיאות).
• מספרי טלפון בפורמט בינלאומי עם +, בלי country_code.
• זמנים ב-ISO 8601 עם היסט, במקום שדות נפרדים לתאריך, לשעה ולאזור הזמן.
• Webhooks הם endpoints שמוסיפים פעם אחת לסביבת העבודה, עם אירועי JSON חתומים, במקום כתובת webhook בכל הודעה.

endpoint אחר endpoint#

הנתיבים של v2 הם יחסית ל-https://wbiztool.com/api/v2.

שליחה, שדה אחר שדה#

אותה שליחה ב-v1 וב-v2:

# v1
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_V1_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "msg_type": 1, "country_code": "91", "phone": "9876543210",
       "img_url": "https://example.com/offers/diwali-sale.jpg", "msg": "Our Diwali sale starts today",
       "expire_after_seconds": 3600}'

# v2
curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diwali-9876543210" \
  -d '{"from": 101, "to": {"phone": "+919876543210"},
       "media": {"url": "https://example.com/offers/diwali-sale.jpg"}, "text": "Our Diwali sale starts today",
       "expires_at": "2026-10-20T11:30:00+05:30"}'

כמה התנהגויות של v1 הוסרו בכוונה:

• אין ניחוש של קידומות מדינה. ‏v1 הוסיף את country_code לפני מספר (עם 91, תמיד לפני מספר בן 10 ספרות). ‏v2 מקבל את המספר בדיוק כפי שהוא נכתב עם +.
• אין הורדת קובץ כשאתם קוראים ל-API. ‏v1 הוריד את img_url ואת file_url במהלך הבקשה. ‏v2 בודק שהקישור ציבורי ומוריד את הקובץ כשההודעה נשלחת; קישור שבור מופיע כהודעה במצב failed.
• אין שורה של כישלון כשהשליחה נדחית. כש-v1 דוחה שליחה מעבר ל-1,000 ההודעות היומיות, הוא עדיין שומר את ההודעה כנכשלה. ‏v2 לא שומר כלום כשהוא דוחה שליחה.
• שדות לא מוכרים נדחים במקום שהמערכת תתעלם מהם.

סטטוסים#

המספרים והמילים של v1 הופכים לשדה status אחד:

אירועי Webhook הם message.sent, ‏message.failed, ‏message.cancelled ו-message.expired, ומתאימים ל-SENT, ‏FAILED, ‏CANCELLED ו-EXPIRED של v1.

תגובות ושגיאות#

‏v1 מחזיר הרבה שגיאות עם HTTP 200 או 400 ו-"status": 0, והצלחה עם "status": 1. ‏v2 משתמש בקוד הסטטוס של HTTP:

• הצלחה היא 200, ‏201 (נוצר) או 202 (בתור), והגוף הוא האובייקט עצמו, למשל ה-Message. אין עטיפה של status: 1.
• שגיאות הן 4xx או 5xx עם מבנה אחד: {"error": {"code", "message", "field", "docs", "request_id"}}. התבססו על code, ולא על ה-message באנגלית. כל הקודים מופיעים בדף השגיאות.

# v1
result = response.json()
if result.get("status") == 1:
    msg_id = result["msg_id"]

# v2
if response.status_code == 202:
    message_id = response.json()["id"]
else:
    error = response.json()["error"]
    if error["code"] == "number_daily_cap_reached":
        ...  # try again tomorrow

כמה הודעות של v1 והקודים שלהן ב-v2:

Webhooks#

ב-v1, כל הודעה יכולה לשאת כתובת webhook שמקבלת msg_id=…&status=SENT כשדות טופס. ב-v2:

1. הוסיפו endpoint פעם אחת עם POST /webhooks ושמרו את ה-secret שלו.
2. הוא מקבל אירועי JSON על כל ההודעות של סביבת העבודה, עם ה-Message המלא ב-data.message. התאימו אותם לרשומות שלכם לפי data.message.id.
3. אמתו את החתימה: אותה שיטה כמו ב-v1 (WbizTool-Timestamp, ‏WbizTool-Signature: v1=…), אבל עם הסוד של ה-endpoint עצמו במקום הסוד של סביבת העבודה.
4. סננו כפילויות עם WbizTool-Event-Id. הניסיונות החוזרים נמשכים כ-23 שעות, ולא 4 ניסיונות במשך כמה דקות כמו ב-v1, וגם תגובות 4xx מנוסות שוב.

לאירועי החיבור של v1 (webhook_url ב-whatsapp/connect/) עדיין אין אירוע ב-v2: בצעו במקום זאת polling ל-GET /numbers/{id}.

רשימת בדיקה#

1. יצירת מפתח v2 לכל אפליקציה

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

2. שינוי הבקשות

   כתובות URL ושיטות חדשות, גוף JSON, ‏to / from / text / media, מספרי טלפון עם +, זמנים עם היסט. הוסיפו Idempotency-Key לכל שליחה.

3. שינוי הטיפול בשגיאות

   בדקו את סטטוס ה-HTTP, ואז את error.code. טפלו ב-429 בהמתנה לפי Retry-After.

4. העברת ה-Webhooks

   הוסיפו endpoint, אמתו חתימות עם הסוד שלו, וסננו כפילויות לפי מזהה האירוע.

5. מעבר ומחיקת המפתח הישן

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

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

• סקירה של API v2
• הודעות
• Webhooks
• שגיאות
• מפתחות API ו-Client ID (v1)