مهم: API محتوا برای خرید در ۱۸ آگوست ۲۰۲۶ غیرفعال شد.

از ۱ سپتامبر ۲۰۲۶ ، رابط برنامه‌نویسی کاربردی محتوا برای درخواست‌های خرید با خطاهای پیش‌رونده مواجه خواهد شد. راهنمای انقضای رابط برنامه‌نویسی کاربردی محتوا را مرور کنید.

اگر برای مهاجرت به Merchant API به زمان بیشتری نیاز دارید، برای دسترسی بیشتر به Content API for Shopping درخواست دهید .

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

مدیریت موافقت با «شرایط خدمات Merchant Center»

برای استفاده از Merchant Center و ویژگی‌های آن، باید شرایط خدمات Merchant Center (ToS) را برای مکان کسب‌وکارتان بپذیرید. این قراردادها شرایط قانونی استفاده از خدمات Merchant Center را مشخص می‌کنند.

این راهنما توضیح می‌دهد که چگونه می‌توانید از Merchant API برای مدیریت این قراردادها استفاده کنید، چه برای حساب خودتان و چه برای حساب‌هایی که به‌عنوان ارائه‌دهنده طرف سوم (3P) مدیریت می‌کنید.

می‌توانید به موارد زیر دست یابید:

وضعیت فعلی قرارداد «شرایط خدمات» را برای یک حساب بررسی کنید.
راهنمایی کردن فروشندگان برای پذیرفتن «شرایط خدمات» لازم.
«شرایط خدمات» را به‌عنوان رساننده خدمات برای حساب‌های مشتری مدیریت کنید.

پیش‌نیازها

برای استفاده از Merchant API به حساب Merchant Center نیاز دارید. پس‌از اینکه آن را بااستفاده از میانای کاربر (UI) Merchant Center ایجاد کردید، می‌توانید تغییراتی در حساب ایجاد کنید (مثلاً اطلاعات کسب‌وکارتان را به‌روز کنید، کاربران را مدیریت کنید، و غیره) یا بااستفاده از میانای کاربر یا بااستفاده از API.

اگر نیاز به مدیریت چندین حساب دارید، می‌توانید بااستفاده از Merchant API حساب‌های مشتری ایجاد کنید. ایجاد حساب‌ها را ببینید.

بررسی وضعیت موافقت حساب با «شرایط خدمات»

قبل‌از اینکه فروشنده بتواند به‌طور کامل از Merchant Center استفاده کند، یا اگر نیاز دارید وضعیت قرارداد فعلی او را درستی‌سنجی کنید، می‌توانید وضعیت قرارداد «شرایط خدمات» او را بازیابی کنید.

از روش termsOfServiceAgreementStates.retrieveForApplication برای دریافت وضعیت قرارداد «شرایط خدمات» برای برنامه اصلی Merchant Center استفاده کنید. این روش «شرایط خدمات» فعلی شما را برمی‌گرداند، درصورت وجود، و اگر «شرایط خدمات» از آخرین باری که آن را پذیرفته‌اید به‌روز شده باشد، جدیدترین نسخه‌ای را که باید بپذیرید برمی‌گرداند.

در اینجا یک درخواست نمونه آورده شده است:

GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/termsOfServiceAgreementStates:retrieveForApplication

تماس موفق یک TermsOfServiceAgreementState منبع برمی‌گرداند. این منبع شامل موارد زیر است:

name: شناسه وضعیت این قرارداد.
‫regionCode: کشوری که این وضعیت قرارداد در آن اعمال می‌شود، معمولاً کشور کسب‌وکار حساب.
‫termsOfServiceKind: MERCHANT_CENTER خواهد بود.
‫accepted: جزئیات مربوط به نسخه «شرایط خدمات» که حساب قبلاً پذیرفته است، ازجمله نام منبع termsOfService (برای نمونه، termsOfService/132) و اینکه چه کسی آن را acceptedBy. همچنین ممکن است تاریخ validUntil را دربرگیرد اگر نسخه جدیدتری از «شرایط خدمات» required باشد.
‫required: جزئیات مربوط به نسخه «شرایط خدمات» که حساب باید آن را بپذیرد. این شامل نام منبع termsOfService و tosFileUri اشاره‌کننده به سند «شرایط خدمات» قابل‌خواندن برای انسان است.

