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

אפשר להשתמש ב-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/MERCHANT_ID/notificationsubscriptions/

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

אם הקריאה תצליח, תקבלו 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/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

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

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

PATCH https://merchantapi.googleapis.com/notifications/v1beta/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"
}

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

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

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

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

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

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIgp9"}}' 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"
}