קבלת התראות על שינויים בנתוני החשבון

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

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

להרשמה

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

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

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

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

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/merchantId/notificationsubscriptions/

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

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

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

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

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

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/merchantId/notificationsubscriptions/

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

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

PATCH /notifications/v1beta/accounts/merchantId/notificationsubscriptions/subscriptionId?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/targetMerchantId",
  "managingAccount": "accounts/merchantId",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "eligible",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/targetMerchantId/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z"
}

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

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

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

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

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

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

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "eligible",
    "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"
}