קריאת דרישות הקמפיין של מותג

שמרו על המותג ומקרה השימוש יחד

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

קראו את הדרישות הנוכחיות

החילו את דרישות המפעילים הנבחרים יחד

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

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

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

טופס הקמפיין הנוכחי משתמש בשדות sample1 עד sample5 עבור דוגמאות הודעות. אם לא ניתן לעמוד בדרישות בתוך הטופס הזמין, עצרו ופתרו את הבחירה מול התמיכה. עבור הצהרת מנוי מופעלת, ספקו את מילות המפתח וטקסט התגובה המתאימים לה: optinKeywords/optinMessage, optoutKeywords/optoutMessage וכן helpKeywords/helpMessage. שמרו על עקביות בין הדוגמאות לבין מקרה השימוש שנבחר והודעות הלקוח בפועל.

סקרו לפני כל בקשת רישום

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

טיפול בחיפוש דרישות שנכשל

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

בקשה

השתמשו בחשבון API מופעל דרך HTTPS מכתובת IP מקור מורשית. הנתיב הנוכחי תומך במדיניות האימות של החשבון, כולל אימות Basic וחשבונות API מופעלים עם אסימון bearer. אל תשתמשו בפרטי הכניסה של הספק.

GET עם מזהה המותג וערך מקרה-השימוש שנבחר בנתיב ה-URL. לא נדרש גוף בקשה.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/campaignBuilder/brand/$BRAND_ID/usecase/$USECASE"

תגובה

נתיב ה-TCR הנוכחי מחזיר את גוף ה-JSON של הרישום ישירות ושומר על סטטוס ה-HTTP שלו. הוא אינו מוסיף את מעטפת status/response הישנה של v3. הדוגמה הבדיונית המקוצרת אינה תוצאת הסמכה חיה. בדקו את סטטוס ה-HTTP ואת מבנה ה-JSON הצפוי לפני השימוש בה. הפורטל מצפה לאובייקט שה-usecase שלו תואם למקרה השימוש שנבחר. דרישות המפעילים נמצאות תחת mnoMetadata, ממופתחות לפי מזהה מפעיל. מזהה המפעיל והדרישות שבדוגמה הם בדיוניים. ייתכן שיוחזרו שדות ספק נוספים.

מבנה תגובה להמחשה; לא נתוני חשבון חיים ולא הצעת מחיר נוכחית.

{
  "usecase": "2FA",
  "minSubUsecases": 0,
  "maxSubUsecases": 0,
  "mnoMetadata": {
    "12345": {
      "mnoSupport": true,
      "qualify": true,
      "minMsgSamples": 1,
      "reqSubscriberOptin": true,
      "reqSubscriberOptout": true,
      "reqSubscriberHelp": true,
      "noEmbeddedLink": false,
      "noEmbeddedPhone": false
    }
  }
}

שגיאות

• 401: אימות החשבון נכשל. בדקו את פרטי הכניסה ל-API, את מצב ההפעלה ואת הגבלות כתובת ה-IP של המקור הרלוונטיות.
• 404: המותג אינו משויך לחשבון המאומת, או שהספק אינו מוצא את המותג או הבחירה המבוקשים. דחיית בעלות מקומית מוחזרת לפני בקשה לספק.
• שגיאות רישום אחרות: סטטוס ה-HTTP והגוף מהמערכת במעלה הזרם נשמרים. מקרה שימוש לא תקף או לא זמין אינו קבוצת דרישות ריקה מוצלחת.
• 429: הושגה מגבלת הבקשות של החשבון או של הספק המשותף. כבדו את Retry-After.
• 502/503: כשל זמינות של התעבורה, הספק או מגביל הקצב. שמרו את הטופס ונסו שוב עם המתנה מדורגת (backoff).

זמינות ותופעות לוואי

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