دریافت اعلان لحظه‌ای برای تغییرات سرویس حساب

می‌توانید در اعلان‌های ACCOUNT_SERVICE_CHANGE مشترک شوید تا هنگام ایجاد، به‌روزرسانی، یا حذف منابع AccountService، هشدارهای هم‌زمان دریافت کنید. این به‌ویژه برای ارائه‌دهندگان طرف سوم و کسب‌وکارهایی که روابط خدماتی چندحسابی را مدیریت می‌کنند ارزشمند است.

با مشترک شدن در تغییرات سرویس حساب، می‌توانید بلافاصله بدون نظرسنجی از API، پیشنهاد، تأیید، به‌روزرسانی، یا حذف شدن سرویس حساب را تشخیص دهید.

قبل‌از شروع، مطمئن شوید که URI فراخوان شما مطابق با الزامات شرح‌داده‌شده در نمای کلی زیر-API اعلان‌ها پیکربندی شده است.

مشترک شدن در تغییرات سرویس حساب

برای مشترک شدن در تغییرات سرویس حساب، درخواست 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"
}

رمزگشایی بار داده‌های تغییر سرویس حساب

وقتی تغییری در سرویس حساب رخ می‌دهد، شناسه منبع یکسان فراخوان شما پیامی با کدبندی 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"
}