Migrar da v1beta para a v1

Este guia ajuda você a migrar da API Merchant v1beta para v1, a primeira versão para disponibilidade geral. A versão v1 apresenta várias atualizações e algumas mudanças que podem exigir atualizações no código. Essas mudanças foram criadas para simplificar a API e melhorar o gerenciamento da sua conta do Merchant Center.

principais diferenças

Confira as mudanças mais importantes que você precisa conhecer ao migrar do v1beta para o v1:

• Registro único de pelo menos um desenvolvedor de API para usar a API Merchant: você precisa chamar o método registerGcp (apenas uma vez para cada projeto do Google Cloud usado para autenticação) para fornecer seus detalhes de contato, o que permite usar a API e receber atualizações e anúncios relacionados a ela. Não será possível usar nenhuma API v1 ou v1alpha até que essa etapa seja concluída. Para ver instruções, consulte Fazer o registro de desenvolvedor.
• Product.attributes renomeado: o campo Product.attributes foi renomeado como Product.productAttributes.
• Remoção de informações de tributos no nível do produto:os campos taxes e taxCategory foram removidos do objeto Product.productAttributes. Confira o artigo da Ajuda do Google Merchant Center sobre tributos para mais informações.
• Mudanças no campo GTIN:o campo gtin no objeto Product.productAttributes foi renomeado como gtins para refletir melhor que ele pode conter vários valores. O campo gtin no objeto OrderTrackingSignals.lineItemDetails agora é um array e também foi renomeado como gtins.
• Remoção do campo "Canal":o campo channel foi removido de produtos, entradas de produtos e fontes de dados. Um novo campo booleano, legacyLocal, foi introduzido para designar claramente produtos vendidos exclusivamente em lojas físicas. Observação: o campo legacyLocal é auxiliar para ajudar na migração e será descontinuado quando os métodos de marketing on-line e local puderem ser totalmente segmentados com uma única fonte de produtos. Confira a tabela na seção a seguir para mais informações.
• Novos campos para atributos de inventário regional e local:
  • Todos os campos RegionalInventory, exceto name, account e region, agora estão agrupados em um novo objeto chamado regionalInventoryAttributes. Por exemplo, o atributo RegionalInventory.price agora está em RegionalInventory.regionalInventoryAttributes.price.
  • Todos os campos LocalInventory, exceto name, account e storeCode, agora estão agrupados em um novo objeto chamado localInventoryAttributes. Por exemplo, o atributo LocalInventory.price agora está em LocalInventory.localInventoryAttributes.price.
• Remoção de customAttributes dos inventários regionais e locais:o campo customAttributes foi removido dos recursos RegionalInventory e LocalInventory.
• Criação de conta refinada:o campo redundante users foi removido do CreateAndConfigureAccountRequest. Use o campo singular user para associar um usuário inicial a uma nova conta.
• Alguns tipos de atributos foram mudados de strings para enums:alguns campos nos recursos Product e Inventory com uma lista curta de valores definida foram mudados do tipo string para o tipo enum para melhorar a validação de dados. Por exemplo, o campo Product.ProductAttributes.condition agora é um enum.
• Remoção do método de atualização da política de devolução on-line:o método onlineReturnPolicy.update será removido na versão v1. Crie uma política de devolução on-line usando o método onlineReturnPolicy.create.

Como migrar

A versão v1beta da API Merchant será desativada em 28 de fevereiro de 2026. Para mais informações sobre o cronograma de descontinuação, consulte o guia de controle de versões da API Merchant.

• A primeira etapa da migração é fazer um registro único de desenvolvedor (consulte Registrar como desenvolvedor). É necessário chamar o método registerGcp para cada projeto do Google Cloud usado para autenticação antes que qualquer método v1 funcione.

• Independente de como você chama as APIs (com REST, gRPC ou usando bibliotecas de cliente), é possível migrar em etapas. Isso significa que você pode atualizar e migrar seu código uma API por vez (por exemplo, movendo a API Products para v1 e mantendo a API Accounts em v1beta) sem precisar atualizar toda a integração de uma vez.

Mudanças detalhadas nos campos

Esta tabela oferece uma comparação detalhada dos campos que mudaram entre as versões v1beta e v1.

v1beta	v1	Descrição
Product.gtin	Product.gtins	O campo para GTINs foi renomeado.
Product.taxes	Removido	O campo taxes foi removido
Product.taxCategory	Removido	O campo taxCategory foi removido
Product.channel	Removido	O campo channel foi removido. Use o campo legacyLocal para casos de uso locais.
Product.attributes	Product.productAttributes	O campo attributes foi renomeado como productAttributes.
availability, condition, gender, includedDestinations e excludedDestinations nos campos Product são representados como strings (ou array de strings)	Esses campos agora são enums (ou array de enums)	Os campos com uma lista curta de valores definida foram mudados do tipo string para enum.
price, salePrice, salePriceEffectiveDate e availability em RegionalInventory	Movido para RegionalInventory.regionalInventoryAttributes	Esses campos foram movidos para regionalInventoryAttributes.
O campo RegionalInventory.availability é um string	RegionalInventory.regionalInventoryAttributes.availability agora é um enums	O tipo de disponibilidade mudou de string para enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla e instoreProductLocation em LocalInventory	Movido para LocalInventory.localInventoryAttributes	Esses campos foram movidos para localInventoryAttributes.
O campo LocalInventory.availability é um string	LocalInventory.localInventoryAttributes.availability agora é um enums	O tipo de disponibilidade mudou de string para enum.
LocalInventory.customAttributes	Removido	Os atributos personalizados não são mais aceitos para inventário local.
RegionalInventory.customAttributes	Removido	Os atributos personalizados não são mais compatíveis com o inventário regional.
ProductInput.channel	Removido	O campo channel foi removido. Use o campo legacyLocal para casos de uso locais.
DataSource.channel	Removido	O campo channel foi removido. Use o campo legacyLocal para casos de uso locais.
Indisponível	ProductInput.legacyLocal	Um novo campo booleano para indicar que um produto só pode segmentar métodos de marketing local. O ID do recurso de produto terá o prefixo "local~".
Indisponível	Product.legacyLocal	Um novo campo booleano para indicar que um produto é vendido apenas em lojas físicas e não está disponível para compra on-line.
Indisponível	DataSource.legacyLocal	Um novo campo booleano para indicar que uma fonte de dados contém produtos vendidos apenas em lojas físicas.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	O campo gtin foi renomeado como gtins e agora é uma matriz de strings (em vez de uma string).
CreateAndConfigureAccountRequest.users	Removido	O campo users foi removido. Use o campo user para adicionar o administrador inicial à conta.