קבלת התראות על שינויים בנתוני המוצרים

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

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

להרשמה

כדי לקבל התראות, צריך callBackUri. ה-URI של הקריאה החוזרת צריך לעמוד בדרישות הבאות:

• הכתובת צריכה להיות כתובת HTTPS שגלויה לכולם, עם אישור SSL תקף שחתום על ידי רשות אישורים.
• צריך לקבל בקשות HTTP POST עם הכותרת Content-Type והערך application/json.
• צריך להחזיר אחד מקודי התשובה הבאים כדי לאשר שההודעה התקבלה.
  • 102
  • 200
  • 201
  • 202
  • 204

אפשר להשתמש באותו URI להודעות חזרה לכמה מינויים. מומלץ להשתמש ב-URI ייחודי להודעת חזרה (callback) לכל חשבון מתקדם, לכל סוג אירוע, כדי למזער את העומס של בקשות ה-push ב-URI יחיד.

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

POST https://merchantapi.googleapis.com/notifications/v1/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

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

• MERCHANT_ID: המזהה הייחודי של החשבון שאליו צריך לשלוח את ההתראות.
• TARGETMERCHANT_ID: המזהה הייחודי של החשבון שאתם רוצים לקבל עליו התראות.

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

אם הקריאה תצליח, תקבלו name עבור המינוי, כולל מזהה מינוי:

{
  "name":"accounts/MERCHANT_ID/notificationsubscriptions/subscriptionId",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

אפשר להשתמש ב-name כדי GET ולDELETE מינויים ספציפיים.

כדי להירשם לקבלת התראות על שינויים בסטטוס המוצר בכל החשבונות המקושרים, צריך לכלול את הערך "allManagedAccounts": true במקום את הערך targetAccount בבקשה:

POST https://merchantapi.googleapis.com/notifications/v1/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com"
}

כדי לעדכן מינוי קיים, משתמשים ב-PATCH עם update_mask כדי לציין את השדות שרוצים לעדכן ואת הערכים החדשים בגוף ה-JSON:

PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/MERCHANT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri

{
  "​callBackUri": "https://my-own-personal-domain.com"
}

פענוח התראות

אחרי שיוצרים מינוי, מקבלים התראות לכתובת callBackUri שציינתם בפורמט הבא:

{"message":{"data":"{base64_encoded_string}"}}

נתוני ההתראות מקודדים. אפשר לפענח את הנתונים לפורמט טקסט קריא לשימוש בהטמעה. הנה דוגמה ל-controller של Spring Boot שאפשר להשתמש בו כדי לעבד את הנתונים המקודדים:

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void doStuff(@RequestBody String message) {
        //wrapped message
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        message = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(message);
        String decodedMessage = new String(decodedBytes);
        // Implement your business logic here
  }
}

דוגמה ל-base64_encoded_string שעבר פענוח:

{
  "account": "accounts/TARGETMERCHANT_ID",
  "managingAccount": "accounts/MERCHANT_ID",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/TARGETMERCHANT_ID/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}

אם השדה oldValue לא מופיע בהתראה, המשמעות היא שנוסף מוצר חדש לחשבון. אם השדה newValue לא מופיע, סימן שהמוצר נמחק מהחשבון.

השדה expirationTime לא יהיה קיים אם המוצר נמחק.

השדה reportingContext תומך רק בערכים (SHOPPING_ADS, ‏ LOCAL_INVENTORY_ADS, ‏ YOUTUBE_SHOPPING, ‏ YOUTUBE_CHECKOUT, ‏ YOUTUBE_AFFILIATE) מתוך ערך ה-enum ReportingContextEnum.

באירוע של שינוי סטטוס המוצר, השדות oldValue ו-newValue יכללו אחד מהערכים הבאים : (approved, pending, disapproved, ‎).

השדה eventTime מכיל את זמן היצירה של האירוע עצמו. אם רוצים למיין הודעות, צריך להסתמך על הערך בשדה הזה ולא על סדר קבלת ההודעות.

למידע נוסף, יש לפעול לפי הפורמט של ProductStatusChangeMessage.

מבצעים בדיקות של ההטמעה.

הנה הודעה לדוגמה שאפשר להשתמש בה כדי לבדוק את ה-URI של הקריאה החוזרת ואת פענוח ההודעה:

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIiwKICAiZXZlbnRUaW1lIjogIjIwMjQtMDMtMjFUMDI6NDM6NDcuNDYxNDY0WiIKfQ=="}}' https://{callBackUri}

בתגובה לקריאה הזו, ה-URI של הקריאה החוזרת צריך להחזיר קוד תגובה של הצלחה. הערך של ההודעה לאחר פענוח צריך להיות:

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z",
  "eventTime": "2024-03-21T02:43:47.461464Z"
}