Migrar da v1beta para a v1

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

principais diferenças

Confira as mudanças mais importantes a serem consideradas ao migrar de v1beta para 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 na nuvem do Google usado para autenticação) para fornecer seus detalhes de contato, o que permite usar a API e receber atualizações e anúncios relacionados à API Merchant. Não será possível usar nenhuma v1 ou v1alpha API até que esta etapa esteja concluída. Para mais informações sobre o processo de registro, consulte Registro.

• Codificação do nome do produto: os ProductInput.name e Product.name campos oferecem suporte à codificação base64url não preenchida (seção 5 da RFC 4648). Siga estas diretrizes:

  • Antes da codificação, a string precisa respeitar o formato contentLanguage~feedLabel~offerId.

  • A codificação é obrigatória se o nome do produto contiver caracteres usados pela API Merchant ou caracteres reservados para URL, como:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Se o nome do produto estiver no formato contentLanguage~feedLabel~offerId e não contiver caracteres usados pela API Merchant ou caracteres reservados para URL, você poderá usar o formato simples, sem codificação.

  • Para garantir uma análise consistente e correta, recomendamos o uso da codificação base64url não preenchida para todos os nomes de produtos.

• Remoção de informações fiscais no nível do produto:taxes e taxCategory.

• Product.attributes renomeado: o campo Product.attributes foi renomeado para Product.productAttributes.

• Remoção de informações fiscais no nível do produto: Os campos taxes e taxCategory foram removidos do Product.productAttributes objeto. Confira mais informações no artigo de ajuda do Google Merchant Center sobre impostos.

• Mudanças no campo GTIN: O campo gtin no objeto Product.productAttributes foi renomeado para gtins para refletir melhor que ele pode conter vários valores. O campo gtin no OrderTrackingSignals.lineItemDetails objeto agora é um array e também foi renomeado para gtins.

• Remoção do campo de 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 os produtos vendidos exclusivamente em lojas físicas. Observação: o campo legacyLocal é um campo 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 mais informações na tabela da seção a seguir.

• Novos campos para atributos de inventário regional e local:

  • Todos os RegionalInventory campos, 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 LocalInventory campos, 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 de inventários regionais e locais: O customAttributes campo foi removido dos recursos RegionalInventory e LocalInventory.

• Criação de conta refinada:o campo users redundante foi removido do CreateAndConfigureAccountRequest. Use o campo user singular para associar um usuário inicial a uma nova conta.

• Alguns tipos de atributos foram alterados de strings para enums: Alguns campos nos recursos Product e Inventory com uma lista curta de valores definidos foram alterados do tipo string para o tipo enum para melhor 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 onlineReturnPolicy.update método foi removido na v1. Crie uma política de devolução on-line usando onlineReturnPolicy.create método em vez disso.

Como migrar

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

• A primeira etapa da migração é fazer um registro de desenvolvedor único . Consulte Registrar-se como desenvolvedor. Você precisa chamar o método registerGcp para cada projeto na nuvem do Google Cloud usado para autenticação antes que qualquer método v1 funcione.

• Independentemente 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, mover a Products API para v1 enquanto mantém a Accounts API em v1beta) sem precisar atualizar toda a integração de uma só vez.

Mudanças detalhadas no campo

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