دریافت اعلان‌های فشار برای تغییرات داده‌های محصولتان

شما می‌توانید از API اعلان‌های فروشنده برای دریافت اعلان‌های فوری برای تغییرات در داده‌های محصول استفاده کنید. به عنوان مثال، اگر در اعلان‌های تغییر وضعیت محصول مشترک شوید، می‌توانید در صورت عدم تأیید یک محصول، به صورت آنی مطلع شوید. می‌توانید در اعلان‌های مربوط به هر یک از حساب‌های فرعی یا سایر حساب‌های مرتبط خود مشترک شوید.

این راهنما نمونه‌هایی از نحوه مدیریت اعلان‌ها برای تغییرات وضعیت محصول را ارائه می‌دهد. می‌توانید از این مثال‌ها برای مدیریت اعلان‌ها برای سایر رویدادها با تغییر مقدار فیلد registeredEvent در درخواست‌های خود استفاده کنید. برای لیست کامل انواع رویدادها، به مرجع Merchant Notifications API مراجعه کنید.

اشتراک

برای دریافت اعلان‌ها، به یک callBackUri نیاز دارید. URL مربوط به فراخوانی شما باید شرایط زیر را داشته باشد:

• باید یک آدرس HTTPS با دسترسی عمومی و دارای گواهی SSL معتبر باشد که توسط یک مرجع صدور گواهی امضا شده باشد.
• باید درخواست‌های HTTP POST را با هدر Content-Type و مقدار application/json بپذیرد.
• برای تأیید دریافت اعلان، باید یکی از کدهای پاسخ زیر را برگرداند.
  • 102
  • 200
  • 201
  • 202
  • 204

شما می‌توانید از یک آدرس فراخوانی یکسان برای چندین اشتراک استفاده کنید. توصیه می‌کنیم برای هر حساب کاربری پیشرفته و هر نوع رویداد، از یک آدرس فراخوانی منحصر به فرد استفاده کنید تا بار درخواست‌های ارسالی به یک آدرس واحد به حداقل برسد.

در اینجا یک نمونه درخواست برای اشتراک در اعلان‌های مربوط به تغییرات وضعیت محصول برای یک حساب تجاری خاص آورده شده است.

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

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

موارد زیر را جایگزین کنید:

• ACCOUNT_ID : شناسه منحصر به فرد حسابی که باید اعلان‌ها را دریافت کند.
• TARGETACCOUNT_ID : شناسه منحصر به فرد حسابی که می‌خواهید درباره آن اعلان دریافت کنید.

اگر حساب مرکز فروش شما یک حساب مستقل و بدون حساب‌های مرتبط است و می‌خواهید اعلان‌ها را برای حساب خودتان دریافت کنید، هر دو این متغیرها را با شناسه حساب خود جایگزین کنید.

فراخوانی‌های موفق، name برای اشتراک شما، شامل شناسه اشتراک، برمی‌گردانند:

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

شما می‌توانید از این name برای GET و DELETE اشتراک‌های تکی استفاده کنید.

شما می‌توانید با وارد کردن "allManagedAccounts": true به جای targetAccount در درخواست خود، در اعلان‌های مربوط به تغییرات وضعیت محصول برای همه حساب‌های کاربری لینک‌شده خود مشترک شوید:

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

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

برای به‌روزرسانی یک اشتراک موجود، PATCH به همراه update_mask برای مشخص کردن فیلدهایی که می‌خواهید به‌روزرسانی کنید و مقادیر جدید در بدنه JSON استفاده کنید:

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

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

رمزگشایی اعلان‌ها

پس از ایجاد اشتراک، اعلان‌هایی را در callBackUri مشخص شده با فرمت زیر دریافت خواهید کرد:

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

داده‌های اعلان رمزگذاری شده‌اند. می‌توانید داده‌ها را به فرمت متنی قابل خواندن رمزگشایی کنید تا در پیاده‌سازی خود از آنها استفاده کنید. در اینجا یک نمونه کنترلر 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/TARGETACCOUNT_ID",
  "managingAccount": "accounts/ACCOUNT_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/TARGETACCOUNT_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 ، FREE_LISTINGS_UCP_CHECKOUT ) از مقدار شمارشی ReportingContextEnum پشتیبانی می‌کند.

برای رویداد تغییر وضعیت محصول، فیلدهای oldValue و newValue یکی از این مقادیر را خواهند داشت: ( approved , pending , disapproved , ``).

فیلد eventTime زمان ایجاد خود رویداد را در خود نگه می‌دارد، اگر می‌خواهید پیام‌ها را مرتب کنید، باید به مقدار موجود در آن فیلد تکیه کنید و به ترتیب دریافت پیام‌ها تکیه نکنید.

برای جزئیات بیشتر، فرمت ProductStatusChangeMessage را دنبال کنید.

پیاده‌سازی خود را آزمایش کنید

در اینجا یک نمونه اعلان وجود دارد که می‌توانید برای آزمایش URI و رمزگشایی callback خود استفاده کنید:

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"
}