پاسخ نمونه:

{
  "name": "accounts/{ACCOUNT_ID}/termsOfServiceAgreementStates/MERCHANT_CENTER-{REGION_CODE}",
  "regionCode": "{REGION_CODE}",
  "termsOfServiceKind": "MERCHANT_CENTER",
  "accepted": {
    "termsOfService": "termsOfService/132",
    "acceptedBy": "accounts/{ACCOUNT_ID}"
  },
  "required": {
    "termsOfService": "termsOfService/132",
    "tosFileUri": "https://www.google.com/intl/{REGION_CODE}/policies/merchants/terms/"
  }
}

اگر «شرایط خدمات» جدیدی required، باید فروشنده را راهنمایی کنید آن را بپذیرد.

در اینجا نمونه‌ای آورده شده است که می‌توانید از آن برای بازیابی وضعیت قرارداد «شرایط خدمات» برای حساب و کشور خاصی استفاده کنید:

جاوا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.GetTermsOfServiceAgreementStateRequest;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceAgreementState;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceAgreementStateName;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceAgreementStateServiceClient;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceAgreementStateServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/**
 * This class demonstrates how to get a TermsOfServiceAgreementState for a specific
 * TermsOfServiceKind and country.
 */
public class GetTermsOfServiceAgreementStateSample {

  public static void getTermsOfServiceAgreementState(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

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

    // Creates TermsOfServiceAgreementState name to identify TermsOfServiceAgreementState.
    String name =
        TermsOfServiceAgreementStateName.newBuilder()
            .setAccount(config.getAccountId().toString())
            // The Identifier is: "{TermsOfServiceKind}-{country}"
            .setIdentifier("MERCHANT_CENTER-US")
            .build()
            .toString();

    System.out.println(name);

    // Calls the API and catches and prints any network failures/errors.
    try (TermsOfServiceAgreementStateServiceClient termsOfServiceAgreementStateServiceClient =
        TermsOfServiceAgreementStateServiceClient.create(
            termsOfServiceAgreementStateServiceSettings)) {

      // The name has the format:
      // accounts/{account}/termsOfServiceAgreementStates/{TermsOfServiceKind}-{country}
      GetTermsOfServiceAgreementStateRequest request =
          GetTermsOfServiceAgreementStateRequest.newBuilder().setName(name).build();

      System.out.println("Sending Get TermsOfServiceAgreementState request:");
      TermsOfServiceAgreementState response =
          termsOfServiceAgreementStateServiceClient.getTermsOfServiceAgreementState(request);

      System.out.println("Retrieved TermsOfServiceAgreementState below");
      // If the terms of service needs to be accepted, the "required" field will include the
      // specific version of the terms of service which needs to be accepted, alongside a link to
      // the terms of service itself.
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }


  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    getTermsOfServiceAgreementState(config);
  }
}GetTermsOfServiceAgreementStateSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\Client\TermsOfServiceAgreementStateServiceClient;
use Google\Shopping\Merchant\Accounts\V1\GetTermsOfServiceAgreementStateRequest;

/**
 * Demonstrates how to get a TermsOfServiceAgreementState.
 */
class GetTermsOfServiceAgreementState
{

    /**
     * Gets a TermsOfServiceAgreementState.
     *
     * @param array $config The configuration data.
     * @return void
     */
    public static function getTermsOfServiceAgreementState($config): void
    {
        // Get OAuth credentials.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Create client options.
        $options = ['credentials' => $credentials];

        // Create a TermsOfServiceAgreementStateServiceClient.
        $termsOfServiceAgreementStateServiceClient = new TermsOfServiceAgreementStateServiceClient($options);

        // Service agreeement identifier
        $identifier = "MERCHANT_CENTER-US";

        // Create TermsOfServiceAgreementState name.
        $name = "accounts/" . $config['accountId'] . "/termsOfServiceAgreementStates/" . $identifier;

        print $name . PHP_EOL;

        try {
            // Prepare the request.
            $request = new GetTermsOfServiceAgreementStateRequest([
                'name' => $name,
            ]);

            print "Sending Get TermsOfServiceAgreementState request:" . PHP_EOL;
            $response = $termsOfServiceAgreementStateServiceClient->getTermsOfServiceAgreementState($request);

            print "Retrieved TermsOfServiceAgreementState below\n";
            print $response->serializeToJsonString() . PHP_EOL;
        } catch (ApiException $e) {
            print $e->getMessage();
        }
    }

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

