إدارة علاقات الحسابات

يمكنك استخدام Accounts API لإدارة العلاقات بين حسابك على Merchant Center ومقدّمي الخدمات الآخرين. العلاقة هي اتصال رسمي يتيح لمقدّم الخدمة تقديم خدمات معيّنة لنشاطك التجاري. تحدّد الخدمة الأذونات والإمكانات الممنوحة لمقدّم الخدمة، مثل إدارة المنتجات أو إدارة الحملات. على سبيل المثال، يتيح ربط حسابك على Merchant Center بحساب على "إعلانات Google" لحساب "إعلانات Google" استخدام بيانات منتجاتك لإطلاق الحملات الإعلانية.

تتألف العلاقة من السمات التالية:

  • حساب Merchant Center الذي يتلقّى الخدمة
  • مقدّم الخدمة
  • الخدمة أو مجموعة الخدمات التي يتم تقديمها إلى حساب Merchant Center

الاسم المستعار

يمكن لمقدّمي الخدمات ربط اسم مستعار بالحسابات التي يقدّمون خدمات لها (هذا هو المكافئ للحقل seller_id الذي كان موجودًا في مورد account في Content API for Shopping). يمكن تعيين الاسم المستعار باستخدام حقل account_id_alias الاختياري ضمن مورد AccountRelationship، وهو يعمل كمعرّف مخصّص. يجب أن يتألف الاسم المستعار من حرف واحد إلى 50 حرفًا يتم اختيارها من أحرف ASCII أو الأرقام العشرية أو الواصلات أو الشرطات السفلية أو النقاط أو علامات التلدة ([A-Za-z0-9_~.-]{1,50}).

بنية عنوان URL للوصول إلى حساب باستخدام عنوانه البديل هي GET /accounts/v1/accounts/{provider}~{account_id_alias}.

الخدمات

في Accounts API، يمكن للحسابات تلقّي الخدمات التالية. يمكنك إضافة العديد من هذه الخدمات أثناء إنشاء الحساب.

  • تجميع الحسابات: تربط هذه الخدمة (accountAggregation) حسابًا متعدّد العملاء بامتيازات متقدّمة بحساب فرعي، ما يمنح الحساب بامتيازات متقدّمة إذن وصول كاملاً وغير مقيّد ويجعل الحساب الفرعي مرئيًا في واجهة مستخدم Merchant Center. تحوّل واجهة مستخدم Merchant Center الحسابات تلقائيًا إلى حسابات بامتيازات متقدّمة باستخدام accountAggregation لمنشئي المتاجر (منصات التجارة الإلكترونية) وشركاء القنوات والأسواق وبائعي التجزئة الذين يبيعون منتجات لعلامات تجارية متعددة وبائعي التجزئة الدوليين عند إنشاء حسابات فرعية جديدة. إذا كنت تمثّل وكالة، يُرجى استخدام accountManagement بدلاً من ذلك. عند إنشاء حساب باستخدام تجميع الحسابات، يجب حذف externalAccountId.

  • إدارة الحملات: تنشئ هذه الخدمة رابطًا بين حساب Merchant Center وحساب "إعلانات Google"، ما يمنح حساب "إعلانات Google" إذن الوصول إلى بيانات المنتجات والحسابات اللازمة لإطلاق الحملات الإعلانية. مقدّم الخدمة في هذه الحالة هو GOOGLE_ADS، وexternalAccountId هو رقم تعريف حساب "إعلانات Google". يمكن أيضًا اقتراح هذه الخدمة لحساب حالي.

  • تتيح هذه الخدمة إنشاء فلاتر منتجات معيّنة خاصة بالشركاء عند إطلاق حملات شبكة الإعلانات القائمة على البيانات التجارية.
  • في الوقت الحالي، يجب استخدام إصدار ألفا من واجهة Accounts sub-API.
  • يتطلّب استخدام هذه الميزة إدراج حسابك على Google Merchant Center في القائمة المسموح بها.

