Gestire i contratti relativi ai Termini di servizio di Merchant Center

Per utilizzare Merchant Center e le sue funzionalità, devi accettare i Termini di servizio di Merchant Center per la sede della tua attività. Questi contratti delineano i termini legali per l'utilizzo dei servizi di Merchant Center.

Questa guida spiega come utilizzare l'API Merchant per gestire questi contratti, sia per il tuo account sia per gli account che gestisci come fornitore di terze parti (3P).

Puoi ottenere i seguenti risultati:

  • Controlla lo stato attuale dell'accettazione dei TdS per un account.
  • Guide merchants to accept necessary ToS.
  • Gestire i TdS come fornitore di servizi per gli account cliente.

Prerequisiti

Per utilizzare l'API Merchant, devi disporre di un account Merchant Center. Una volta creato l'account utilizzando l'interfaccia utente (UI) di Merchant Center, puoi apportare modifiche all'account (ad esempio aggiornare le informazioni sull'attività, gestire gli utenti e così via) utilizzando l'UI o l'API.

Se devi gestire più account, puoi creare account cliente utilizzando l'API Merchant. Vedi Crea account.

Controlla lo stato di accettazione dei TdS di un account

Prima che un commerciante possa utilizzare appieno Merchant Center o se devi verificare lo stato del suo contratto attuale, puoi recuperare lo stato del suo contratto con i Termini di servizio.

Utilizza il metodo termsOfServiceAgreementStates.retrieveForApplication per ottenere lo stato del contratto relativo ai Termini di servizio per l'applicazione principale di Merchant Center. Questo metodo restituisce i tuoi ToS attuali, se presenti, e, se i ToS sono stati aggiornati dalla tua ultima accettazione, l'ultima versione che devi accettare.

Ecco una richiesta di esempio:

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

Una chiamata riuscita restituisce una risorsa TermsOfServiceAgreementState. Questa risorsa contiene:

  • name: l'identificatore di questo stato del contratto.
  • regionCode: il paese a cui si applica questo stato del contratto, in genere il paese dell'attività dell'account.
  • termsOfServiceKind: sarà MERCHANT_CENTER.
  • accepted: dettagli sulla versione dei TdS già accettata dall'account, tra cui il nome della risorsa termsOfService (ad esempio, termsOfService/132) e chi l'ha acceptedBy. Potrebbe anche includere una data validUntil se è required una versione più recente dei TdS.
  • required: dettagli su una versione dei TdS che l'account deve accettare. Sono inclusi il nome della risorsa termsOfService e un tosFileUri che rimanda al documento dei TdS leggibile da una persona.

Esempio di risposta:

{
  "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 sono disponibili nuovi TdS (required), devi invitare il commerciante ad accettarli.

Ecco un esempio che puoi utilizzare per recuperare lo stato del contratto relativo ai Termini di servizio per un account e un paese specifici:

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);
  }
}

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();

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()

Accetta i Termini di servizio

I commercianti devono accettare i Termini di servizio più recenti per mantenere l'accesso alle funzionalità di Merchant Center.

Accetta i TdS per il tuo account

Se gestisci il tuo account Merchant Center, segui questi passaggi:

  1. Chiama termsOfServiceAgreementStates.retrieveForApplication per identificare se i ToS sono required.
  2. Se sono richiesti i TdS, prendi nota del nome termsOfService dal campo required (ad esempio, termsOfService/132).

  3. Chiama termsOfService.accept per accettare i TdS. Ti serviranno il nome dei TdS, il tuo ACCOUNT_ID e il regionCode restituito da retrieveForApplication.

    Ecco una richiesta di esempio:

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

    Una chiamata riuscita restituisce un corpo della risposta vuoto e aggiorna lo stato di accettazione dei Termini di servizio dell'account.

Guida i commercianti ad accettare i TdS (per i fornitori di terze parti)

Se sei un fornitore di terze parti (3P) che gestisce account Merchant Center per altre attività, non devi accettare i Termini di servizio per loro conto. Invece, dovresti:

  1. Recupera i TdS più recenti: chiama termsOfService.retrieveLatest per regionCode e MERCHANT_CENTER del commerciante per ottenere i dettagli della versione più recente dei TdS che potrebbe dover accettare.

    Richiesta di esempio:

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

    Esempio di risposta:

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

  2. Mostra i TdS: utilizza il campo fileUri della risposta per mostrare il testo completo dei Termini di servizio al commerciante nell'interfaccia utente della tua applicazione.

  3. Ottenere l'accettazione del commerciante: il commerciante deve accettare esplicitamente i termini all'interno della tua UI.

  4. Registra l'accettazione utilizzando l'API: dopo che il commerciante ha accettato, chiama termsOfService.accept utilizzando il name dei TdS ottenuto nel passaggio 1, il ACCOUNT_ID del commerciante e il suo regionCode.

    Richiesta di esempio:

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

Ecco un esempio che puoi utilizzare per accettare il contratto relativo ai Termini di servizio per un determinato account (dopo che il commerciante ha accettato):

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");
  }
}

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();

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()

Considerazioni speciali per i fornitori di terze parti

In qualità di fornitore di terze parti, puoi gestire i Termini di servizio per gli account cliente.

Gestisci i TdS per gli account cliente

Se gestisci un account avanzato e crei account cliente per attività diverse:

  • Accettazione dell'account avanzato: se un account avanzato fornisce il servizio di aggregazione degli account agli account cliente, i TdS accettati dall'account avanzato si applicano anche a tutti i suoi account cliente con quel servizio.
  • Visualizzazione e consenso: anche se l'accettazione dell'account avanzato copre gli account cliente, è una best practice (e potrebbe essere un requisito legale) mostrare i Termini di servizio di Google Merchant Center pertinenti al proprietario dell'attività effettivo di ogni cliente. Devi ottenere il loro consenso esplicito che confermi che comprendono e accettano questi termini, anche se la chiamata API per l'accettazione viene effettuata a livello di account avanzato.
  • Controllo dello stato dell'account cliente: utilizza termsOfServiceAgreementStates.retrieveForApplication su un account cliente specifico per verificare lo stato dei TdS e vedere se è coperto dal contratto dell'account avanzato o se è necessaria un'azione diretta.

Gestisci i TdS per altri account

Come descritto in Guida i commercianti ad accettare i Termini di servizio, quando aiuti un'attività a creare o gestire il proprio account, questa (il proprietario dell'account) deve accettare personalmente i Termini di servizio . Per farlo, recupera e visualizza i TdS, quindi chiama il metodo termsOfService.accept per loro conto dopo che hanno dato il loro consenso esplicito tramite la tua interfaccia.

Indietro
Manage homepage settings
Avanti
Manage Merchant Center email preferences