מעבר מגרסה 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 שמשמש לאימות.

• לא משנה איך קוראים לממשקי ה-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 כדי להוסיף את האדמין הראשוני לחשבון.