טעינת קטלוגים לרישום הודעות

טענו אפשרויות לפני בניית טופס רישום

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

בחרו קטלוג

טפלו בתשובת TCR ישירות

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

הפרידו בין אפשרויות הקטלוג לבין זכאות ותמחור

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

טפלו בקטלוגים שאינם זמינים

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

בקשה

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

שלחו בקשת GET עם שם קטלוג נתמך בנתיב. העבירו מסנני קטלוג רלוונטיים במחרוזת השאילתה. אין צורך בגוף בקשה.

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/tcr/v2/enum/usecase?validSubUsecase=true"

תשובה

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

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

{
  "2FA": {
    "displayName": "Authentication",
    "description": "Example authentication use case"
  }
}

שגיאות

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

זמינות והשפעות נלוות

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