A versão v1beta da API Merchant será descontinuada e desativada em 28 de fevereiro de 2026. Para saber como fazer a transição para a versão estável mais recente, consulte Migrar da v1beta para a v1.

Produtos de migração

A API Merchant apresenta uma maneira mais robusta e intuitiva de gerenciar os dados de produtos. A principal mudança é a separação dos dados de produtos em dois recursos distintos: ProductInput para enviar seus dados e Product para ver a versão final processada, incluindo status e problemas do produto. Essa nova estrutura oferece uma experiência mais previsível e transparente.

Este guia mostra as principais diferenças para ajudar você a migrar sua integração da API Content for Shopping. Para um guia detalhado sobre como usar os novos recursos, consulte Gerenciar seus produtos.

principais diferenças

Confira as mudanças mais significativas na forma de gerenciar produtos na API Merchant em comparação com a API Content for Shopping:

Recursos dedicados para dados de entrada e processados: a API Merchant divide o gerenciamento de produtos em dois recursos. Você pode usar o recurso ProductInput para inserir, atualizar e excluir os dados de produtos. Você pode usar o recurso somente leitura Product para ver o produto final depois que o Google processa suas entradas, aplica regras e combina dados de fontes complementares.
Codificação para nomes de produtos: você pode usar a codificação base64url sem padding (seção 5 da RFC 4648) para os campos ProductInput.name e Product.name. Se os nomes dos produtos contiverem caracteres usados pela API Merchant ou caracteres reservados para URL, a codificação será obrigatória. Por exemplo, você precisa codificar os nomes dos produtos se eles contiverem algum dos seguintes caracteres:
```
% . + / : ~ , ( * ! ) & ? = @ # $
```
Status do produto integrado: o serviço productstatuses é removido. Os problemas de validação de produtos e os status de destino agora estão incluídos diretamente no recurso Product no campo productStatus, simplificando a recuperação de dados.
Atualizações de produtos previsíveis: o novo método productInputs.patch modifica uma entrada de produto específica diretamente. Essa é uma melhoria significativa em relação à API Content for Shopping, em que as atualizações podiam ser substituídas inesperadamente por outros uploads de feed. Na API Merchant, uma atualização permanece até que a entrada de produto específica seja atualizada ou excluída novamente. As atualizações de produtos são aplicadas no recurso ProductInput em vez do recurso Product processado.
Escolha sua fonte de dados para um gerenciamento de dados mais limpo: todas as operações de gravação productInputs agora exigem um parâmetro de consulta dataSource, deixando explícito qual fonte de dados você está modificando. Isso é especialmente útil se você tiver várias fontes de dados.
Novos identificadores de recursos: agora os produtos são identificados por um recurso RESTful name em vez do campo id. O formato é accounts/{account}/products/{product}.
Sem lotes personalizados: o método custombatch não está mais disponível. É possível usar solicitações assíncronas ou lotes HTTP para enviar várias solicitações em uma única chamada HTTP.
Fontes de dados para qualquer rótulo e idioma do feed: a API Merchant permite criar uma fonte de dados sem especificar o rótulo e o idioma do feed. Assim, é possível inserir produtos com qualquer rótulo e idioma.

Solicitações

Esta seção compara os formatos de solicitação da API Content for Shopping e da API Merchant.

Descrição da solicitação	API Content for Shopping	API Merchant
Receber um produto	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}`
Listar produtos	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products`
Inserir um produto	`POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products`	`POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert`
Atualizar um produto	`PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}`
Excluir um produto	`DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}`
Receber status do produto	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}`
Listar status dos produtos	`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses`	`GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products`
Agrupar várias solicitações	`POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch`	Use solicitações assíncronas ou agrupamento em lote HTTP

Identificadores

O formato dos identificadores de produtos mudou na API Merchant para um nome de recurso REST padrão.

Descrição do identificador	API Content for Shopping	API Merchant
ID do produto	Uma string composta de segmentos separados por dois pontos (`:`). Formato: `channel:contentLanguage:targetCountry:offerId` ou `channel:contentLanguage:feedLabel:offerId`. Exemplo: `online:en:US:sku123`	Uma string `name` de recurso REST. Formato: `accounts/{account}/products/{product}` em que `{product}` é `contentLanguage~feedLabel~offerId`. Exemplo: `accounts/12345/products/en~US~sku123`. Codificação: codificação base64url sem padding recomendada e obrigatória no caso de IDs de produtos que contêm caracteres usados pela API Merchant ou caracteres reservados para URL.

Métodos

Esta tabela mostra os métodos da API Content for Shopping e os equivalentes na API Merchant.

Método da API Content for Shopping	Método da API Merchant	Disponibilidade e observações
`products.get`	`products.get`	Recupera o produto final processado.
`products.list`	`products.list`	Lista os produtos finais processados.
`products.insert`	`productInputs.insert`	Insere uma entrada de produto. Requer um `dataSource`.
`products.update`	`productInputs.update`	O comportamento é significativamente diferente. Ele atualiza uma entrada de produto específica e é persistente.
`products.delete`	`productInputs.delete`	Exclui uma entrada de produto específica. Requer um `dataSource`.
`products.custombatch`	Indisponível	Use solicitações assíncronas ou agrupamento em lote HTTP.
`productstatuses.get`	`products.get`	O serviço `productstatuses` é removido. As informações de status agora fazem parte do recurso `Product`.
`productstatuses.list`	`products.list`	O serviço `productstatuses` é removido. As informações de status agora fazem parte do recurso `Product`.
`productstatuses.custombatch`	Indisponível	Use solicitações assíncronas ou lotes HTTP.

Mudanças detalhadas nos campos

Esta tabela destaca campos importantes que foram mudados, adicionados ou removidos na API Merchant.

API Content for Shopping	API Merchant	Descrição
`id`	`name`	O identificador principal de um produto agora é o recurso REST `name`. A codificação base64url sem padding é recomendada e obrigatória em nomes de produtos que contêm caracteres usados pela API Merchant ou caracteres reservados para URL.
Atributos de especificação dos dados do produto de nível superior (por exemplo, `title`, `price`, `link`)	Objeto `productAttributes`	Atributos de produto como `title`, `price` e `link` não são mais campos de nível superior. Agora eles estão agrupados no objeto `productAttributes` nos recursos `Product` e `ProductInput`. Isso oferece uma estrutura de recursos mais limpa e organizada.
`targetCountry`	`feedLabel`	O nome do recurso agora usa `feedLabel` em vez de `targetCountry` para se alinhar à funcionalidade do Merchant Center.
`feedId`	`dataSource` (parâmetro de consulta)	Agora, um nome `dataSource` é um parâmetro de consulta obrigatório para todos os métodos de gravação `productInputs` (`insert`, `update`, `delete`).
`channel`	Indisponível. Use `legacy_local` para produtos disponíveis apenas na loja física.	O campo `channel` não está mais presente na API Merchant. Os produtos com o canal `LOCAL` na API Content for Shopping precisam definir o campo `legacy_local` como "true".
Indisponível	`versionNumber`	Um novo campo opcional em `ProductInput` que pode ser usado para evitar inserções fora de ordem em fontes de dados principais.
Campos do tipo `string` com um conjunto de valores definido	Campos do tipo `enum` com um conjunto de valores definido	Os campos nos atributos de produto com um conjunto definido de valores (por exemplo, `excluded_destinations`, `availability`) agora são do tipo `enum`.

Migrate merchant support

Avançar

Migrate data sources management