Per utilizzare Merchant Center e le sue funzionalità, devi accettare i Termini di servizio di Merchant Center per la tua sede attività. Questi contratti delineano i termini legali per l'utilizzo dei servizi 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.
Puoi ottenere i seguenti risultati:
- Controlla lo stato attuale dell'accordo Termini di servizio per un account.
- Guidare i commercianti ad accettare i Termini di servizio necessari.
- Gestisci i Termini di servizio come fornitore di terze parti per account cliente o account autonomi.
Prerequisiti
Per utilizzare l'API Merchant, devi disporre di un account Merchant Center. Una volta creato utilizzando l'interfaccia utente (UI) di Merchant Center, puoi apportare modifiche all'account (ad esempio, aggiornare i dati dell'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. Consulta Creare e gestire subaccount.
Controllare lo stato di accettazione dei Termini di servizio 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 suo contratto dei Termini di servizio.
Utilizza il metodo
termsOfServiceAgreementStates.retrieveForApplication
per ottenere lo stato dell'accettazione dei Termini di servizio per l'applicazione principale Merchant Center.
Questo metodo restituisce i Termini di servizio correnti, se presenti, e, se i Termini di servizio sono stati aggiornati
dalla tua ultima accettazione, l'ultima versione che devi accettare.
Ecco una richiesta di esempio:
GET https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/termsOfServiceAgreementStates:retrieveForApplication
Una chiamata riuscita restituisce una risorsa
TermsOfServiceAgreementState. Questa risorsa contiene:
name: l'identificatore per questo stato del contratto.regionCode: il paese a cui si applica lo stato del contratto, in genere il paese dell'attività dell'account.termsOfServiceKind: il valore saràMERCHANT_CENTER.accepted: dettagli sulla versione dei TdS che l'account ha già accettato, incluso il nome della risorsatermsOfService(ad esempio,termsOfService/132) e chi l'haacceptedBy. Potrebbe anche includere una datavalidUntilse èrequireduna versione più recente dei TdS.required: Dettagli su una versione dei TdS che l'account deve accettare. Questo include il nome della risorsatermsOfServicee untosFileUriche rimanda al documento dei Termini di servizio leggibile.
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 stati required nuovi Termini di servizio, 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.v1beta.GetTermsOfServiceAgreementStateRequest;
import com.google.shopping.merchant.accounts.v1beta.TermsOfServiceAgreementState;
import com.google.shopping.merchant.accounts.v1beta.TermsOfServiceAgreementStateName;
import com.google.shopping.merchant.accounts.v1beta.TermsOfServiceAgreementStateServiceClient;
import com.google.shopping.merchant.accounts.v1beta.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\V1beta\Client\TermsOfServiceAgreementStateServiceClient;
use Google\Shopping\Merchant\Accounts\V1beta\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_v1beta import GetTermsOfServiceAgreementStateRequest
from google.shopping.merchant_accounts_v1beta 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.
Accettare i TdS per il proprio account
Se gestisci il tuo account Merchant Center, procedi nel seguente modo:
- Chiama il numero
termsOfServiceAgreementStates.retrieveForApplicationper verificare se i Termini di servizio sonorequired. - Se sono richiesti Termini di servizio, annota il nome
termsOfServicedal camporequired(ad esempio,termsOfService/132). Chiama
termsOfService.acceptper accettare i Termini di servizio. Avrai bisogno del nome dei Termini di servizio, del tuoACCOUNT_IDe delregionCoderestituito da retrieveForApplication.Ecco una richiesta di esempio:
POST https://merchantapi.googleapis.com/accounts/v1beta/{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 Termini di servizio (per i fornitori di terze parti)
Se sei un fornitore di terze parti (3P) che gestisce account Merchant Center autonomi per altre attività, non devi accettare i Termini di servizio per loro conto. Invece, devi:
Recupera i Termini di servizio più recenti: chiama il numero
termsOfService.retrieveLatestper ottenere i dettagli della versione più recente dei Termini di servizio che il commerciante potrebbe dover accettare.regionCodeMERCHANT_CENTERRichiesta di esempio:
GET https://merchantapi.googleapis.com/accounts/v1beta/termsOfService:retrieveLatest?regionCode={REGION_CODE}&kind=MERCHANT_CENTEREsempio di risposta:
{ "name": "{termsOfService/VERSION}", "regionCode": "{REGION_CODE}", "kind": "MERCHANT_CENTER", "fileUri": "https://www.google.com/intl/{REGION_CODE}/policies/merchants/terms/" }Visualizza i Termini di servizio: utilizza
fileUridella risposta per visualizzare il testo completo dei Termini di servizio al commerciante all'interno della UI della tua applicazione.Ottenere l'accettazione del commerciante: il commerciante deve accettare esplicitamente i termini all'interno della tua UI.
Registra l'accettazione utilizzando l'API: dopo l'accettazione da parte del commerciante, chiama
termsOfService.acceptutilizzandonamedei TdS ottenuti nel passaggio 1,ACCOUNT_IDdel commerciante eregionCode.Richiesta di esempio:
POST https://merchantapi.googleapis.com/accounts/v1beta/{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.v1beta.AcceptTermsOfServiceRequest;
import com.google.shopping.merchant.accounts.v1beta.TermsOfServiceServiceClient;
import com.google.shopping.merchant.accounts.v1beta.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\V1beta\AcceptTermsOfServiceRequest;
use Google\Shopping\Merchant\Accounts\V1beta\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_v1beta import AcceptTermsOfServiceRequest
from google.shopping.merchant_accounts_v1beta 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 o gli account autonomi.
Gestire i Termini di servizio per gli account cliente
Se gestisci un account avanzato e crei account cliente per attività diverse:
- Accettazione avanzata dell'account: se un account avanzato fornisce il servizio di aggregazione degli account agli account cliente, i Termini di servizio accettati dall'account avanzato si applicheranno 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'aspettativa legale) mostrare i Termini di servizio di Google Merchant Center pertinenti al proprietario dell'attività di ogni account cliente. Devi ottenere il loro consenso esplicito affinché comprendano e accettino 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.retrieveForApplicationsu 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 gli account autonomi
Come descritto in Guida per i commercianti all'accettazione
dei Termini di servizio, quando aiuti
un'attività a creare o gestire un account Merchant Center autonomo, l'attività (il proprietario dell'account) deve accettare personalmente i Termini di servizio. Per facilitare questa operazione, recupera e visualizza i Termini di servizio, quindi chiama il metodo termsOfService.accept per conto dell'utente dopo che ha dato il proprio consenso esplicito tramite la tua interfaccia.