Use a API Accounts para gerenciar as relações entre sua conta do Merchant Center e outros provedores de serviços. Uma relação é uma conexão formal que permite que um provedor ofereça serviços específicos para sua empresa. Um serviço define as permissões e os recursos concedidos ao provedor, como gerenciamento de produtos ou de campanhas. Por exemplo, vincular sua conta do Merchant Center a uma conta do Google Ads permite que a conta de anúncios use os dados do produto para veicular campanhas publicitárias.
Um relacionamento é composto pelos seguintes atributos:
- A conta do Merchant Center que recebe o serviço
- O provedor de serviços
- O serviço ou conjunto de serviços fornecido à conta do Merchant Center.
Alias
Os provedores de serviços podem associar um alias às contas que atendem. Isso é o
equivalente ao campo seller_id que estava presente no recurso
account
na API Content for Shopping. O alias pode ser atribuído usando o
campo opcional account_id_alias no recurso AccountRelationship e
serve como um identificador personalizado. O alias precisa ter de 1 a 50 caracteres
escolhidos entre letras ASCII, dígitos decimais, hifens, sublinhados, pontos ou
tils ([A-Za-z0-9_~.-]{1,50}).
A estrutura de URL para acessar uma conta usando o alias é
GET /accounts/v1/accounts/{provider}~{account_id_alias}.
Serviços
Na API Accounts, as contas podem receber os serviços a seguir. É possível adicionar muitos desses serviços durante a criação da conta.
Agregação de contas: esse serviço (
accountAggregation) vincula uma conta avançada de múltiplos clientes a uma subconta, concedendo à conta avançada acesso total e irrestrito e tornando a subconta visível na interface do Merchant Center. A interface do Merchant Center converte automaticamente as contas em contas avançadas comaccountAggregationpara criadores de lojas (plataformas de e-commerce), parceiros de canal, marketplaces, varejistas multimarcas e varejistas internacionais ao criar novas subcontas. Se você é uma agência, useaccountManagement. Ao criar uma conta usando a agregação de contas, oexternalAccountIdprecisa ser omitido.Gerenciamento de campanhas: esse serviço modela a vinculação entre uma conta do Merchant Center e uma conta do Google Ads, permitindo que a conta de anúncios acesse os dados da conta e de produtos necessários para veicular campanhas publicitárias. O provedor de serviços nesse caso é
GOOGLE_ADS, eexternalAccountIdé o ID da conta do Google Ads. Esse serviço também pode ser proposto para uma conta existente.
- Esse serviço permite a criação de filtros de produtos específicos do parceiro ao veicular campanhas de rede de commerce media.
- No momento, é necessário usar a versão Alfa da sub-API Accounts.
- O uso desse recurso requer uma lista de permissões específica do GMC.
Entre em contato com a equipe de gerenciamento de conta do Google Ads para mais detalhes.
Comparação de preços: representa a relação com um serviço de comparação de preços (CSS) que opera a conta do Merchant Center.
Gerenciamento de fichas locais: representa a relação com um gerente de loja para gerenciar o inventário local e as fichas usando um Perfil da Empresa no Google.
Gerenciamento de contas: esse serviço (
accountManagement) permite que o provedor realize ações administrativas em uma conta externa independente do Merchant Center, como definir as configurações da conta, gerenciar usuários ou atualizar informações comerciais. A empresa também pode restringir o acesso concedido. Quando usado durante a criação da conta, esse serviço cria uma conta independente vinculada ao provedor. Também pode ser proposto para uma conta atual. As agências que usam esse tipo de serviço podem ver as contas que gerenciam no Merchant Center para Agências. Os criadores de lojas e parceiros de canal podem usar a API Merchant para extrair informações sobre os comerciantes que gerenciam peloaccountManagement.Gerenciamento de produtos: esse serviço permite que os provedores gerenciem produtos e recursos relacionados, como fontes de dados e regras. Quando adicionado durante a criação da conta, ele geralmente é combinado com
accountManagementouaccountAggregation. Esse serviço também pode ser proposto para uma conta existente.Gerenciamento de finalização de compra da UCP (
v1alpha, acesso limitado): o serviçoucpCheckoutManagementpermite que um provedor de serviços aprovado gerencie as integrações, as configurações e a participação no programa de finalização de compra da UCP em nome de um comerciante. Esse serviço só pode ser proposto ou aprovado por uma conta do Merchant Center.Observação: a finalização de compra do UCP é um recurso Alfa com acesso limitado. Saiba mais sobre os provedores de serviços e a finalização de compra da UCP no Merchant Center para provedores de serviços.
Aperto de mão
Para estabelecer um serviço, tanto a conta que o fornece quanto a que o recebe precisam autorizar a conexão. Esse processo de autorização é chamado de handshake.
O handshake é um processo de duas etapas:
- Uma parte propõe um link de serviço.
- A outra parte aprova ou rejeita a proposta.
Depois que uma proposta é aceita, o serviço é aprovado e considerado totalmente estabelecido. Qualquer direito de acesso conferido ao provedor de serviços agora é concedido a usuários qualificados (consulte os direitos de acesso abaixo).
O usuário que cria, rejeita ou aprova uma proposta precisa ter
ADMIN direitos de
acesso
na conta que inicia o processo. Portanto, se o provedor de serviços
propuser um serviço, o usuário que fizer a proposta precisará ser um ADMIN na
conta do provedor de serviços, e o usuário que aceitar ou rejeitar a proposta
precisará ser um ADMIN na conta de recebimento.
Os exemplos a seguir mostram como propor um serviço de conta:
Java
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.AccountName;
import com.google.shopping.merchant.accounts.v1.AccountService;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceClient;
import com.google.shopping.merchant.accounts.v1.AccountServicesServiceSettings;
import com.google.shopping.merchant.accounts.v1.ProductsManagement;
import com.google.shopping.merchant.accounts.v1.ProposeAccountServiceRequest;
import shopping.merchant.samples.utils.Authenticator;
/** This class demonstrates how to propose a service to an existing Merchant Center account. */
public class ProposeServiceSample {
public static void proposeService(long accountId, long providerId, String externalAccountId)
throws Exception {
// Obtains OAuth token based on the user's configuration.
// The user that authenticates should have access to the account.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
AccountServicesServiceSettings accountServicesServiceSettings =
AccountServicesServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Calls the API and catches and prints any network failures/errors.
try (AccountServicesServiceClient accountServicesServiceClient =
AccountServicesServiceClient.create(accountServicesServiceSettings)) {
// The service to be proposed.
// This sample shows how to propose product management.
// For more information about the different services, see:
// https://developers.google.com/merchant/api/guides/accounts/services
AccountService accountService =
AccountService.newBuilder()
.setProductsManagement(ProductsManagement.newBuilder().build())
.setExternalAccountId(externalAccountId)
.build();
String accountName =
AccountName.newBuilder().setAccount(String.valueOf(accountId)).build().toString();
ProposeAccountServiceRequest request =
ProposeAccountServiceRequest.newBuilder()
.setParent(accountName)
.setProvider("accounts/" + providerId)
.setAccountService(accountService)
.build();
System.out.println("Sending Propose Service request:");
AccountService response = accountServicesServiceClient.proposeAccountService(request);
System.out.println("Proposed Service below");
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
// The ID of the account to propose the service to.
long accountId = 123L;
// This is the provider ID of the e-commerce platform.
long providerId = 456L;
// An external ID that uniquely identifies the account service.
String externalAccountId = "ext-acc-id-123";
proposeService(accountId, providerId, externalAccountId);
}
}
PHP
require_once __DIR__ . '/../../../../vendor/autoload.php';
require_once __DIR__ . '/../../../Authentication/Authentication.php';
require_once __DIR__ . '/../../../Authentication/Config.php';
use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\AccountAggregation;
use Google\Shopping\Merchant\Accounts\V1\AccountService;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountServicesServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ProposeAccountServiceRequest;
/**
* This class demonstrates how to propose an account service.
*/
class ProposeAccountServiceSample
{
/**
* A helper function to create the account name string.
*
* @param string $accountId The ID of the account.
*
* @return string The account name has the format: `accounts/{account_id}`
*/
private static function toAccountName(string $accountId): string
{
return sprintf('accounts/%s', $accountId);
}
/**
* Proposes a new account service.
*
* @param array $config The configuration data used for authentication and
* getting the account ID.
* @param string $providerId The ID of the provider account.
*/
public static function proposeAccountService(
array $config,
string $providerId
): void {
// Gets the OAuth credentials to make the request.
$credentials = Authentication::useServiceAccountOrTokenFile();
// Creates options containing credentials for the client to use.
$options = ['credentials' => $credentials];
// Creates a client.
$accountServicesServiceClient = new AccountServicesServiceClient($options);
// Calls the API and catches and prints any network failures/errors.
try {
$accountAggregation = new AccountAggregation();
$accountService = (new AccountService())
->setAccountAggregation($accountAggregation);
$request = (new ProposeAccountServiceRequest())
->setParent(self::toAccountName($config['accountId']))
->setProvider(self::toAccountName($providerId))
->setAccountService($accountService);
print "Sending Propose AccountService request\n";
$response = $accountServicesServiceClient->proposeAccountService($request);
print "Proposed AccountService below\n";
print $response->serializeToJsonString(true) . PHP_EOL;
} catch (ApiException $e) {
printf("An error has occurred: %s%s", $e->getMessage(), PHP_EOL);
}
}
/**
* Helper to execute the sample.
*/
public function callSample(): void
{
$config = Config::generateConfig();
// Update this with the Merchant Center provider ID you want to get the
// relationship for.
$providerId = 111;
self::proposeAccountService($config, $providerId);
}
}
// Run the script
$sample = new ProposeAccountServiceSample();
$sample->callSample();
Python
"""This class demonstrates how to propose an account service."""
from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1 import AccountAggregation
from google.shopping.merchant_accounts_v1 import AccountService
from google.shopping.merchant_accounts_v1 import AccountServicesServiceClient
from google.shopping.merchant_accounts_v1 import ProposeAccountServiceRequest
_ACCOUNT = configuration.Configuration().read_merchant_info()
_PARENT = f"accounts/{_ACCOUNT}"
def propose_account_service(provider_id: int) -> None:
"""Proposes an account service.
Args:
provider_id: The Merchant Center ID of the provider.
"""
# Gets OAuth Credentials.
credentials = generate_user_credentials.main()
# Creates a client.
client = AccountServicesServiceClient(credentials=credentials)
# Creates the provider resource name from the provider ID.
provider = f"accounts/{provider_id}"
# Creates an AccountService object.
# For this request, only `account_aggregation` is needed.
account_service = AccountService()
account_service.account_aggregation = AccountAggregation()
# Creates the request.
request = ProposeAccountServiceRequest(
parent=_PARENT,
provider=provider,
account_service=account_service,
)
# Makes the request and catches and prints any error messages.
try:
print("Sending Propose AccountService request")
response = client.propose_account_service(request=request)
print("Proposed AccountService below")
print(response)
except RuntimeError as e:
print(e)
if __name__ == "__main__":
# Update this with the Merchant Center provider ID you want to get the
# relationship for.
provider_id_ = 111
propose_account_service(provider_id_)
Comportamento de handshake específico do serviço
Veja a seguir uma descrição dos requisitos específicos de handshake para cada serviço individual:
Agregação de contas: esse serviço só pode ser estabelecido como parte da criação da conta. O provedor de serviços precisa ser uma conta avançada, e o serviço é aprovado automaticamente, já que os usuários da conta avançada têm acesso total de
ADMINà conta que está sendo criada.Comparação de preços: esse serviço é aprovado automaticamente quando adicionado durante a criação da conta usando
createAndConfigure.Gerenciamento de campanhas: embora siga o processo normal de handshake, as propostas são feitas em um sistema (por exemplo, o Google Ads) e as aprovações são feitas no outro sistema (por exemplo, no Merchant Center ou pela API Merchant).
Gerenciamento de fichas de empresas em pesquisa local: para esse serviço, o handshake é proposto em um método dedicado, e as aprovações são feitas no outro sistema (por exemplo, o Perfil da Empresa no Google). As etapas detalhadas estão no Guia para vincular um Perfil da Empresa no Google.
Gerenciamento de contas: para esse serviço, o processo de handshake regular se aplica ao usar
propose. Se o serviço for adicionado durante a criação da conta usandocreateAndConfigure, ele será aprovado automaticamente.Gerenciamento de produtos: para esse serviço, aplica-se o processo de handshake regular (proposto por uma parte, seguido pela aceitação da outra).
Gerenciamento de finalização de compra da UCP (
v1alpha, acesso limitado): para esse serviço, o comerciante pode concluir o handshake pela caixa de diálogo de vinculação de contas hospedada pelo Google no portal do provedor de serviços ou usando o processo de handshake padrão (proposeseguido porapprove). Para detalhes sobre a integração, consulte a documentação dos provedores de serviços do Merchant Center.
Direitos de acesso
Cada tipo de serviço oferece um determinado nível de acesso para os usuários do provedor de serviços na conta que está sendo atendida:
Agregação de contas: esse serviço oferece todos os direitos de
ADMIN.Gerenciamento de campanhas: esse serviço oferece um direito de acesso restrito, permitindo que a conta do Google Ads associada acesse produtos e informações básicas da conta.
Comparação de preços: esse serviço oferece, por padrão, todos os direitos do
ADMIN. No entanto, a empresa pode restringir o acesso concedido no Merchant Center.Gerenciamento de fichas de empresas locais: esse serviço não oferece direito de acesso direto. Em vez disso, ela permite que a listagem sincronize os produtos com a conta do Merchant Center.
Importante: os direitos de acesso descritos para os tipos de serviço a seguir se aplicam
apenas a provedores de serviços aprovados. Entre em contato com nossa equipe de suporte se você for um provedor de serviços e quiser usar esse recurso. Se você já
tinha aprovação para o método accounts.link de gerenciamento de produtos na
API Content for Shopping, pode usar esse serviço na API Merchant sem
outras aprovações.
Gerenciamento de contas: esse serviço oferece, por padrão, todos os direitos do
ADMIN.Gerenciamento de produtos: esse serviço oferece todos os direitos de
ADMIN. No futuro, isso será limitado apenas aos direitos de acesso relacionados ao produto.Gerenciamento de finalização de compra com UCP (
v1alpha, acesso limitado): esse serviço oferece direitos completos deADMIN. No futuro, isso será limitado apenas aos direitos de acesso relacionados à finalização de compra da UCP.
Como as relações se aplicam a plataformas de terceiros
Se você é uma plataforma de terceiros que gerencia contas em nome de outras empresas, veja como os diferentes conceitos se aplicam à estrutura da sua conta:
- Provedor de serviços: sua conta avançada.
- Conta que recebe o serviço: uma conta do Merchant Center que representa a empresa que você gerencia.
- Serviço:
accountAggregation: usado por criadores de lojas (plataformas de e-commerce), parceiros de canal, marketplaces e varejistas multimarcas que criam novas subcontas em nome dos comerciantes. A interface do Merchant Center configura automaticamente criadores de lojas e parceiros de canal como contas avançadas comaccountAggregation, permitindo que eles visualizem e gerenciem subcontas na interface do Merchant Center.accountManagement: usado por agências que criam ou vinculam contas de cliente independentes de propriedade do comerciante, que podem ser visualizadas no Merchant Center para Agências. Outros tipos de provedores de serviços usam o métodoaccounts.listna API Merchant para conferir as informações da conta vinculada.
Para saber como configurar uma conta avançada e vincular a novas contas do Merchant Center, consulte Criar contas.