Gerenciar relacionamentos de conta

Você pode usar 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 à 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 do Ads use seus dados de produtos para veicular campanhas publicitárias.

Uma relação é composta 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 que está sendo fornecido à conta do Merchant Center

Alias

Os provedores de serviços podem associar um alias às contas que atendem. Isso é o equivalente ao seller_id campo que estava presente no recurso da conta 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 do 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 seguintes serviços. É possível adicionar muitos desses serviços durante a criação da conta.

• Agregação de contas: esse serviço vincula uma conta avançada a outra conta, concedendo acesso total e irrestrito à conta avançada. Ele é usado normalmente por marketplaces, varejistas de várias marcas ou varejistas internacionais que precisam de controle centralizado sobre contas aninhadas. Se você é uma plataforma de e-commerce ou um parceiro de canal, recomendamos usar accountManagement. Ao criar uma conta usando a agregação de contas, o externalAccountId precisa ser omitido.

• Gerenciamento de campanhas: esse serviço modela o vínculo entre uma conta do Merchant Center e uma conta do Google Ads, à conta do Ads acesso aos dados da conta e de produtos necessários para veicular campanhas publicitárias. O provedor de serviços nesse caso é GOOGLE_ADS, e o externalAccountId é o ID da conta do Google Ads. Esse serviço também pode ser proposto a uma conta atual.

Observação: para varejistas/ marketplaces que usam a rede de commerce media em contas do Google Ads:

• Esse serviço permite a criação de filtros de produtos específicos do parceiro ao veicular campanhas da rede de commerce media.
• No momento, é necessário usar a versão Alfa da sub-API Accounts.
• O uso desse recurso exige uma lista de permissões específica do GMC.

Entre em contato com a equipe de gerenciamento de contas 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 e as fichas locais usando um Perfil da Empresa no Google.

• Gerenciamento de contas: esse serviço permite que o provedor realize ações administrativas na conta do Merchant Center, como configurar as definiçõ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 vinculada ao provedor, que é a abordagem recomendada para plataformas de e-commerce e parceiros de canal. Ele também pode ser proposto a uma conta atual.

• 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 accountManagement ou accountAggregation. Esse serviço também pode ser proposto a uma conta atual.

Aperto de mão

Para estabelecer um serviço, a conta que o fornece e a conta que o recebe precisam autorizar a conexão. Esse processo de autorização é chamado de "aperto de mão".

O aperto de mão é um processo de duas etapas:

1. Uma das partes propõe um link de serviço.
2. 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).

Observe que 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 precisa ser um ADMIN na conta do provedor de serviços, e o usuário que aceitar ou rejeitar a proposta precisa ser um ADMIN na conta receptora.

Os exemplos a seguir demonstram 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);
  }
}
ProposeServiceSample.java

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();
ProposeAccountServiceSample.php

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_)
propose_account_service_sample.py

Comportamento de aperto de mão específico do serviço

A seguir, descrevemos os requisitos específicos de aperto de mão para cada serviço:

• Agregação de contas: esse serviço só pode ser estabelecido como parte da criação da conta. Espera-se que o provedor de serviços seja uma conta avançada, e o serviço é aprovado automaticamente, já que os usuários da conta avançada têm acesso ADMIN total à 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 aperto de mão, 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 na API Merchant).

• Gerenciamento de fichas da empresa 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, no 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 normal de aperto de mão é aplicado ao usar propose. Se o serviço for adicionado durante a criação da conta usando createAndConfigure, ele será aprovado automaticamente.

• Gerenciamento de produtos: para esse serviço, o processo normal de aperto de mão é aplicado (proposto por uma parte, seguido da aceitação da outra).

Direitos de acesso

Cada tipo de serviço oferece um determinado nível de acesso para usuários do provedor de serviços na conta atendida:

• Agregação de contas: esse serviço oferece direitos ADMIN completos.

• Gerenciamento de campanhas: esse serviço oferece um direito de acesso restrito, permitindo que a conta do Ads associada acesse produtos e informações básicas da conta.

• Comparação de preços: esse serviço oferece, por padrão, direitos ADMIN completos. No entanto, a empresa pode restringir o acesso concedido no Merchant Center.

• Gerenciamento de fichas da empresa em pesquisa local: esse serviço não oferece direito de acesso direto. Em vez disso, ele permite que as informações do produto sincronizem os produtos com a conta do Merchant Center.

Importante: os direitos de acesso descritos para os seguintes tipos de serviço 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á tiver sido aprovado para o método accounts.link para gerenciamento de produtos na API Content for Shopping, poderá usar esse serviço na API Merchant sem outras aprovações.

• Gerenciamento de contas: esse serviço oferece, por padrão, direitos ADMIN completos.

• Gerenciamento de produtos: esse serviço oferece direitos ADMIN completos. No futuro, isso será limitado apenas aos direitos de acesso relacionados ao produto.

Como as relações se aplicam a plataformas de terceiros

Se você é uma plataforma de terceiros que gerencia contas em nome de outras empresas, a seguir mostramos como os diferentes conceitos são mapeados para a estrutura da sua conta:

1. Provedor de serviços: sua conta avançada.
2. Conta que recebe o serviço: uma conta do Merchant Center que representa a empresa que você gerencia.
3. Serviço:
   • accountManagement: esse é o serviço recomendado para plataformas de e-commerce e parceiros de canal que criam novas contas em nome de comerciantes. Ele cria uma conta de propriedade do comerciante, vinculada a você para gerenciamento. Isso está alinhado à estrutura preferencial do Merchant Center para esse caso de uso.
   • accountAggregation: esse serviço vincula sua conta avançada a outra conta. Embora seja compatível, não é recomendado para plataformas de e-commerce e parceiros de canal.

Para detalhes sobre como configurar uma conta avançadae vincular a novas contas do Merchant Center, consulte Criar contas.