        self::getTermsOfServiceAgreementState($config);
    }

}

// Run the script
$sample = new GetTermsOfServiceAgreementState();
$sample->callSample();GetTermsOfServiceAgreementStateSample.php

Python

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import GetTermsOfServiceAgreementStateRequest
from google.shopping.merchant_accounts_v1 import TermsOfServiceAgreementStateServiceClient

# Replace with your actual value.
_ACCOUNT_ID = configuration.Configuration().read_merchant_info()
_IDENTIFIER = "MERCHANT_CENTER-US"  # Replace with your identifier


def get_terms_of_service_agreement_state():
  """Gets a TermsOfServiceAgreementState for a specific TermsOfServiceKind and country."""

  credentials = generate_user_credentials.main()
  client = TermsOfServiceAgreementStateServiceClient(credentials=credentials)

  name = (
      "accounts/"
      + _ACCOUNT_ID
      + "/termsOfServiceAgreementStates/"
      + _IDENTIFIER
  )

  print(name)

  request = GetTermsOfServiceAgreementStateRequest(name=name)

  try:
    print("Sending Get TermsOfServiceAgreementState request:")
    response = client.get_terms_of_service_agreement_state(request=request)
    print("Retrieved TermsOfServiceAgreementState below")
    print(response)
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  get_terms_of_service_agreement_state()
get_terms_of_service_agreement_state_sample.py

پذیرفتن شرایط خدمات

فروشندگان باید «شرایط خدمات» جدید را بپذیرند تا دسترسی به ویژگی‌های Merchant Center را حفظ کنند.

«شرایط خدمات» را برای حساب خودتان بپذیرید

اگر حساب Merchant Center خودتان را مدیریت می‌کنید، این کارها را انجام دهید:

برای شناسایی اینکه آیا «شرایط خدمات» required است یا نه، با termsOfServiceAgreementStates.retrieveForApplication تماس بگیرید.
اگر «شرایط خدمات» الزامی است، نام termsOfService را از فیلد required یادداشت کنید (برای مثال، termsOfService/132).
برای پذیرفتن «شرایط خدمات»، با termsOfService.accept تماس بگیرید. به نام «شرایط خدمات»، ACCOUNT_ID، و regionCode برگشت‌داده‌شده توسط retrieveForApplication نیاز دارید.

در اینجا یک درخواست نمونه آورده شده است:
```
POST https://merchantapi.googleapis.com/accounts/v1/{name={termsOfService/VERSION}}:accept
{
  "account": "accounts/{ACCOUNT_ID}",
  "regionCode": "{REGION_CODE}"
}
```
تماس موفقیت‌آمیز بدنه پاسخ خالی برمی‌گرداند و وضعیت موافقت حساب با «شرایط خدمات» را به‌روز می‌کند.

راهنمایی کردن فروشندگان برای پذیرفتن «شرایط خدمات» (برای ارائه‌دهندگان طرف سوم)

اگر ارائه‌دهنده طرف سوم (3P) هستید که حساب‌های Merchant Center را برای کسب‌وکارهای دیگر مدیریت می‌کنید، نباید «شرایط خدمات» را ازطرف آن‌ها بپذیرید. درعوض، باید:

بازیابی جدیدترین «شرایط خدمات»: برای دریافت جزئیات جدیدترین نسخه «شرایط خدمات» که ممکن است لازم باشد فروشنده بپذیرد، termsOfService.retrieveLatest را برای نوع regionCode و MERCHANT_CENTER فروشنده فراخوانی کنید.

