סקירה כללית של Merchant Products API

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

Merchant Products API מכיל שני משאבים.

• productInputs represents the input parts of your products.
• products מייצג את המוצרים שעברו עיבוד ונוצרו מחלקי הקלט.

השדה productInputs יכול להיות ראשי ומשלים, בהתאם לכך שהוא הועלה למקור נתונים ראשי או למקור נתונים משלים. כל product מורכב מ-productInput ראשי אחד ומכל מספר של productInputs משלימים.

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

למרות שלמוכרים יש אפשרות להעלות מוצרים באמצעות קובץ שנקרא PrimaryProductDataSource, יש כמה יתרונות ליצירה ולמחיקה של מוצרים באמצעות Merchant API. היתרונות האלה כוללים זמני תגובה מהירים יותר ויכולת לעדכן מוצרים בזמן אמת, בלי צורך לנהל קבצים גדולים. יכול להיות שיחלפו כמה שעות עד ששינויים במוצרים שבוצעו באמצעות קריאות ל-API יופיעו במסד הנתונים של שופינג.

דרישות מוקדמות

אם אין לכם מקור נתונים, יוצרים מקור נתונים באמצעות Merchant DataSources API או Merchant Center.

אם כבר יש לכם מקור נתונים שיצרתם באמצעות ממשק המשתמש של Merchant Center או באמצעות ה-API, תוכלו להשתמש ב-Merchant Products API כדי להוסיף את המוצרים שלכם. אם אתם משתמשים ב-Content API for Shopping כדי להוסיף מוצרים, תוכלו לעיין במדריך להעברה כדי להבין איך מתחילים להשתמש ב-Merchant Products API.

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

משאבים

המשאב products מאפשר לאחזר פרטי מוצרים ממסד הנתונים של Shopping.

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

• channel: הערוץ של המוצר.
• offerId: המזהה הייחודי של המוצר.
• contentLanguage: קוד השפה בן שתי האותיות של המוצר לפי תקן ISO 639-1.
• feedLabel: תווית הפיד של המוצר.

העלאת קלט של מוצרים לחשבון

כדי להעלות קלט של מוצר לחשבון, משתמשים בשיטה accounts.productInputs.insert. צריך להעביר את המזהה הייחודי של מקור הנתונים הראשי או המשלים.

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

POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE}

