עדכון מותג להעברת הודעות

תיקון מותג קיים להעברת הודעות

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

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

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

שמירה על שדות המותג הנוכחיים

הכינו את brand-update.json מתוך הרשומה הנוכחית, ובחרו רק שדות מותג הניתנים לכתיבה. שמרו על זהות העסק ועל הערכים הנדרשים האחרים בעת ביצוע התיקון הרצוי. אל תשלחו את כל תגובת GET: השדה brandId, תוצאות זהות ומצב, חותמות זמן ושדות אחרים המיועדים לתגובה בלבד אינם שייכים לעדכון.

סכמת העדכון מחייבת את entityType, displayName, country, email ואת brandRelationship. הכללים הייחודיים לסוג הישות עדיין חלים. עבור ארגון, שמרו על שם החברה המשפטי, מזהה המס והמדינה שהנפיקה אותו, הכתובת וענף הפעילות, לפי העניין. עבור עסק בבעלות יחיד, שמרו במקום זאת על השדות הרלוונטיים של השם האישי ופרטי הקשר בטלפון הנייד. השתמשו בערכים הנוכחיים האמיתיים, ולא במצייני המיקום מדוגמת רישום.

קבוצות שדות לעדכון מותג
שדות	אופן השימוש בהם
displayName, email, phone	שם מותג שניתן לזהות ופרטי קשר תקינים. האורכים המרביים: 255, 100 ו-20 תווים. השתמשו בתבנית מספר טלפון בינלאומית עם הסימן + וקידומת המדינה.
street, city, state, postalCode, country	כתובת עסק אמיתית שפרטיה עקביים. המגבלות: 255, 100, 20, 10 ו-2 תווים. השתמשו בקודים העדכניים של מדינות ארצות הברית כאשר הדבר רלוונטי.
entityType, companyName, ein, einIssuingCountry	זהות משפטית. שינויים אלה מוגבלים כאשר קמפיינים או הליכי בדיקה חיצונית ממתינים או פעילים. אל תמחקו קמפיינים מתפקדים רק כדי לעקוף מגבלה על שינוי זהות.
firstName, lastName, mobilePhone, businessContactEmail	פרטי זהות או פרטי קשר לצורכי אימות, כאשר הם מתאימים לסוג הישות. המגבלות: 100, 100, 20 ו-255 תווים.
brandRelationship, vertical	הקודים הנוכחיים של הקשר ושל ענף הפעילות. שינויי קשר מוגבלים לפעם אחת בשלושה חודשים. טופס העריכה הרגיל של הפורטל אינו מאפשר שינויי קשר.
website, altBusinessIdType, altBusinessId, stockSymbol, stockExchange	אתר האינטרנט, פרטי הזהות העסקית החלופית ופרטי החברה הציבורית הרלוונטיים. שמרו על הערכים הדרושים לאימות הישות.
referenceId, ipAddress	מטא-נתונים נתמכים של אסמכתה עסקית ושל כתובת המקור בפרוטוקול האינטרנט. אף אחד מהם אינו קובע בעלות של חשבון ואינו משמש כמפתח האידמפוטנטיות של הבקשה.

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

שליחת התיקון שנבדק

curl --silent --show-error --fail-with-body --user "$API_USER:$API_PASSWORD" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data-binary @brand-update.json \
  "https://api.multitel.net/tcr/v2/brand/$BRAND_ID"

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

בדיקת הרשומה שנשמרה ומצב האימות

עדכון מוצלח מחזיר HTTP 200 ואובייקט JSON ישיר של המותג, ללא מעטפת status/response הישנה של v3. בדקו את brandId שלו, ואז אחזרו שוב את אותו מותג באמצעות GET והשוו את השדות המיועדים. נתיב העדכון הציבורי אינו מקבל את מעטפת changes/version של הפורטל ואינו מספק את בדיקת המקביליות האופטימית שלו. תאמו בין עורכים הפועלים במקביל; מפתח אידמפוטנטיות מונע שליחה כפולה, אך אינו מונע שינויים של עורך אחר.

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

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

פתרון שגיאות ללא יצירת רישום כפול

קראו את מצב HTTP ואת פרטי השגיאה ב-JSON. עבור 400, תקנו את השדה המסוים או פעלו בהתאם למגבלה על זהות או קשר. עבור 401, 403 או 404, בדקו את פרטי ההזדהות, את כתובת המקור המורשית בפרוטוקול האינטרנט ואת הבעלות של החשבון. עבור 429, פעלו לפי Retry-After. שגיאת 500 או 502 עשויה להתרחש לאחר שהמרשם קיבל את העדכון; שמרו כל requestId שהתקבל וקראו את הרשומה הקיימת לפני שליחה נוספת.

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