Migrar o gerenciamento da conta

A API Accounts é dividida em uma coleção de recursos para permitir o gerenciamento mais eficiente das suas contas do Merchant Center com um controle mais preciso em 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 focados. Essa mudança permite chamadas de API mais segmentadas e eficientes. Por exemplo, para atualizar apenas o endereço comercial, agora você faz uma solicitação PATCH ao recurso BusinessInfo em vez de atualizar todo o objeto Account.

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

• Os detalhes da conta principal (ID, nome, configurações de conteúdo adulto) permanecem no recurso Account.
• Agora, as informações comerciais (endereço, número de telefone, atendimento ao cliente) 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.
• Os relacionamentos de contas (links para contas avançadas, provedores terceirizados e outros serviços do Google) são gerenciados pelos recursos AccountRelationship e AccountService.
• Atributos de identidade da empresa (por exemplo, de empreendedores negros, de 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.
• Acesso à conta por alias:acesse contas usando um formato providerId~accountAlias, oferecendo uma maneira consistente para empresas que gerenciam várias contas usarem os próprios identificadores.

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 os 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
Atualizar detalhes da conta	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando 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 saída. O identificador principal é o recurso name.
name	account_name	O nome legível da conta.
language	language_code	O nome do campo agora é language_code.

Gerenciar informações comerciais

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
Acessar informações comerciais	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo business_information)	GET /accounts/v1/accounts/{account}/businessInfo
Atualizar 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 o URL da página inicial	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo website_url)	GET /accounts/v1/accounts/{account}/homepage
Atualizar o URL da página inicial	PUT /content/v2.1/{merchantId}/accounts/{accountId} (atualizando o atributo website_url)	PATCH /accounts/v1/accounts/{account}/homepage
Reivindicar página inicial	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST /accounts/v1/accounts/{account}/homepage:claim
Cancelar a 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 é 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. Uma diferença importante é 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 antes de 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} (atualizando o 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 enumeração 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, os relacionamentos eram gerenciados com accounts.link. A API Merchant apresenta um modelo mais explícito com recursos AccountService e AccountRelationship, exigindo um processo de handshake (propor e aceitar).

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 prestado (por exemplo, ACCOUNT_AGGREGATION).
status	handshake.approval_state (em AccountService)	O status do link (por exemplo, PENDING, ESTABLISHED).

Configurações fiscais 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 Atualização de 2025 da especificação dos dados de produtos do Merchant Center.

Gerenciar a 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 a identidade da empresa	GET /content/v2.1/{merchantId}/accounts/{accountId} (acessando o atributo business_identity)	GET /accounts/v1/accounts/{account}/businessIdentity
Atualizar a 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 é substituído por uma enumeração (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 é substituído por um enum 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 subcontas da MCA especificada. As contas avançadas na API Merchant são muito mais eficientes, permitindo uma variedade maior de tipos de contas e relacionamentos. Para permitir uma migração simples de contas avançadas, a API Merchant oferece um equivalente direto ao 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 subcontas	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 da 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.