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

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

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

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

• רישום חד-פעמי של לפחות מפתח API אחד לשימוש ב-Merchant API: תצטרכו לבצע קריאה לשיטת registerGcp (רק פעם אחת לכל פרויקט בענן של Google שמשמש לאימות) כדי לספק את פרטי הקשר שלכם. כך תוכלו להשתמש ב-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 כדי להוסיף את האדמין הראשוני לחשבון.