chamadas de recursos de produtos

Gostaríamos de apresentar a versão Beta da API Merchant. Esta é a nova versão da API Content e o futuro.

O recurso products permite muita flexibilidade e controle sobre mais de 60 atributos do produto.Há vários campos que são obrigatórios e precisam ser incluídos para que sejam aprovados para exibição no Google Shopping. Há vários campos opcionais que podem se tornar obrigatórios com base em condições variadas, como local, tipo de produto, variantes do produto e pacotes de produtos. Para mais detalhes sobre os mais de 60 parâmetros opcionais que podem ser configurados para produtos, consulte as Especificações de dados do produto.

O recurso products permite insert, get, update e delete um produto por vez e list para todos os produtos no banco de dados do Merchant Center.

O recurso productstatuses pode ser usado para verificar o status de aprovação ou reprovação de um produto específico para um destino. Consulte o guia de status do produto para mais detalhes sobre quais produtos podem ter problemas de qualidade de dados e quais podem ser.

Nos exemplos da API, usamos três produtos: duas camisetas do Google e um boné do Google. Usamos um conjunto mínimo de dados do produto mostrado na tabela abaixo para fazer chamadas de recurso products para inserir, receber, atualizar, listar e excluir produtos individuais e lotes de produtos.

Recomendamos que as informações fiscais e de frete sejam configuradas no nível da conta, e não no nível do produto.

Para subcontas de vários vendedores de Marketplaces, todos os produtos precisam incluir o campo external_seller_id. Consulte IDs do produto para mais detalhes.

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
title	Camiseta preta do Google	Camiseta Google verde	Boné de sarja do Google
description	Camiseta preta do Google	Camiseta Google 100% algodão	Limite clássico do Google
ID do grupo de itens	google_tee	google_tee
link	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
transição	Novo	Novo	Novo
preço	21.99 BRL	21.99 BRL	10.99 BRL
disponibilidade	Em estoque	Em estoque	Em estoque
imageLink	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
gtin	9504000059422	9504000059446	9504000059452
mpn	00638NIC	00638ANG	00638ABC
brand	Google	Google	Google
Categoria Google do produto	Vestuário e acessórios > Roupas	Vestuário e acessórios > Roupas	Vestuário e acessórios > Acessórios para roupas > Chapéus
color	preto	green	preto
tamanho	L	M	M
age_group	adulto	adulto	adulto
gender	masculino	masculino	unissex
included_destination	Shopping Actions e anúncios do Shopping	Shopping Actions e anúncios do Shopping	Shopping Actions

products.insert

Para inserir um único produto, use o URL de solicitação a seguir, especificando o ID do comerciante e um corpo JSON de amostra. Uma inserção cria o novo produto. Se os valores existem para os atributos channel, contentLanguage, offerId e feedLabel de um determinado produto, esse método atualiza essa entrada e substitui todos os dados de chamadas de API anteriores para o produto em questão.

Os produtos excluídos de todos os destinos por mais de sete dias são excluídos automaticamente.

O exemplo mostrado insere uma nova "camiseta preta do Google" nos produtos disponíveis.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Exemplo de chamada de corpo de solicitação para products.insert:

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

Um produto também pode ter atributos personalizados definidos no corpo JSON. Por exemplo, podemos definir um purchase_quantity_limit para um único produto a fim de limitar o número de itens que um cliente pode pedir:

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

O atributo personalizado purchase_quantity_limit estabelece um limite de compra por pedido do cliente para a definição do produto e também é compatível com feeds. No momento, o atributo está na versão Beta até ser totalmente compatível com a API. Qualquer outro atributo personalizado pode ser adicionado por um comerciante, mas não resulta em nenhum processamento específico pelas APIs.

Uma chamada bem-sucedida retorna um código HTTP 200 e um corpo de resposta contendo o recurso do produto inserido com apenas id, offerId, contentLanguage, feedLabel e channel preenchidos:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

Para acessar informações sobre um produto específico no banco de dados do Merchant Center, use products.get. Pode levar alguns minutos para que um produto recém-inserido fique disponível por meio dessa chamada.