درخواست نمونه:
```
GET https://merchantapi.googleapis.com/accounts/v1/termsOfService:retrieveLatest?regionCode={REGION_CODE}&kind=MERCHANT_CENTER
```
پاسخ نمونه:
```
{
    "name": "{termsOfService/VERSION}",
    "regionCode": "{REGION_CODE}",
    "kind": "MERCHANT_CENTER",
    "fileUri": "https://www.google.com/intl/{REGION_CODE}/policies/merchants/terms/"
}
```
نمایش «شرایط خدمات»: از fileUri در پاسخ برای نمایش متن کامل «شرایط خدمات» به فروشنده در «میانای کاربری» برنامه‌تان استفاده کنید.
دریافت پذیرش فروشنده: فروشنده باید صراحتاً با شرایط مندرج در واسط کاربر شما موافقت کند.
ثبت پذیرش بااستفاده از API: پس‌از اینکه فروشنده پذیرفت، بااستفاده از name «شرایط خدمات» که در مرحله ۱ به‌دست آمده است، ACCOUNT_ID فروشنده، و regionCode او را فراخوانی کنید. termsOfService.accept

درخواست نمونه:
```
POST https://merchantapi.googleapis.com/accounts/v1/{name={termsOfService/VERSION}}:accept
{
  "account": "accounts/{MERCHANT_ACCOUNT_ID}",
  "regionCode": "{REGION_CODE}"
}
```

در اینجا نمونه‌ای وجود دارد که می‌توانید از آن برای پذیرفتن قرارداد «شرایط خدمات» برای یک حساب معین استفاده کنید (پس‌از اینکه فروشنده موافقت کرد):

جاوا

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AcceptTermsOfServiceRequest;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceServiceClient;
import com.google.shopping.merchant.accounts.v1.TermsOfServiceServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to accept the TermsOfService agreement in a given account. */
public class AcceptTermsOfServiceSample {

  public static void acceptTermsOfService(String accountId, String tosVersion, String regionCode)
      throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

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

    // Calls the API and catches and prints any network failures/errors.
    try (TermsOfServiceServiceClient tosServiceClient =
        TermsOfServiceServiceClient.create(tosServiceSettings)) {

      // The parent has the format: accounts/{account}
      AcceptTermsOfServiceRequest request =
          AcceptTermsOfServiceRequest.newBuilder()
              .setName(String.format("termsOfService/%s", tosVersion))
              .setAccount(String.format("accounts/%s", accountId))
              .setRegionCode(regionCode)
              .build();

      System.out.println("Sending request to accept terms of service...");
      tosServiceClient.acceptTermsOfService(request);

      System.out.println("Successfully accepted terms of service.");
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    // See GetTermsOfServiceAgreementStateSample to understand how to check which version of the
    // terms of service needs to be accepted, if any.
    // Likewise, if you know that the terms of service needs to be accepted, you can also simply
    // call RetrieveLatestTermsOfService to get the latest version of the terms of service.
    // Region code is either a country when the ToS applies specifically to that country or 001 when
    // it applies globally.
    acceptTermsOfService(config.getAccountId().toString(), "VERSION_HERE", "REGION_CODE_HERE");
  }
}AcceptTermsOfServiceSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\AcceptTermsOfServiceRequest;
use Google\Shopping\Merchant\Accounts\V1\Client\TermsOfServiceServiceClient;

/**
 * Demonstrates how to accept the TermsOfService agreement in a given account.
 */
class AcceptTermsOfService
{

    /**
     * Accepts the Terms of Service agreement.
     *
     * @param string $accountId The account ID.
     * @param string $tosVersion The Terms of Service version.
     * @param string $regionCode The region code.
     * @return void
     */
    public static function acceptTermsOfService($accountId, $tosVersion, $regionCode): void
    {
        // Get OAuth credentials.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Create client options.
        $options = ['credentials' => $credentials];

        // Create a TermsOfServiceServiceClient.
        $tosServiceClient = new TermsOfServiceServiceClient($options);

        try {
            // Prepare the request.
            $request = new AcceptTermsOfServiceRequest([
                'name' => sprintf("termsOfService/%s", $tosVersion),
                'account' => sprintf("accounts/%s", $accountId),
                'region_code' => $regionCode,
            ]);

            print "Sending request to accept terms of service...\n";
            $tosServiceClient->acceptTermsOfService($request);

            print "Successfully accepted terms of service.\n";
        } catch (ApiException $e) {
            print $e->getMessage();
        }
    }

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

