Gerenciar contratos dos Termos de Serviço do Merchant Center

Para usar o Merchant Center e os recursos dele, é necessário aceitar os Termos de Serviço (TOS) do Merchant Center para o local da sua empresa. Esses contratos descrevem os termos legais para usar os serviços do Merchant Center.

Este guia explica como usar a API Merchant para gerenciar esses contratos, seja para sua própria conta ou para contas que você gerencia como um provedor terceirizado (3P).

Você pode fazer o seguinte:

  • Verifica o status atual do contrato de Termos de Serviço de uma conta.
  • Oriente os comerciantes a aceitar os Termos de Serviço necessários.
  • Gerenciar os Termos de Serviço como um provedor terceirizado para contas de clientes ou contas independentes.

Pré-requisitos

Para usar a API Merchant, você precisa de uma conta do Merchant Center. Depois de criar a conta usando a interface do usuário (IU) do Merchant Center, você pode fazer mudanças nela (por exemplo, atualizar as informações comerciais, gerenciar usuários etc.) usando a IU ou a API.

Se você precisar gerenciar várias contas, crie contas de cliente usando a API Merchant. Consulte Criar e gerenciar subcontas.

Verificar o estado do contrato de Termos de Serviço de uma conta

Antes que um comerciante possa usar totalmente o Merchant Center ou se você precisar verificar o status atual do contrato, é possível recuperar o estado do contrato de Termos de Serviço.

Use o método termsOfServiceAgreementStates.retrieveForApplication para acessar o estado do contrato de Termos de Serviço do aplicativo principal do Merchant Center. Esse método retorna os TOS atuais, se houver, e, se eles tiverem sido atualizados desde sua última aceitação, a versão mais recente que você precisa aceitar.

Confira um exemplo de solicitação:

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

Uma chamada bem-sucedida retorna um recurso TermsOfServiceAgreementState. Esse recurso contém:

  • name: o identificador do estado do contrato.
  • regionCode: o país a que esse estado de contrato se aplica, geralmente o país da empresa da conta.
  • termsOfServiceKind: será MERCHANT_CENTER.
  • accepted: detalhes sobre a versão dos Termos de Serviço que a conta já aceitou, incluindo o nome do recurso termsOfService (como termsOfService/132) e quem acceptedBy. Também pode incluir uma data de validUntil se uma versão mais recente dos ToS for required.
  • required: detalhes sobre uma versão dos Termos de Serviço que a conta precisa aceitar. Isso inclui o nome do recurso termsOfService e um tosFileUri que aponta para o documento dos Termos de Serviço legível.

Exemplo de resposta:

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

Se um novo ToS estiver required, oriente o comerciante a aceitá-lo.

Confira um exemplo que pode ser usado para recuperar o estado do contrato dos Termos de Serviço de uma conta e um país específicos:

Java

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

Aceite os Termos de Serviço

Os comerciantes precisam aceitar os Termos de Serviço mais recentes para manter o acesso aos recursos do Merchant Center.

Aceitar os Termos de Serviço da sua conta

Se você estiver gerenciando sua própria conta do Merchant Center, faça o seguinte:

  1. Chame termsOfServiceAgreementStates.retrieveForApplication para identificar se algum TdS é required.
  2. Se for necessário, anote o nome termsOfService do campo required (por exemplo, termsOfService/132).

  3. Chame termsOfService.accept para aceitar os Termos de Serviço. Você vai precisar do nome dos Termos de Serviço, do seu ACCOUNT_ID e do regionCode retornado por "retrieveForApplication".

    Confira um exemplo de solicitação:

    POST https://merchantapi.googleapis.com/accounts/v1/{name={termsOfService/VERSION}}:accept
{
  "account": "accounts/{ACCOUNT_ID}",
  "regionCode": "{REGION_CODE}"
}

    Uma chamada bem-sucedida retorna um corpo de resposta vazio e atualiza o estado de concordância com os Termos de Serviço da conta.

Oriente os comerciantes a aceitar os Termos de Serviço (para provedores terceirizados)

Se você for um provedor terceirizado (3P) que gerencia contas independentes do Merchant Center para outras empresas, não aceite os Termos de Serviço em nome delas. Em vez disso, faça o seguinte:

  1. Recupere os Termos de Serviço mais recentes: chame termsOfService.retrieveLatest para o tipo regionCode e MERCHANT_CENTER do comerciante e receba os detalhes da versão mais recente dos Termos de Serviço que ele precisa aceitar.

    Exemplo de solicitação:

    GET https://merchantapi.googleapis.com/accounts/v1/termsOfService:retrieveLatest?regionCode={REGION_CODE}&kind=MERCHANT_CENTER

    Exemplo de resposta:

    {
    "name": "{termsOfService/VERSION}",
    "regionCode": "{REGION_CODE}",
    "kind": "MERCHANT_CENTER",
    "fileUri": "https://www.google.com/intl/{REGION_CODE}/policies/merchants/terms/"
}

  2. Mostrar os Termos de Serviço: use o fileUri da resposta para mostrar o texto completo dos Termos de Serviço ao comerciante na interface do seu aplicativo.

  3. Obter a aceitação do comerciante: o comerciante precisa concordar explicitamente com os termos na sua interface.

  4. Registre a aceitação usando a API: depois que o comerciante aceitar, chame termsOfService.accept usando o name dos Termos de Serviço obtidos na etapa 1, o ACCOUNT_ID do comerciante e o regionCode dele.

    Exemplo de solicitação:

    POST https://merchantapi.googleapis.com/accounts/v1/{name={termsOfService/VERSION}}:accept
{
  "account": "accounts/{MERCHANT_ACCOUNT_ID}",
  "regionCode": "{REGION_CODE}"
}

Confira um exemplo que você pode usar para aceitar o contrato dos Termos de Serviço de uma determinada conta (depois que o comerciante concordar):

Java

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

Considerações especiais para provedores terceirizados

Como um provedor terceirizado, você pode gerenciar os Termos de Serviço para contas de clientes ou contas independentes.

Gerenciar os Termos de Serviço das contas de clientes

Se você opera uma conta avançada e cria contas de cliente para diferentes empresas:

  • Aceitação avançada de contas: se uma conta avançada fornecer o serviço de agregação de contas para contas de clientes, os Termos de Serviço aceitos pela conta avançada também serão aplicáveis a todas as contas de clientes com esse serviço.
  • Exibição e consentimento: mesmo que a aceitação da conta avançada abranja as contas de cliente, é uma prática recomendada (e pode ser uma expectativa legal) exibir os Termos de Serviço relevantes do Google Merchant Center para o proprietário real de cada conta de cliente. Você precisa receber o consentimento explícito de que eles entendem e concordam com estes termos, mesmo que a chamada de API para aceitação seja feita no nível da conta avançada.
  • Verificar o status da conta do cliente: use termsOfServiceAgreementStates.retrieveForApplication em uma conta de cliente específica para verificar o status dos Termos de Serviço e saber se ela está coberta pelo contrato da conta avançada ou se alguma ação direta é necessária.

Gerenciar os Termos de Serviço de contas independentes

Conforme detalhado em Orientar comerciantes a aceitar os Termos de Serviço, quando você ajuda uma empresa a criar ou gerenciar uma conta independente do Merchant Center, ela (o proprietário da conta) precisa aceitar pessoalmente os Termos de Serviço. Para facilitar isso, recupere e mostre os TdS e chame o método termsOfService.accept em nome deles depois que eles derem consentimento explícito pela sua interface.

Anterior
Overview
Avançar
Create and manage sub-accounts