Use os seguintes URLs e parâmetros de solicitação HTTP, o ID do comerciante e o ID do produto (formato do ID REST) do produto que você quer receber:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Uma chamada bem-sucedida retorna um HTTP 200 e o "recurso do produto" no corpo da resposta. Veja a seguir uma amostra de dados do produto recuperados de um produto com o ID online:en:US:1111111111:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

Para atualizar um único produto, use o seguinte URL de solicitação com o método PATCH, especificando o ID do comerciante, o ID do produto e um corpo JSON com os dados que você quer atualizar para o produto. Ao contrário de products.insert, que exige que todos os campos aplicáveis sejam fornecidos, products.update exige apenas que você especifique os campos que quer mudar.

Observação: a atualização de um produto é semelhante ao products.insert e leva alguns minutos para que as mudanças sejam processadas. Se products.update for bem-sucedido sem erros, a atualização será bem-sucedida. As seguintes chamadas para products.get podem retornar o valor anterior até que a atualização seja processada.

Aviso: as mudanças feitas com product.update não serão mantidas se o produto com o mesmo ID do produto for reenviado pelo feed principal, feed complementar ou API. Se você quiser que um valor persista após o reenvio, verifique se o valor atualizado está incluído no feed ou usando a chamada de API products.insert.

Para adicionar ou modificar um atributo, especifique o campo com o novo valor no corpo do JSON. O exemplo mostrado atualiza o title e o description de uma "camiseta preta do Google" atual com os dados do produto fornecidos no corpo da solicitação, deixando todos os outros campos intactos.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Exemplo de chamada de corpo de solicitação para products.update:

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

Somente campos de nível superior podem ser atualizados com uma solicitação products.update. Se você quiser atualizar campos aninhados, será necessário fornecer todo o objeto de nível superior.

O exemplo mostrado vai atualizar o objeto salePrice de nível superior, incluindo os campos aninhados de um produto atual com os dados do produto fornecidos no corpo da solicitação, deixando todos os outros campos intocados.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

Para selecionar determinados campos para atualizar sem fazer alterações nos outros incluídos no corpo da solicitação, especifique um updateMask. Esse parâmetro precisa ser uma lista separada por vírgulas dos campos que você quer modificar. Um updateMask é útil quando você quer declarar que apenas os campos nomeados serão atualizados. Não especificar um updateMask equivale a marcar todos os campos na solicitação a serem atualizados, conforme mostrado no exemplo acima.

O exemplo mostrado atualiza apenas o description e o availability de uma "camiseta preta do Google" atual com os respectivos dados do produto fornecidos no corpo da solicitação, deixando todos os outros campos, incluindo o title, intactos.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

Exemplo de chamada de corpo de solicitação para products.update:

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

Se um campo estiver na lista updateMask, mas não no corpo da solicitação, ele será excluído do recurso Product, se houver.

O exemplo mostrado usará updateMask para remover o valor do campo salePrice.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

O corpo da solicitação de amostra não deve incluir o campo salePrice para excluí-lo. Você também pode não fornecer nenhum corpo ou um corpo vazio. Outros campos permanecerão intactos, desde que não apareçam no updateMask.

Aviso: ao usar updateMask, forneça o valor correto para todos os campos listados no updateMask. Se você não incluir o valor no corpo da solicitação, isso será equivalente à exclusão do campo.

Para usar o updateMask em uma solicitação products.custombatch, o updateMask precisa ser especificado no corpo da solicitação.

O exemplo mostrado atualizará o price e o availability de uma "camiseta preta do Google" atual usando products.custombatch com os dados do produto fornecidos na entrada em lote, deixando todos os outros campos, incluindo title e description, intactos.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

Para excluir um único produto, use products.delete com o URL de solicitação HTTP de amostra, o ID do comerciante e o ID do produto (no formato de ID REST, como online:en:US:1111111111) para o produto que você quer excluir:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Uma resposta bem-sucedida retorna uma HTTP Status 204 sem corpo de resposta.

products.list

products.list lista todos os produtos que um comerciante tem no banco de dados do Merchant Center. Use o seguinte URL de solicitação:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Uma chamada bem-sucedida retorna dados HTTP 200 e JSON para os produtos na chave "resources".

Os três exemplos de produtos a seguir são retornados:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}