chamadas de recursos de produtos

Gostaríamos de apresentar a versão Beta da API Merchant. É a nova versão API Content for Shopping e o futuro.

Para mais informações sobre como a API Merchant pode melhorar sua integração e como você pode ajudar a moldar a futuro, consulte Anunciar a API Merchant API Beta.

O products oferece grande flexibilidade e controle sobre de 60 atributos do produto.Há vários campos obrigatórios, e precisam ser incluídos para serem aprovados para exibição no Google Shopping. Há diversos campos opcionais que podem se tornar obrigatórios com base em diferentes condições como local, tipo de produto, variantes do produto e pacotes. Para mais detalhes sobre os mais de 60 parâmetros opcionais que podem ser configurados para produtos, consulte a página Dados do produto Especificações.

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

A productstatuses pode ser usado para verificar o status de aprovação ou reprovação de um para um destino. Consulte o status do produto para mais detalhes sobre quais produtos podem ter problemas de qualidade de dados e quais são esses problemas.

Em nossos exemplos de API, usamos três produtos: duas camisetas do Google e uma Limite 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 você configure as informações fiscais e de frete da conta nível, em vez de no nível do produto.

Para subcontas de vários vendedores de Mercados, todos os produtos precisam inclua 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
título	Camiseta preta do Google	Camiseta Google verde	Boné de sarja do Google
descrição	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
marca	Google	Google	Google
Categoria Google do produto	Vestuário e Acessórios > Roupa	Vestuário e Acessórios > Roupa	Vestuário e Acessórios > Acessórios para roupas > Chapéus
cor	preto	verde	preto
tamanho	L	M	M
age_group	adulto	adulto	adulto
gênero	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 seguinte URL de solicitação, especificando o seu ID do comerciante e um corpo JSON de exemplo. Uma inserção cria o novo produto. Valores "if" existem para os atributos channel, contentLanguage, offerId e feedLabel para um determinado produto, este método atualiza essa entrada e substitui todos os dados de chamadas de API anteriores para o produto especificado.

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

O exemplo mostrado insere uma nova "camiseta preta do Google". aos 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 encomendar:

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

O atributo personalizado purchase_quantity_limit define um limite de compra. por pedido do cliente até a definição do produto e também é suportado por feeds. A está na versão Beta até ser totalmente compatível com a API. Qualquer um atributo personalizado adicional pode ser adicionado por um comerciante, mas não resulta qualquer 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 um produto recém-inserido ser disponíveis nesta chamada.

Use os seguintes parâmetros e URL de solicitação HTTP, seu ID do comerciante e os 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. Estes são um exemplo de dados do produto recuperados de um produto com 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 seu ID do comerciante, o ID do produto e um corpo JSON contendo os dados que você gostaria de atualizar para o produto. Ao contrário de products.insert, isso exige todos os campos aplicáveis a serem fornecidos, o products.update exige apenas que você especifique os campos que você quer mudar.

Observação: a atualização de um produto se comporta de maneira semelhante ao products.insert e leva até uma alguns minutos para que as alterações sejam processadas. Se products.update for bem-sucedido sem erros, a atualização será bem-sucedida. Talvez as seguintes chamadas para products.get retornem o valor anterior até que a atualização tenha sido processada.

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

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

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 o campos de um produto existente, com os dados do produto fornecidos nos corpo da solicitação, deixando todos os outros campos inalterados.

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, é possível especificar um updateMask. Essa string de consulta deve 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 na solicitação a serem atualizados, conforme mostrado no exemplo acima.

O exemplo mostrado vai atualizar apenas os parâmetros description e availability de uma "camiseta preta do Google" existente com os respectivos dados do produto fornecidos nas o 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 do 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 deve incluir o campo salePrice para excluí-la. Você também pode não fornecer nenhum corpo ou um corpo vazio. Outros campos vão permanecem intactas desde que não apareçam no updateMask.

Aviso: ao usar updateMask, tenha o cuidado de fornecer o valor correto para todos campos listados em updateMask. Se você não incluir o valor no corpo da solicitação, isso equivale à exclusão do campo.

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

O exemplo mostrado vai atualizar o price e o availability de um "Camiseta preta do Google" usando products.custombatch com os dados do produto fornecidos na entrada em lote, deixando todos os outros campos, incluindo title e description intocados.

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 exemplo de solicitação HTTP URL, seu ID do comerciante e o ID do produto (no formato de ID REST, como online:en:US:1111111111) do 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 Merchant Center. no seu banco de dados. 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 "recursos" de dados.

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"
   ]
  }
 ]
}