Migrar o gerenciamento da conta

A API Accounts é dividida em uma coleção de recursos para permitir o gerenciamento das suas contas do Merchant Center de forma mais eficiente, com um controle mais preciso de diferentes aspectos da sua conta.

Este guia explica as principais mudanças e ajuda você a migrar sua integração de gerenciamento de contas da API Content for Shopping para a API Merchant.

De um recurso para muitos

Na API Content for Shopping, o recurso Account era um objeto monolítico que continha tudo, desde o nome da conta e o URL do site até listas de usuários e informações comerciais.

A API Merchant divide isso em vários recursos menores e mais específicos. Essa mudança permite chamadas de API mais direcionadas e eficientes. Por exemplo, para atualizar apenas seu endereço comercial, faça uma solicitação PATCH ao recurso BusinessInfo em vez de atualizar todo o objeto Account.

Confira um resumo de como os conceitos do recurso Account da API Content for Shopping são mapeados para os novos recursos na API Merchant:

• Os detalhes principais da conta (ID, nome, configurações de conteúdo adulto) permanecem no recurso Account.
• Informações comerciais (endereço, número de telefone, atendimento ao cliente) agora são gerenciadas pelo recurso BusinessInfo.
• O URL do site e a reivindicação são processados pelo recurso Homepage.
• O gerenciamento de usuários é feito pelo recurso User.
• As relações de conta (links para contas avançadas, provedores terceirizados e outros serviços do Google) são gerenciadas pelos recursos AccountRelationship e AccountService.
• Atributos de identidade da empresa (por exemplo, de empreendedores negros, de empreendedoras mulheres) são gerenciados pelo recurso BusinessIdentity.
• Os contratos de Termos de Serviço (ToS), um novo recurso, são gerenciados pelos recursos TermsOfService e TermsOfServiceAgreementState.

Os novos recursos,

A API Merchant também apresenta novos recursos para gerenciamento de contas que não estavam disponíveis na API Content for Shopping:

• Termos de Serviço: recupere e aceite os Termos de Serviço de forma programática usando os recursos TermsOfService e TermsOfServiceAgreementState.
• Criação de conta: o método accounts.createAndConfigure agora permite criar contas com relacionamentos (como accountManagement), definir um alias e suprimir a verificação de e-mail usando o campo user.verificationMailSettings.verificationMailMode em favor da verificação baseada em API usando o novo método accounts.verifySelf.
• Acesso à conta por alias: acesse contas usando um formato providerId~accountAlias, oferecendo uma maneira consistente para as empresas que gerenciam várias contas usarem os próprios identificadores de conta.

Solicitações

Esta tabela oferece uma comparação consolidada dos URLs de solicitação para tarefas comuns de gerenciamento de contas entre a API Content for Shopping e a API Merchant.

Descrição da solicitação	API Content for Shopping	API Merchant
Acessar conta	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Acessar conta por alias	Não disponível diretamente	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
Listar subcontas	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
Criar subconta	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
Atualizar dados da conta	PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	PATCH no recurso apropriado. Por exemplo, para atualizar o nome da conta: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Excluir subconta	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Reivindicar site	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
Vincular contas	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

Gerenciar informações principais da conta

O recurso Account na API Merchant contém os detalhes essenciais de uma conta do Merchant Center, como nome, ID e configurações básicas.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Acessar detalhes da conta	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando atributos principais, como name, adult_content)	GET /accounts/v1/accounts/{account}
Criar uma subconta	POST /content/v2.1/{merchantId}/accounts	POST /accounts/v1/accounts:createAndConfigure
Atualize os detalhes da conta	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualização dos atributos principais)	PATCH /accounts/v1/accounts/{account}
Excluir uma subconta	DELETE /content/v2.1/{merchantId}/accounts/{accountId}	DELETE /accounts/v1/accounts/{account}

Comparação detalhada de campos

API Content for Shopping (Account)	API Merchant (Account)	Observações
id	account_id	O ID numérico agora é um campo somente de saída. O identificador principal é o recurso name.
name	account_name	O nome legível por humanos da conta.
language	language_code	O nome do campo agora é language_code.

Gerenciar informações da empresa

Use o recurso BusinessInfo para gerenciar informações públicas sobre sua empresa, como endereço e contatos de atendimento ao cliente. Isso substitui o objeto businessInformation na API Content for Shopping.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Receber informações comerciais	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo business_information)	GET /accounts/v1/accounts/{account}/businessInfo
Atualize as informações comerciais	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo business_information)	PATCH /accounts/v1/accounts/{account}/businessInfo

Comparação detalhada de campos

API Content for Shopping (business_information)	API Merchant (BusinessInfo)	Observações
phone_number	phone	O campo agora é phone e usa google.type.PhoneNumber.
customer_service.url	customer_service.uri	O nome do campo agora é uri.

Gerenciar sua página inicial

