מעבר מגרסה 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: השדה 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 כדי להוסיף את האדמין הראשוני לחשבון.