chamadas de recursos de produtos

O recurso products oferece muita flexibilidade e controle sobre mais de 60 atributos de produtos.Há vários campos obrigatórios que precisam ser incluídos para serem aprovados para exibição no Google Shopping. Há uma série de campos opcionais que podem se tornar obrigatórios com base em condições variadas, como local, tipo de produto, variantes de produtos 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 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 esses problemas.

Nos nossos exemplos de API, usamos três produtos: duas camisetas e um boné do Google. Usamos um conjunto mínimo de dados de produtos mostrados 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 de frete e tributos sejam configuradas no nível da conta, e não no nível do produto.

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

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
título	A camiseta preta do Google	Camiseta Google verde	Boné de sarja Google
Descrição	A camiseta preta do Google	Camiseta Google 100% algodão	Boné 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
condiçã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 [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
cor	preto	green	preto
tamanho	L	M	M
age_group	adulto	adulto	adulto
gênero	masculino	masculino	unissex
included_destination	Ações do Shopping, anúncios do Shopping	Ações do Shopping, anúncios do Shopping	Shopping Actions

products.insert

Para inserir um único produto, use o URL de solicitação a seguir, especificando seu ID do comerciante e um exemplo de corpo JSON. Uma inserção cria o novo produto. Se houver valores para os atributos channel, contentLanguage, offerId e feedLabel em um determinado produto, esse método vai atualizar essa entrada e substituir todos os dados de chamadas de API anteriores do 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 do corpo da 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 do JSON. Por exemplo, podemos definir uma purchase_quantity_limit para um único produto de modo a limitar o número de itens que um cliente pode pedir:

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

O atributo personalizado purchase_quantity_limit define 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 das APIs.

Uma chamada bem-sucedida retorna um código HTTP 200 e um corpo de resposta contendo o recurso de 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 conferir 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 seja disponibilizado por essa chamada.

Use os seguintes parâmetros e URL de solicitação HTTP, seu ID do comerciante e o ID do produto (formato de 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 exemplos 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 URL de solicitação a seguir com o método PATCH, especificando o ID do comerciante, o ID do produto e um corpo JSON contendo os dados que você quer atualizar. Ao contrário de products.insert, que exige que todos os campos aplicáveis sejam fornecidos, products.update só exige que você especifique os campos que quer mudar.

Observação: a atualização de um produto se comporta de maneira semelhante a products.insert e leva alguns minutos para que as mudanças sejam processadas. Se products.update for bem-sucedida 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 sã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, certifique-se de que o valor atualizado esteja incluído no feed ou por meio da chamada de API products.insert.

Para adicionar ou modificar um atributo, especifique o campo com o novo valor no corpo 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 do corpo da 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."
}

Apenas campos de nível superior podem ser atualizados por uma solicitação products.update. Se você quiser atualizar campos aninhados, forneça todo o objeto de nível superior.

O exemplo mostrado atualiza o objeto salePrice de nível superior, incluindo os campos aninhados de um produto existente, 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}

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

Para selecionar determinados campos a serem atualizados sem alterar os outros incluídos no corpo da solicitação, especifique um updateMask. Esse parâmetro de string de consulta precisa ser uma lista de campos separados por vírgulas 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, como mostrado no exemplo acima.

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

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

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

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

Se um campo for fornecido na lista updateMask, mas não no corpo da solicitação, esse campo 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 pode incluir o campo salePrice para excluí-lo. Também é possível informar nenhum corpo ou um corpo vazio. Os outros campos vão permanecer inalterados, 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 a excluir o campo.

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

O exemplo mostrado atualiza o price e o availability de uma "Camiseta preta do Google" atual usando products.custombatch com os dados do produto fornecidos na entrada do 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, seu 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 um 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 produtos na chave "resources".

Os três produtos de exemplo 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"
   ]
  }
 ]
}