يُرجى التواصل مع فريق إدارة حسابك على "إعلانات Google" لمزيد من التفاصيل.

  • مقارنة الأسعار: تمثّل هذه العلاقة خدمة مقارنة الأسعار (CSS) التي تدير حساب Merchant Center.

  • إدارة البيانات المحلية: تمثّل هذه العلاقة مع مدير المتجر لإدارة المخزون المحلي والبيانات باستخدام "الملف التجاري على Google".

  • إدارة الحساب: تتيح هذه الخدمة (accountManagement) لمقدّم الخدمة تنفيذ إجراءات إدارية على حساب Merchant Center خارجي مستقل، مثل ضبط إعدادات الحساب أو إدارة المستخدمين أو تعديل معلومات النشاط التجاري. ويمكن للمؤسسة أيضًا تقييد إمكانية الوصول الممنوحة. عند استخدام هذه الخدمة أثناء إنشاء الحساب، يتم إنشاء حساب مستقل مرتبط بمقدّم الخدمة. ويمكن أيضًا اقتراحه لحساب حالي. يمكن للوكالات التي تستخدم هذا النوع من الخدمات الاطّلاع على الحسابات التي تديرها في Merchant Center للوكالات. يمكن لمطوّري المتاجر وشركاء القنوات استخدام Merchant API للحصول على معلومات عن التجّار الذين يديرونهم من خلال accountManagement.

  • إدارة المنتجات: تتيح هذه الخدمة لمقدّمي الخدمات إدارة المنتجات والميزات ذات الصلة، مثل مصادر البيانات والقواعد. عند إضافته أثناء إنشاء الحساب، يكون عادةً مع accountManagement أو accountAggregation. يمكن أيضًا اقتراح هذه الخدمة لحساب حالي.

  • إدارة الدفع في UCP (v1alpha، وصول محدود): تتيح خدمة ucpCheckoutManagement لمقدّم خدمة معتمَد إدارة عمليات دمج الدفع في UCP والإعدادات والمشاركة في البرنامج نيابةً عن التاجر. لا يمكن اقتراح هذه الخدمة أو الموافقة عليها إلا من خلال حساب حالي على Merchant Center.

    ملاحظة: ميزة الدفع عبر UCP هي ميزة في الإصدار الأوّلي متاحة بشكل محدود. يمكنك الاطّلاع على مزيد من المعلومات حول مقدّمي الخدمة والدفع في UCP في مقالة Merchant Center لمقدّمي الخدمة.

مصافحة

لإنشاء خدمة، يجب أن يفوّض كل من الحساب الذي يقدّم الخدمة والحساب الذي يتلقّى الخدمة الاتصال. تسمى عملية التفويض هذه بالمصافحة.

تتألف عملية المصافحة من خطوتَين:

  1. يقترح أحد الطرفين ربط الخدمة.
  2. يوافق الطرف الآخر على الاقتراح أو يرفضه.

بعد قبول الاقتراح، تتم الموافقة على الخدمة واعتبارها قائمة بالكامل. يتم الآن منح أي حق وصول تم منحه لمقدّم الخدمة للمستخدمين المؤهَّلين (يُرجى الاطّلاع على حقوق الوصول أدناه).

يُرجى العِلم أنّ المستخدم الذي ينشئ اقتراحًا أو يرفضه أو يوافق عليه يجب أن يكون لديه ADMIN حقوق الوصول إلى الحساب الذي يبدأ العملية. لذلك، إذا اقترح مقدّم الخدمة خدمةً ما، يجب أن يكون المستخدم الذي يقدّم الاقتراح ADMIN في حساب مقدّم الخدمة، ويجب أن يكون المستخدم الذي يقبل الاقتراح أو يرفضه ADMIN في الحساب المستلِم.

توضّح النماذج التالية كيفية اقتراح خدمة حساب:

جافا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.AccountService;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceClient;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceSettings;
import com.google.shopping.merchant.accounts.v1.ProductsManagement;
import com.google.shopping.merchant.accounts.v1.ProposeAccountServiceRequest;
import shopping.merchant.samples.utils.Authenticator;