Para gerenciar o URL do site da sua loja e realizar a verificação e a reivindicação, use o recurso Homepage. Isso substitui o campo websiteUrl e o método accounts.claimwebsite da API Content for Shopping.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Receber URL da página inicial	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo website_url)	GET /accounts/v1/accounts/{account}/homepage
Atualizar URL da página inicial	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo website_url)	PATCH /accounts/v1/accounts/{account}/homepage
Página inicial da reivindicação	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST /accounts/v1/accounts/{account}/homepage:claim
Cancelar reivindicação da página inicial	Indisponível	POST /accounts/v1/accounts/{account}/homepage:unclaim

Comparação detalhada de campos

API Content for Shopping (Account)	API Merchant (Homepage)	Observações
website_url	uri	O URL da página inicial da loja.
Não disponível diretamente	claimed	Um campo booleano que será true se a página inicial for reivindicada.

Gerenciar usuários

O recurso User permite gerenciar quem pode acessar uma conta do Merchant Center. Isso substitui a matriz users no recurso Account. A principal diferença é o processo de criação de usuários. Na API Merchant, adicionar um usuário envia um convite. O usuário precisa aceitar o convite para acessar a conta.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Listar usuários	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo users)	GET /accounts/v1/accounts/{account}/users
Criar um usuário	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo users)	POST /accounts/v1/accounts/{account}/users
Atualizar um usuário	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo users)	PATCH /accounts/v1/accounts/{account}/users/{email}
Excluir um usuário	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualização do atributo users)	DELETE /accounts/v1/accounts/{account}/users/{email}

Comparação detalhada de campos

API Content for Shopping (objeto de matriz users)	API Merchant (recurso User)	Observações
email_address	name (no formato accounts/{account}/users/{email})	O e-mail do usuário agora faz parte do nome do recurso.
admin, order_manager, reporting_manager etc.	access_rights	Os direitos de acesso agora estão consolidados em um campo de tipo enumerado repetido.
Indisponível	state	Um novo campo somente de saída que indica se o usuário é PENDING ou VERIFIED.

Gerenciar relações e serviços de contas

Na API Content for Shopping, as relações eram gerenciadas com accounts.link. A API Merchant apresenta um modelo mais explícito com os recursos AccountService e AccountRelationship, que exigem um processo de handshake (proposta e aceitação).

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Vincular contas	POST /content/v2.1/{merchantId}/accounts/{accountId}/link	POST /accounts/v1/accounts/{account}/services:propose
Listar contas vinculadas	GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks	GET /accounts/v1/accounts/{account}/relationships e GET /accounts/v1/accounts/{account}/services

Comparação detalhada de campos

API Content for Shopping (AccountLink)	API Merchant (AccountService, AccountRelationship)	Observações
linked_account_id	provider (em AccountService)	O ID da conta que fornece o serviço.
service	service_type (em AccountService)	O tipo de serviço que está sendo prestado (por exemplo, ACCOUNT_AGGREGATION).
status	handshake.approval_state (em AccountService)	O status do link (por exemplo, PENDING, ESTABLISHED).

Configurações de tributos da conta

O serviço accounttax da API Content for Shopping não está disponível na API Merchant. Não é mais necessário informar os tributos sobre vendas dos EUA. Para mais informações, consulte a atualização de 2025 da especificação dos dados do produto do Merchant Center.

Gerenciar identidade comercial

Use o recurso BusinessIdentity para declarar atributos sobre sua empresa. Isso substitui o objeto businessIdentity na API Content for Shopping.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Receber identidade da empresa	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo business_identity)	GET /accounts/v1/accounts/{account}/businessIdentity
Atualizar identidade da empresa	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo business_identity)	PATCH /accounts/v1/accounts/{account}/businessIdentity

Comparação detalhada de campos

API Content for Shopping (business_identity)	API Merchant (BusinessIdentity)	Observações
black_owned.self_identified (booleano)	black_owned.identity_declaration (enum)	O booleano foi substituído por um tipo enumerado (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS) para uma declaração mais explícita. Isso se aplica a todos os atributos de identidade.
include_for_promotions (booleano)	promotions_consent (enum)	Um booleano global foi substituído por um tipo enumerado mais descritivo (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED).

Exibir contas

Na API Content for Shopping, o único tipo de conta avançada era uma "conta de múltiplos clientes (MCA)", que expunha um método accounts.list para listar as contas da MCA em questão. As contas avançadas na API Merchant são muito mais eficientes, permitindo uma variedade maior de tipos de conta e relacionamentos. Para permitir uma migração simples para contas avançadas, a API Merchant oferece um equivalente direto ao método accounts.list da API Content for Shopping como um método accounts.listSubaccounts. Estamos lançando um novo método accounts.list mais eficiente que permite a filtragem avançada de contas.

Comparação de solicitações

Descrição da solicitação	API Content for Shopping	API Merchant
Listar contas de uma conta avançada	GET /content/v2.1/{merchantId}/accounts	GET /accounts/v1/accounts/{providerId}:listSubaccounts
Listar todas as contas acessíveis	Indisponível	GET /accounts/v1/accounts

Comparação detalhada de campos (parâmetros de solicitação)

API Content for Shopping (accounts.list)	API Merchant (accounts.listSubaccounts)	Observações
merchant_id (parâmetro de caminho)	provider (parâmetro de caminho)	O ID da conta avançada no formato accounts/{account}.
max_results	page_size	O número máximo de contas a serem retornadas.