מעבר מגרסה v1beta לגרסה v1

המדריך הזה יעזור לכם לעבור מ-Merchant API v1beta אל v1, הגרסה הראשונה שזמינה לכולם. גרסה 1 כוללת כמה עדכונים וכמה שינויים שעשויים לחייב עדכוני קוד. השינויים האלה נועדו לפשט את ה-API ולשפר את הניהול של חשבון Merchant Center.

ההבדלים העיקריים

אלה השינויים הכי חשובים שצריך להכיר כשעוברים מ-v1beta ל-v1:

• רישום חד-פעמי של לפחות מפתח API אחד לשימוש ב-Merchant API: תצטרכו להפעיל את השיטה registerGcp (רק פעם אחת לכל פרויקט Google Cloud שמשמש לאימות) כדי לספק את פרטי הקשר שלכם. כך תוכלו להשתמש ב-API ולקבל עדכונים והודעות שקשורים ל-Merchant API. לא תהיה לכם אפשרות להשתמש באף API של v1 או v1alpha עד שתשלימו את השלב הזה. הוראות מפורטות מופיעות במאמר בנושא הרשמה כמפתח.

• קידוד שם המוצר: השדות ProductInput.name ו- Product.name תומכים בקידוד base64url ללא ריפוד (RFC 4648 סעיף 5). חשוב להקפיד על ההנחיות הבאות:

  • לפני הקידוד, המחרוזת צריכה להיות בפורמט contentLanguage~feedLabel~offerId.

  • קידוד הוא חובה אם שם המוצר מכיל תווים שמשמשים את Merchant API או תווים שמורים בכתובת URL, כמו:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • אם שם המוצר שלכם עומד בדרישות contentLanguage~feedLabel~offerId הפורמט ולא מכיל תווים שמשמשים את Merchant API או תווים שמורים בכתובות URL, אתם יכולים להשתמש בפורמט הרגיל, ללא קידוד.

  • כדי להבטיח ניתוח עקבי ונכון, מומלץ להשתמש בקידוד base64url לא מרופד לכל שמות המוצרים.

• הסרת פרטי מס ברמת המוצר: המאפיינים taxes ו-taxCategory.

• Product.attributes שינוי שם: השם של השדה Product.attributes שונה ל-Product.productAttributes.

• הסרת פרטי מס ברמת המוצר: השדות taxes ו-taxCategory הוסרו מהאובייקט Product.productAttributes. מידע נוסף זמין במאמר הזה במרכז העזרה של Google Merchant Center בנושא מיסים.

• שינויים בשדה GTIN: השם של השדה gtin באובייקט Product.productAttributes שונה ל-gtins כדי לשקף טוב יותר את העובדה שאפשר להזין בו כמה ערכים. השדה gtin באובייקט OrderTrackingSignals.lineItemDetails הוא עכשיו array, ושמו שונה ל-gtins.

• הסרת השדה 'ערוץ': השדה channel הוסר מהמוצרים, מקלט המוצרים וממקורות הנתונים. הוספנו שדה בוליאני חדש, legacyLocal, כדי לציין בבירור מוצרים שנמכרים רק בחנויות פיזיות. הערה: השדה legacyLocal הוא שדה עזר שנועד לעזור בתהליך ההעברה. בסופו של דבר הוא יוצא משימוש אחרי שיהיה אפשר לטרגט באופן מלא שיטות שיווק אונליין ומקומיות באמצעות מקור מוצרים יחיד. פרטים נוספים מופיעים בטבלה שבקטע הבא.

• שדות חדשים למאפייני מלאי אזורי ומקומי:

  • כל השדות של RegionalInventory למעט name, account ו-region עכשיו עטופים באובייקט חדש שנקרא regionalInventoryAttributes . לדוגמה, המאפיין RegionalInventory.price נמצא עכשיו בקטע RegionalInventory.regionalInventoryAttributes.price.
  • כל השדות של LocalInventory למעט name, account ו-storeCode עכשיו עטופים באובייקט חדש שנקרא localInventoryAttributes . לדוגמה, המאפיין LocalInventory.price נמצא עכשיו בקטע LocalInventory.localInventoryAttributes.price.

• הסרה של customAttributes ממלאי אזורי וממלאי בחנות מקומית: השדה customAttributes הוסר מהמשאבים RegionalInventory ו-LocalInventory.

• יצירת חשבון משופרת: השדה המיותר users הוסר מה-CreateAndConfigureAccountRequest. משתמשים בשדה user כדי לשייך משתמש ראשוני לחשבון חדש.

• סוגים מסוימים של מאפיינים השתנו ממחרוזות לרשימות מוגדרות מראש: חלק מהשדות במשאבי Product ו-Inventory עם רשימה קצרה מוגדרת של ערכים השתנו מסוג string לסוג enum כדי לשפר את אימות הנתונים (לדוגמה, השדה Product.ProductAttributes.condition הוא עכשיו enum).

