Gerenciar relacionamentos de conta

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 vincula uma conta avançada a outra, concedendo à conta avançada acesso total e irrestrito. Normalmente, ela é usada por marketplaces, varejistas multimarcas ou varejistas internacionais que precisam de controle centralizado sobre contas aninhadas. Se você é uma plataforma de e-commerce ou 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 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, e externalAccountId é o ID da conta do Google Ads. Esse serviço também pode ser proposto para uma conta existente.

  • 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 permite que o provedor realize ações administrativas na conta 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 vinculada ao provedor, que é a abordagem recomendada para plataformas de e-commerce e parceiros de canal. Ele também pode ser proposto para 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 para uma conta existente.

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:

  1. Uma parte 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).

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 usando createAndConfigure, 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).

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.

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:

  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: este é o serviço recomendado para plataformas de e-commerce e parceiros de canal que criam contas em nome de comerciantes. Ele cria uma conta que pertence ao comerciante, vinculada a você para gerenciamento. Isso se alinha à 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 saber como configurar uma conta avançada e vincular a novas contas do Merchant Center, consulte Criar contas.