يمكنك تلقّي إشعارات فورية بالتغييرات التي تطرأ على بيانات حسابك.

يمكنك استخدام واجهة برمجة التطبيقات Merchant Notifications API للحصول على إشعارات فورية بشأن التغييرات التي تطرأ على بيانات الحساب. على سبيل المثال، إذا اشتركت في خدمة تلقّي إشعارات بشأن تغيير حالة المنتج، يمكن أن يتمّ إشعارك في الوقت الفعلي عندما يتم رفض منتج. يمكنك الاشتراك في الإشعارات لأي من حساباتك الفرعية أو حساباتك المرتبط الأخرى.

يقدّم هذا الدليل أمثلة على كيفية إدارة الإشعارات بشأن تغيُّرات حالة المنتج. يمكنك استخدام هذه الأمثلة لإدارة الإشعارات للأحداث الأخرى من خلال تغيير قيمة الحقل registeredEvent في طلباتك. للحصول على قائمة كاملة بأنواع الأحداث، اطّلِع على مرجع Merchant Notifications API.

اشتراك

لتلقّي الإشعارات، تحتاج إلى callBackUri. يجب أن يستوفي عنوان URL لطلب إعادة الاتصال المتطلبات التالية:

• يجب أن يكون عنوان HTTPS متاحًا للجميع وأن يتضمّن شهادة طبقة المقابس الآمنة (SSL) صالحة موقَّعة من مرجع تصديق.
• يجب قبول طلبات HTTP POST باستخدام العنوان Content-Type وقيمة application/json.
• يجب عرض أحد رموز الاستجابة التالية للإشارة إلى تلقّي الإشعار.
  • 102
  • 200
  • 201
  • 202
  • 204

يمكنك استخدام عنوان URL نفسه للرجوع إلى اشتراكات متعددة. ننصحك باستخدام معرّف فريد لعنوان URL للرجوع لكل حساب متقدّم، ولكل نوع حدث بهدف تقليل عدد طلبات الإرسال الفوري إلى عنوان URL واحد.

إليك نموذج طلب للاشتراك في الإشعارات بشأن تغييرات حالة المنتج لحساب تاجر معيّن. استخدِم رقم تعريف التاجر للحساب الذي يجب أن يتلقّى الإشعارات على أنّه 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}"}}

يتم ترميز بيانات الإشعار. يمكنك فك ترميز البيانات إلى تنسيق نصي قابل للقراءة لاستخدامه في عملية التنفيذ. في ما يلي نموذج عنصر تحكّم في 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) من قيمة التعداد 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}

استجابةً لهذا الطلب، من المفترض أن يعرض عنوان URL لمعاودة الاتصال رمز استجابة ناجحة. يجب أن تحتوي الرسالة التي تم فك تشفيرها على القيمة التالية:

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