يمكنك الاشتراك في إشعارات "ACCOUNT_SERVICE_CHANGE" لتلقّي تنبيهات في الوقت الفعلي عند إنشاء موارد "AccountService" أو تعديلها أو حذفها. ويُعدّ ذلك مفيدًا بشكل خاص لمقدّمي الخدمات الخارجيين والأنشطة التجارية التي تدير علاقات الخدمة المتعددة الحسابات.
يتيح لك الاشتراك في تغييرات خدمات الحساب رصد أي تغييرات فورًا عند اقتراح خدمة حساب أو الموافقة عليها أو تعديلها أو إزالتها، بدون الحاجة إلى إجراء استطلاع لواجهة برمجة التطبيقات.
قبل البدء، تأكَّد من ضبط معرّف الموارد المنتظم (URI) لمعاودة الاتصال وفقًا للمتطلبات الموضّحة في نظرة عامة على واجهة برمجة التطبيقات الفرعية للإشعارات.
الاشتراك في التغييرات على خدمات الحساب
للاشتراك في التغييرات على خدمة الحساب، أرسِل طلب POST إلى المورد notificationsubscriptions مع ضبط registeredEvent على ACCOUNT_SERVICE_CHANGE.
الاشتراك في حساب مستهدَف محدّد
يؤدي نموذج الطلب التالي إلى الاشتراك في تغييرات خدمة الحساب لحساب تاجر معيّن:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/
{
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"targetAccount": "accounts/{TARGETACCOUNT_ID}",
"callBackUri": "https://example.com/callback"
}
غيِّر القيم في السلسلة على الشكل التالي:
- ACCOUNT_ID: معرّف الحساب الذي يملك الاشتراك ويتلقّى الإشعارات
- TARGETACCOUNT_ID: معرّف الحساب الذي تريد تلقّي إشعارات بشأنه
الاشتراك في جميع الحسابات المُدارة
يمكن لمقدّمي الخدمات والأنشطة التجارية التي تدير حسابات تجّار متعددة الاشتراك في
تغييرات خدمة الحساب في جميع الحسابات المُدارة من خلال ضبط
allManagedAccounts: true:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/
{
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com/callback"
}
تؤدي الطلبات الناجحة إلى عرض معرّف
name
لاشتراكك، بما في ذلك معرّف اشتراك فريد:
{
"name":"accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}",
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com/callback"
}
فك ترميز حمولات تغيير خدمة الحساب
عند حدوث تغيير في خدمة الحساب، يتلقّى معرّف الموارد المنتظم (URI) لمعاودة الاتصال رسالة بترميز base64. عند فك ترميز الحمولة، تتوافق مع تنسيق
ResourceChangeMessage:
{
"account": "accounts/{TARGETACCOUNT_ID}",
"managingAccount": "accounts/{ACCOUNT_ID}",
"resourceType": "ACCOUNT_SERVICE",
"resource": "accounts/{TARGETACCOUNT_ID}/services/{SERVICE_ID}",
"operation": "CREATE",
"eventTime": "2026-08-25T10:00:00Z"
}
حقول الحمولة وقواعدها
-
account: الحساب المستهدَف الذي يملك كيان الخدمة الذي تم تغييره (accounts/{merchant_id}) -
managingAccount: الحساب الذي يدير حساب التاجر (accounts/{service_provider_id}). -
resourceType: نوع المرجع الذي تم تغييره (ACCOUNT_SERVICE) -
resource: اسم المورد الكامل لخدمة الحساب (مثلاً،accounts/{account}/services/{service}) operation: العملية التي تم تنفيذها على المورد:-
CREATE: تم إنشاء علاقة جديدة بين الحساب والخدمة. UPDATE: تم تغيير إعدادات أو أذونات خدمة حساب حالية.-
DELETE: تمت إزالة علاقة خدمة الحساب.
-
-
eventTime: الطابع الزمني الذي يشير إلى وقت إنشاء الحدث استخدِم هذا الطابع الزمني لضمان ترتيب الأحداث بشكل صحيح.
اختبار إشعارات تغيير خدمة الحساب
استخدِم نموذج الطلب التالي لاختبار ما إذا كانت نقطة نهاية معاودة الاتصال تتلقّى رسائل تغيير خدمة الحساب وتقرّ باستلامها وتفكّ ترميزها بشكل صحيح:
curl --request POST \
'https://{YOUR_CALLBACK_URI}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"message":{"data": "ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJBQ0NPVU5UX1NFUlZJQ0UiLAogICJyZXNvdXJjZSI6ICJhY2NvdW50cy8xMjM0L3NlcnZpY2VzLzEyMyIsCiAgIm9wZXJhdGlvbiI6ICJDUkVBVEUiLAogICJldmVudFRpbWUiOiAiMjAyNi0wOC0yNVQxMDowMDowMFoiCn0="}}'استجابةً لهذا الطلب، يجب أن يعرض معرّف الموارد المنتظم (URI) لمعاودة الاتصال رمز حالة HTTP مقبولاً (مثل 200 OK). تحتوي الرسالة التي تم فك ترميزها على المحتوى التالي:
{
"account": "accounts/1234",
"managingAccount": "accounts/5678",
"resourceType": "ACCOUNT_SERVICE",
"resource": "accounts/1234/services/123",
"operation": "CREATE",
"eventTime": "2026-08-25T10:00:00Z"
}