        // Replace with actual values.
        $tosVersion = "132";
        $regionCode = "US";

        self::acceptTermsOfService($config['accountId'], $tosVersion, $regionCode);
    }
}

// Run the script
$sample = new AcceptTermsOfService();
$sample->callSample();AcceptTermsOfServiceSample.php

Python

from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AcceptTermsOfServiceRequest
from google.shopping.merchant_accounts_v1 import TermsOfServiceServiceClient

# Replace with your actual values.
_ACCOUNT_ID = configuration.Configuration().read_merchant_info()
_TOS_VERSION = (  # Replace with the Terms of Service version to accept
    "VERSION_HERE"
)
_REGION_CODE = "US"  # Replace with the region code


def accept_terms_of_service():
  """Accepts the Terms of Service agreement for a given account."""

  credentials = generate_user_credentials.main()
  client = TermsOfServiceServiceClient(credentials=credentials)

  # Construct the request
  request = AcceptTermsOfServiceRequest(
      name=f"termsOfService/{_TOS_VERSION}",
      account=f"accounts/{_ACCOUNT_ID}",
      region_code=_REGION_CODE,
  )

  try:
    print("Sending request to accept terms of service...")
    client.accept_terms_of_service(request=request)
    print("Successfully accepted terms of service.")
  except RuntimeError as e:
    print(e)


if __name__ == "__main__":
  accept_terms_of_service()
accept_terms_of_service_sample.py

ملاحظات ویژه برای ارائه‌دهندگان طرف سوم

به‌عنوان ارائه‌دهنده طرف سوم، می‌توانید «شرایط خدمات» را برای حساب‌های مشتری مدیریت کنید.

مدیریت «شرایط خدمات» برای حساب‌های مشتری

اگر یک حساب پیشرفته را اداره می‌کنید و برای کسب‌وکارهای مختلف حساب‌های مشتری ایجاد می‌کنید:

پذیرش حساب پیشرفته: اگر حساب پیشرفته‌ای خدمات تجمیع حساب را به حساب‌های مشتری ارائه دهد، «شرایط خدمات» پذیرفته‌شده توسط حساب پیشرفته برای همه حساب‌های مشتری آن سرویس نیز اعمال خواهد شد.
نمایش و موافقت: حتی اگر پذیرش حساب پیشرفته حساب‌های مشتری را پوشش دهد، رویه مطلوب این است (و شاید انتظار قانونی این باشد) که «شرایط خدمات» مربوط به Google Merchant Center را به مالک کسب‌وکار واقعی هریک از این مشتریان نشان دهید. باید رضایت صریح او را دریافت کنید که این شرایط را درک می‌کند و با آن موافق است، حتی اگر تماس «میانای برنامه‌سازی کاربردی» برای پذیرش در سطح حساب پیشرفته برقرار شود.
بررسی وضعیت حساب مشتری: از termsOfServiceAgreementStates.retrieveForApplication در حساب مشتری خاصی استفاده کنید تا وضعیت «شرایط خدمات» آن را تأیید کنید و ببینید آیا تحت پوشش قرارداد حساب پیشرفته است یا اقدام مستقیمی لازم است.

مدیریت «شرایط خدمات» برای حساب‌های دیگر

همان‌طور که در راهنمای بازرگانان برای پذیرفتن «شرایط خدمات» توضیح داده شده است، وقتی به کسب‌وکاری در ایجاد یا مدیریت حساب خودش کمک می‌کنید، آن کسب‌وکار (مالک حساب) باید شخصاً «شرایط خدمات» را بپذیرد . شما با بازیابی و نمایش «شرایط خدمات» و سپس فراخوانی روش termsOfService.accept ازطرف آن‌ها پس‌از اینکه ازطریق واسط شما رضایت صریح خود را اعلام کردند، این کار را تسهیل می‌کنید.

قبلی

Manage business identity

بعدی

Create and update regions