تلقّي إشعارات فورية بشأن التغييرات في بيانات منتجاتك

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

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

اشتراك

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

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

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

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

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: المعرّف الفريد للحساب الذي تريد تلقّي إشعارات بشأنه.

إذا كان حسابك على Merchant Center حسابًا مستقلاً بدون حسابات مرتبطة، وأردت تلقّي إشعارات لحسابك الخاص، استبدِل كلا هذين المتغيّرَين برقم تعريف حسابك.

تعرض الطلبات الناجحة a 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 لتحديد الحقول التي تريد تعديلها والقيم الجديدة في نص HTTP:

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 الخاص بالردّ على طلبات معاودة الاتصال وعملية فك الترميز:

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