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

يمكنك استخدام واجهة برمجة التطبيقات 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/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}"}}

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

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

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