/** This class demonstrates how to propose a service to an existing Merchant Center account. */
public class ProposeServiceSample {

  public static void proposeService(long accountId, long providerId, String externalAccountId)
      throws Exception {

    // Obtains OAuth token based on the user's configuration.
    // The user that authenticates should have access to the account.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    AccountServicesServiceSettings accountServicesServiceSettings =
        AccountServicesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (AccountServicesServiceClient accountServicesServiceClient =
        AccountServicesServiceClient.create(accountServicesServiceSettings)) {

      // The service to be proposed.
      // This sample shows how to propose product management.
      // For more information about the different services, see:
      // https://developers.google.com/merchant/api/guides/accounts/services
      AccountService accountService =
          AccountService.newBuilder()
              .setProductsManagement(ProductsManagement.newBuilder().build())
              .setExternalAccountId(externalAccountId)
              .build();

      String accountName =
          AccountName.newBuilder().setAccount(String.valueOf(accountId)).build().toString();

      ProposeAccountServiceRequest request =
          ProposeAccountServiceRequest.newBuilder()
              .setParent(accountName)
              .setProvider("accounts/" + providerId)
              .setAccountService(accountService)
              .build();

      System.out.println("Sending Propose Service request:");
      AccountService response = accountServicesServiceClient.proposeAccountService(request);

      System.out.println("Proposed Service below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    // The ID of the account to propose the service to.
    long accountId = 123L;
    // This is the provider ID of the e-commerce platform.
    long providerId = 456L;
    // An external ID that uniquely identifies the account service.
    String externalAccountId = "ext-acc-id-123";
    proposeService(accountId, providerId, externalAccountId);
  }
}

PHP

require_once __DIR__ . '/../../../../vendor/autoload.php';
require_once __DIR__ . '/../../../Authentication/Authentication.php';
require_once __DIR__ . '/../../../Authentication/Config.php';

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\AccountAggregation;
use Google\Shopping\Merchant\Accounts\V1\AccountService;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountServicesServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ProposeAccountServiceRequest;

/**
 * This class demonstrates how to propose an account service.
 */
class ProposeAccountServiceSample
{
    /**
     * A helper function to create the account name string.
     *
     * @param string $accountId The ID of the account.
     *
     * @return string The account name has the format: `accounts/{account_id}`
     */
    private static function toAccountName(string $accountId): string
    {
        return sprintf('accounts/%s', $accountId);
    }

    /**
     * Proposes a new account service.
     *
     * @param array $config The configuration data used for authentication and
     *     getting the account ID.
     * @param string $providerId The ID of the provider account.
     */
    public static function proposeAccountService(
        array $config,
        string $providerId
    ): void {
        // Gets the OAuth credentials to make the request.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Creates options containing credentials for the client to use.
        $options = ['credentials' => $credentials];

        // Creates a client.
        $accountServicesServiceClient = new AccountServicesServiceClient($options);

        // Calls the API and catches and prints any network failures/errors.
        try {
            $accountAggregation = new AccountAggregation();
            $accountService = (new AccountService())
                ->setAccountAggregation($accountAggregation);

            $request = (new ProposeAccountServiceRequest())
                ->setParent(self::toAccountName($config['accountId']))
                ->setProvider(self::toAccountName($providerId))
                ->setAccountService($accountService);

            print "Sending Propose AccountService request\n";
            $response = $accountServicesServiceClient->proposeAccountService($request);
            print "Proposed AccountService below\n";
            print $response->serializeToJsonString(true) . PHP_EOL;
        } catch (ApiException $e) {
            printf("An error has occurred: %s%s", $e->getMessage(), PHP_EOL);
        }
    }

    /**
     * Helper to execute the sample.
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();

        // Update this with the Merchant Center provider ID you want to get the
        // relationship for.
        $providerId = 111;
        self::proposeAccountService($config, $providerId);
    }
}

// Run the script
$sample = new ProposeAccountServiceSample();
$sample->callSample();

Python

"""This class demonstrates how to propose an account service."""

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AccountAggregation
from google.shopping.merchant_accounts_v1 import AccountService
from google.shopping.merchant_accounts_v1 import AccountServicesServiceClient
from google.shopping.merchant_accounts_v1 import ProposeAccountServiceRequest

_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"


def propose_account_service(provider_id: int) -> None:
  """Proposes an account service.

  Args:
    provider_id: The Merchant Center ID of the provider.
  """
  # Gets OAuth Credentials.
  credentials = generate_user_credentials.main()

  # Creates a client.
  client = AccountServicesServiceClient(credentials=credentials)

  # Creates the provider resource name from the provider ID.
  provider = f"accounts/{provider_id}"

  # Creates an AccountService object.
  # For this request, only `account_aggregation` is needed.
  account_service = AccountService()
  account_service.account_aggregation = AccountAggregation()

  # Creates the request.
  request = ProposeAccountServiceRequest(
      parent=_PARENT,
      provider=provider,
      account_service=account_service,
  )

  # Makes the request and catches and prints any error messages.
  try:
    print("Sending Propose AccountService request")
    response = client.propose_account_service(request=request)
    print("Proposed AccountService below")
    print(response)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  # Update this with the Merchant Center provider ID you want to get the
  # relationship for.
  provider_id_ = 111
  propose_account_service(provider_id_)

سلوك المصافحة الخاص بالخدمة

في ما يلي وصف لمتطلبات المصافحة المحددة لكل خدمة فردية:

  • تجميع الحسابات: لا يمكن إنشاء هذه الخدمة إلا كجزء من عملية إنشاء الحساب. من المتوقّع أن يكون مقدّم الخدمة حسابًا بامتيازات متقدّمة، وتتم الموافقة على الخدمة تلقائيًا لأنّ مستخدمي الحساب بامتيازات متقدّمة لديهم إذن وصول كامل إلى ADMIN الحساب الذي يتم إنشاؤه.

  • خدمة مقارنة الأسعار: تتم الموافقة على هذه الخدمة تلقائيًا عند إضافتها أثناء إنشاء الحساب باستخدام createAndConfigure.

  • إدارة الحملات: على الرغم من أنّ هذه العملية تتّبع عملية المصافحة العادية، يتم تقديم الاقتراحات في نظام واحد (مثل "إعلانات Google") وتتم الموافقة عليها في النظام الآخر (مثل Merchant Center أو من خلال Merchant API).

  • إدارة البيانات المحلية: بالنسبة إلى هذه الخدمة، يتم اقتراح المصافحة بطريقة مخصّصة وتتم الموافقة في النظام الآخر (على سبيل المثال، "الملف التجاري على Google"). يمكنك الاطّلاع على الخطوات التفصيلية في دليل ربط ملف تجاري على Google.

  • إدارة الحساب: بالنسبة إلى هذه الخدمة، تنطبق عملية المصافحة العادية عند استخدام propose. إذا تمت إضافة الخدمة أثناء إنشاء الحساب باستخدام createAndConfigure، تتم الموافقة عليها تلقائيًا.

  • إدارة المنتجات: بالنسبة إلى هذه الخدمة، تنطبق عملية المصافحة العادية (يقترحها أحد الطرفين، ثم يقبلها الطرف الآخر).

  • إدارة الدفع في UCP (v1alpha، وصول محدود): بالنسبة إلى هذه الخدمة، يمكن للتاجر إكمال عملية تأكيد الاتصال من خلال مربّع حوار ربط الحسابات المُستضاف على Google في بوابة مقدّم الخدمة، أو باستخدام عملية تأكيد الاتصال العادية (propose متبوعة بـ approve). للحصول على تفاصيل حول عملية الدمج، يُرجى الاطّلاع على مستندات مقدّمي الخدمات في Merchant Center.

حقوق الوصول

يوفّر كل نوع خدمة مستوى معيّنًا من الوصول لمستخدمي مقدّم الخدمة على الحساب الذي تتم خدمته:

  • تجميع الحسابات: توفّر هذه الخدمة حقوق ADMIN كاملة.

  • إدارة الحملات: توفّر هذه الخدمة حق وصول مقيّد، ما يسمح لحساب "إعلانات Google" المرتبط بالوصول إلى المنتجات والمعلومات الأساسية للحساب.

  • مقارنة الأسعار: توفّر هذه الخدمة تلقائيًا حقوق ADMIN الكاملة. ومع ذلك، يمكن للمؤسسة تقييد إذن الوصول الممنوح في Merchant Center.

  • إدارة البيانات المحلية: لا توفّر هذه الخدمة أيّ حق وصول مباشر. بدلاً من ذلك، تتيح هذه الميزة مزامنة المنتجات في البيانات مع حساب Merchant Center.

ملاحظة مهمة: تنطبق حقوق الوصول الموضّحة لأنواع الخدمات التالية على مقدّمي الخدمات المعتمَدين فقط. يُرجى التواصل مع فريق الدعم إذا كنت مقدّم خدمة وتريد الاستفادة من هذه الميزة. إذا سبق أن حصلت على الموافقة لاستخدام طريقة accounts.link لإدارة المنتجات في Content API for Shopping، يمكنك استخدام هذه الخدمة في Merchant API بدون الحاجة إلى موافقات إضافية.

  • إدارة الحساب: توفّر هذه الخدمة تلقائيًا حقوق ADMIN الكاملة.

  • إدارة المنتجات: توفّر هذه الخدمة حقوق ADMIN كاملة. يُرجى العِلم أنّ هذا الإجراء سيقتصر في المستقبل على حقوق الوصول المتعلّقة بالمنتجات فقط.

  • إدارة الدفع المستند إلى بروتوكول UCP (v1alpha، وصول محدود): توفّر هذه الخدمة حقوق ADMIN كاملة. يُرجى العِلم أنّه في المستقبل، سيقتصر ذلك على حقوق الوصول المتعلّقة بالدفع في UCP فقط.

كيفية تطبيق العلاقات على المنصات الخارجية

إذا كنت تمثّل منصة تابعة لجهة خارجية تدير حسابات نيابةً عن أنشطة تجارية أخرى، يوضّح ما يلي كيفية ربط المفاهيم المختلفة ببنية حسابك:

  1. مقدّم الخدمة: حسابك بامتيازات متقدّمة
  2. الحساب الذي يتلقّى الخدمة: حساب على Merchant Center يمثّل النشاط التجاري الذي تديره
  3. الخدمة:
    • accountAggregation: تُستخدَم من قِبل منشئي المتاجر (منصات التجارة الإلكترونية) وشركاء القنوات والأسواق وبائعي التجزئة الذين يملكون علامات تجارية متعددة وينشئون حسابات فرعية جديدة نيابةً عن التجّار. تضبط واجهة مستخدم Merchant Center تلقائيًا أدوات إنشاء المتاجر وشركاء القنوات كحسابات بامتيازات متقدّمة باستخدام accountAggregation، ما يتيح لهم عرض الحسابات الفرعية وإدارتها في واجهة مستخدم Merchant Center.
    • accountManagement: تستخدمه الوكالات التي تنشئ حسابات عملاء مستقلة يملكها التاجر أو تربطها بحساباتها، ويمكنها الاطّلاع عليها في Merchant Center للوكالات. تستخدم الأنواع الأخرى من مقدّمي الخدمات طريقة accounts.list في Merchant API للاطّلاع على معلومات الحسابات المرتبطة.

للحصول على تفاصيل حول كيفية إعداد حساب بامتيازات متقدّمة وربطه بحسابات جديدة على Merchant Center، يُرجى الاطّلاع على مقالة إنشاء حسابات.

السابق
Create accounts
التالي
Control access to your account