• הסרה של שיטת עדכון מדיניות החזרת מוצרים אונליין: השיטה onlineReturnPolicy.update הוסרה בגרסה v1. במקום זאת, צריך ליצור מדיניות החזרת מוצרים באינטרנט באמצעות השיטה onlineReturnPolicy.create.

איך מבצעים את ההעברה

הגרסה v1beta של Merchant API מתוכננת לצאת משימוש ב-28 בפברואר 2026. מידע נוסף על לוח הזמנים להוצאה משימוש זמין במדריך לניהול גרסאות של Merchant API.

• השלב הראשון בתהליך ההעברה הוא לבצע רישום חד-פעמי כמפתח (ראו רישום כמפתח). כדי ששיטות v1 יעבדו, צריך להפעיל את שיטת registerGcp לכל פרויקט ב-Google Cloud שמשמש לאימות.

• לא משנה איך קוראים לממשקי ה-API (עם REST, ‏ gRPC או באמצעות ספריות לקוח), אפשר לבצע את המעבר בשלבים. המשמעות היא שאפשר לעדכן ולהעביר את הקוד שלכם API אחד בכל פעם (לדוגמה, להעביר את Products API ל-v1 ולהשאיר את Accounts API ב-v1beta) בלי לעדכן את השילוב כולו בבת אחת.

שינויים מפורטים בשדות

בטבלה הזו מוצגת השוואה מפורטת של השדות שהשתנו בין גרסאות v1beta ו-v1.

v1beta	v1	תיאור
ProductInput.name	ProductInput.name	Unpadded base64url encoding נתמך וחובה לשימוש בשמות מוצרים שמכילים תווים שמשמשים את Merchant API או תווים שמורים ב-URL.
Product.name	Product.name	Unpadded base64url encoding נתמך וחובה לשימוש בשמות מוצרים שמכילים תווים שמשמשים את Merchant API או תווים שמורים ב-URL.
Product.gtin	Product.gtins	השם של השדה של מספרי ה-GTIN השתנה.
Product.taxes	הוסר	השדה taxes הוסר
Product.taxCategory	הוסר	השדה taxCategory הוסר
Product.channel	הוסר	השדה channel הוסר. משתמשים בשדה legacyLocal לתרחישים מקומיים.
Product.attributes	Product.productAttributes	השם של השדה attributes השתנה ל-productAttributes.
השדות availability, ‏ condition, ‏ gender, ‏ includedDestinations ו-excludedDestinations ב-Product מוצגים כ-strings (או כ-array מתוך strings)	השדות האלה הם עכשיו enums (או array מתוך enums)	השדות עם רשימה קצרה מוגדרת של ערכים השתנו מסוג string לסוג enum.
‫price, salePrice, salePriceEffectiveDate וגם availability בRegionalInventory	הועברה אל RegionalInventory.regionalInventoryAttributes	השדות האלה הועברו לקטע regionalInventoryAttributes.
השדה RegionalInventory.availability הוא string	מעכשיו התפקיד של RegionalInventory.regionalInventoryAttributes.availability הוא enums	הסוג של מאפיין הזמינות השתנה מ-string ל-enum.
‫price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla וinstoreProductLocation ב-LocalInventory	הועברה אל LocalInventory.localInventoryAttributes	השדות האלה הועברו לקטע localInventoryAttributes.
השדה LocalInventory.availability הוא string	מעכשיו התפקיד של LocalInventory.localInventoryAttributes.availability הוא enums	הסוג של מאפיין הזמינות השתנה מ-string ל-enum.
LocalInventory.customAttributes	הוסר	אין יותר תמיכה במאפיינים בהתאמה אישית למלאי של חנויות מקומיות.
RegionalInventory.customAttributes	הוסר	אין יותר תמיכה במאפיינים מותאמים אישית למלאי אזורי.
ProductInput.channel	הוסר	השדה channel הוסר. משתמשים בשדה legacyLocal לתרחישים מקומיים.
DataSource.channel	הוסר	השדה channel הוסר. משתמשים בשדה legacyLocal לתרחישים מקומיים.
לא זמין	ProductInput.legacyLocal	שדה בוליאני חדש שמציין שמוצר יכול להיות מיועד רק לשיטות שיווק מקומיות. מזהה משאב המוצר יכלול את הקידומת local~.
לא זמין	Product.legacyLocal	שדה בוליאני חדש שמציין שמוצר נמכר רק בחנויות מקומיות ולא זמין לרכישה אונליין.
לא זמין	DataSource.legacyLocal	שדה בוליאני חדש שמציין שמקור נתונים מכיל מוצרים שנמכרים רק בחנויות מקומיות.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	השם של השדה gtin השתנה ל-gtins, ועכשיו הוא מערך של מחרוזות (במקום מחרוזת).
CreateAndConfigureAccountRequest.users	הוסר	השדה users הוסר. משתמשים בשדה user כדי להוסיף את האדמין הראשוני לחשבון.