{
  "name": "{PRODUCT_TITLE}",
  "versionNumber": {VERSION_NUMBER},
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "offerId": "{OFFER_ID}",
  "channel": "ONLINE",
  "attributes": {
    "availability": "in stock",
    "imageLink": "{IMAGE_LINK}",
    "link": "{PRODUCT_LINK}",
    "brand": "{BRAND_NAME}",
    "price": {
      "currencyCode": "{CURRENCY_CODE}",
      "amountMicros": {PRICE}
    },
    "color": "red",
    "productWeight": {
      "value": 320,
      "unit": "g"
    },
    "adult": false,
    "shipping": [
      {
        "country": "GB",
        "price": {
          "amountMicros": {SHIPPING_COST},
          "currencyCode": "{CURRENCY_CODE_SHIPPING}"
        },
        "postalCode": "{SHIPPING_POSTALCODE}",
        "service": "",
        "region": "{SHIPPING_REGION}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}"
      }
    ],
    "gender": "Female"
  },
  "customAttributes": [
    {
      "name": "size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

מחליפים את מה שכתוב בשדות הבאים:

• {ACCOUNT_ID}: המזהה הייחודי של חשבון Merchant Center.
• {DATASOURCE}: המזהה הייחודי של מקור הנתונים. הפורמט הנדרש הוא accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}.
• {PRODUCT_TITLE}: שם המוצר.
• {VERSION_NUMBER}: מספר הגרסה של המוצר. זה שינוי אופציונלי.
• {CONTENT_LANGUAGE}: קוד השפה בן שתי האותיות של המוצר לפי תקן ISO 639-1. חובה.
• {FEED_LABEL}: קוד האזור במאגר CLDR של האזור שבו רוצים למכור את המוצר. אם הערך שצוין בשדה feedLabel לא תקין, השדה targetCountry לא מאוכלס.
• {OFFER_ID}: המזהה הייחודי של המוצר. חובה.
• {IMAGE_LINK}: הקישור לתמונה של המוצר באתר שלכם. זה שינוי אופציונלי.
• {PRODUCT_LINK}: הקישור למוצר באתר שלכם. זה שינוי אופציונלי.
• ‫{CURRENCY_CODE}: המטבע של המחיר, באמצעות ראשי תיבות של שלוש אותיות בהתאם ל-ISO 4217. זה שינוי אופציונלי.
• {PRICE}: המחיר של המוצר, שמוצג כמספר ב-micros. זה שינוי אופציונלי.
• {SHIPPING_COST}: מחיר המשלוח הקבוע שמוצג כמספר. זה שינוי אופציונלי.
• {SHIPPING_POSTALCODE}: טווח המיקוד שבו חל תעריף המשלוח. זה שינוי אופציונלי.
• {MAX_HANDLING_TIME}: זמן הטיפול המקסימלי בימי עסקים ממועד קבלת ההזמנה ועד לשליחתה. זה שינוי אופציונלי.
• {MIN_HANDLING_TIME}: זמן הטיפול המינימלי בימי עסקים ממועד קבלת ההזמנה ועד למועד השליחה שלה. הערך 0 מציין שההזמנה נמסרת באותו יום שבו היא מתקבלת. זה שינוי אופציונלי.
• {MAX_TRANSIT_TIME}: זמן האספקה המקסימלי בימי עסקים ממועד שליחת ההזמנה ועד למועד המסירה שלה. זה שינוי אופציונלי.
• {MIN_TRANSIT_TIME}: זמן האספקה המינימלי בימי עסקים ממועד שליחת ההזמנה ועד למועד המסירה. הערך 0 מציין שההזמנה תימסר באותו יום שבו היא תישלח. זה שינוי אופציונלי.

אם הבקשה פועלת בהצלחה, תוצג התגובה הבאה:

{
  "name": "{PRODUCT_NAME}",
  "product": "{PRODUCT_ID}",
  "channel": "ONLINE",
  "offerId": "{OFFER_ID}",
  "contentLanguage": "{CONTENT_LANGUAGE}",
  "feedLabel": "{FEED_LABEL}",
  "versionNumber": "{VERSION_NUMBER}",
  "attributes": {
    "link": "{PRODUCT_LINK}",
    "imageLink": "{IMAGE_LINK}",
    "adult": false,
    "availability": "in stock",
    "brand": "{BRAND_NAME}",
    "color": "red",
    "gender": "Female",
    "price": {
      "amountMicros": "{PRICE}",
      "currencyCode": "{CURRENCY_CODE}"
    },
    "shipping": [
      {
        "price": {
          "amountMicros": "{SHIPPING_COST}",
          "currencyCode": "{CURRENCY_CODE}"
        },
        "country": "{SHIPPING_COUNTRY}",
        "region": "{SHIPPING_REGION}",
        "postalCode": "{SHIPPING_POSTALCODE}",
        "minHandlingTime": "{MIN_HANDLING_TIME}",
        "maxHandlingTime": "{MAX_HANDLING_TIME}",
        "minTransitTime": "{MIN_TRANSIT_TIME}",
        "maxTransitTime": "{MAX_TRANSIT_TIME}"
      }
    ],
    "productWeight": {
      "value": 320,
      "unit": "g"
    }
  },
  "customAttributes": [
    {
      "name": "Size",
      "value": "Large"
    },
    {
      "name": "Date of Manufacturing",
      "value": "2024-05-05"
    }
  ]
}

אחזור מוצר מעובד מהחשבון

כדי לאחזר מוצר מעובד מהחשבון, משתמשים בשיטה accounts.products.get. יכול להיות שיחלפו כמה דקות עד שהמוצר המעובד יופיע אחרי ההוספה.

אפשר לקבל את שם המשאב של המוצר המעובד מהשדה product בתגובה של accounts.productInputs.insert

מחיקת קלט של מוצר מהחשבון

כדי למחוק קלט של מוצר מהחשבון, משתמשים ב-method‏ accounts.productInputs.delete. כדי למחוק מוצר באמצעות Merchant Products API, צריך להעביר את המזהה הייחודי של מקור הנתונים הראשי או המשלים שאליו המוצר שייך.

הצגת מוצרים מהחשבון

כדי לקבל רשימה של המוצרים שעברו עיבוד בחשבון, משתמשים ב-method‏ accounts.products.list.