Gestire i contratti relativi ai Termini di servizio di Merchant Center

Per utilizzare Merchant Center e le relative funzionalità, devi accettare i Termini di servizio (TdS) di Merchant Center per la sede della tua attività commerciale. Questi contratti descrivono 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 in qualità di fornitore di terze parti (3P).

Puoi eseguire le seguenti operazioni:

  • Controllare lo stato attuale del contratto relativo ai TdS per un account.
  • Guidare i commercianti ad accettare i TdS necessari.
  • Gestire i TdS come fornitore di servizi per gli account cliente.

Prerequisiti

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

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

Controllare lo stato del contratto relativo ai TdS di un account

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

Utilizza il termsOfServiceAgreementStates.retrieveForApplication metodo per ottenere lo stato del contratto relativo ai TdS per l'applicazione principale di Merchant Center. Questo metodo restituisce i TdS attuali, se presenti, e, se i TdS sono stati aggiornati dall'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 TermsOfServiceAgreementState risorsa. Questa risorsa contiene:

  • name: l'identificatore per 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 che l'account ha già accettato, incluso il nome della risorsa termsOfService (ad es. termsOfService/132) e chi l'ha acceptedBy. Potrebbe includere anche una data validUntil se è required una versione più recente dei TdS.
  • required: dettagli su una versione dei TdS che l'account deve accettare. Include il nome della risorsa termsOfService e un tosFileUri che rimanda al documento dei TdS leggibile.

Risposta di esempio:

{
  "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 è required una nuova versione dei TdS, devi guidare il commerciante ad accettarla.

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 gli ultimi Termini di servizio per mantenere l'accesso alle funzionalità di Merchant Center.

Accetta i TdS per il tuo account

Se gestisci il tuo account Merchant Center:

  1. Chiama termsOfServiceAgreementStates.retrieveForApplication per verificare se è required una versione dei TdS.
  2. Se è richiesta una versione dei TdS, prendi nota del termsOfService nome dal required campo (ad es. termsOfService/132).

  3. Chiama termsOfService.accept per accettare i TdS. Avrai bisogno del nome dei TdS, del tuo ACCOUNT_ID e del 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 del contratto relativo ai TdS 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 gli account Merchant Center per altre attività, non devi accettare i TdS per loro conto. Devi invece:

  1. Recuperare gli ultimi TdS: chiama termsOfService.retrieveLatest per il regionCode e il tipo MERCHANT_CENTER del commerciante per ottenere i dettagli dell'ultima versione dei TdS che potrebbe dover accettare.

    Richiesta di esempio:

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

    Risposta di esempio:

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

  2. Visualizzare i TdS: utilizza fileUri dalla risposta per visualizzare 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 nella tua UI.

  4. Registrare l'accettazione utilizzando l'API: dopo che il commerciante ha accettato, chiama termsOfService.accept utilizzando il name dei TdS ottenuto nel passaggio 1, l'ACCOUNT_ID, e il relativo 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 TdS per gli account cliente.

Gestire i TdS per gli account cliente

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

  • 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 applicheranno anche a tutti i relativi 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'aspettativa legale) mostrare i TdS di Google Merchant Center pertinenti al proprietario dell'attività di ogni account cliente. Devi ottenere il consenso esplicito che comprenda e accetti 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 verificarne lo stato dei TdS e vedere se è coperto dal contratto dell'account avanzato o se è necessaria un'azione diretta.

Gestire i TdS per altri account

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

Indietro
Manage business identity
Avanti
Create and update regions