llamadas a recursos de productos

Queremos presentar la versión beta de la API de Merchant. Es la nueva versión de Content API y el futuro.

El recurso products ofrece una gran flexibilidad y control sobre más de 60 atributos de producto.Existen varios campos que son obligatorios y que se deben incluir para aprobarse para mostrarse en Google Shopping. Hay una serie de campos opcionales que pueden volverse obligatorios según distintas condiciones, como la ubicación, el tipo de producto, las variantes de productos y los paquetes de productos. Si quieres obtener más detalles sobre los más de 60 parámetros opcionales que se pueden configurar para los productos, consulta las especificaciones de datos de productos.

El recurso products te permite insert, get, update y delete un producto a la vez, y list todos los productos de la base de datos de Merchant Center.

El recurso productstatuses se puede usar para verificar el estado de aprobación o rechazo de un producto específico para un destino. Consulta la guía del estado del producto para obtener más detalles sobre qué productos pueden tener problemas de calidad de los datos y cuáles pueden ser.

En nuestros ejemplos de la API, usamos tres productos: dos camisetas de Google y un gorro de Google. Usamos un conjunto mínimo de datos de productos que se muestran en la tabla a continuación para realizar llamadas a recursos products para insertar, obtener, actualizar, enumerar y borrar productos individuales y lotes de productos.

Recomendamos que la información de impuestos y envío se configure a nivel de la cuenta en lugar de a nivel del producto.

Para las cuentas secundarias de varios vendedores de Marketplaces, todos los productos deben incluir el campo external_seller_id. Consulta los IDs de productos para obtener más información.

id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
title	Camiseta negra de Google	Camiseta verde de Google	Gorra de sarga de Google
description	Camiseta negra de Google	Camiseta de Google 100% algodón	Gorra clásica de Google
ID de grupo de artículos	google_tee	google_tee
vínculo	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
de transición	Nuevo	Nuevo	Nuevo
precio	219.90 MXN	219.90 MXN	109.90 MXN
de disponibilidad	En stock	En stock	En stock
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
Categoría producto google	Apparel & Accessories > Clothing [Ropa y accesorios > Prendas de vestir]	Apparel & Accessories > Clothing [Ropa y accesorios > Prendas de vestir]	Indumentaria y accesorios > Complementos > Sombreros
color	negro	green	negro
tamaño	L	M	M
age_group	para adultos	para adultos	para adultos
género	male	male	unisex
included_destination	Acciones de Shopping, anuncios de Shopping	Acciones de Shopping, anuncios de Shopping	Shopping Actions

products.insert

Para insertar un solo producto, usa la siguiente URL de solicitud y especifica tu ID de comerciante y un cuerpo JSON de muestra. Un inserción crea el nuevo producto. Si existen valores para los atributos channel, contentLanguage, offerId y feedLabel de un producto determinado, este método actualiza esa entrada y reemplaza todos los datos de llamadas a la API anteriores para el producto determinado.

Los productos que se excluyen de todos los destinos durante más de 7 días se borran automáticamente.

En el ejemplo que se muestra, se inserta una nueva “camiseta negra de Google” en los productos disponibles.

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

Ejemplo de llamada al cuerpo de la solicitud 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"
 ]
}

Un producto también puede tener atributos personalizados configurados en el cuerpo JSON. Por ejemplo, podemos establecer un purchase_quantity_limit para un solo producto a fin de limitar la cantidad de artículos que un cliente puede pedir:

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

Ten en cuenta que el atributo personalizado purchase_quantity_limit establece un límite de compra por pedido de cliente para la definición del producto y también es compatible con los feeds. Actualmente, el atributo está en versión beta hasta que la API lo admita por completo. Los comercios pueden agregar cualquier atributo personalizado adicional, pero esto no genera un procesamiento específico por parte de las APIs.

Una llamada exitosa muestra un código HTTP 200 y un cuerpo de respuesta que contiene el recurso de producto insertado con solo id, offerId, contentLanguage, feedLabel y channel propagados:

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

products.get

Para obtener información sobre un producto específico de la base de datos de Merchant Center, usa products.get. Es posible que un producto recién insertado tarde unos minutos en estar disponible mediante esta llamada.

Usa los siguientes parámetros y URL de solicitud HTTP, tu ID de comerciante y el ID de producto (formato de ID de REST) del producto que deseas obtener:

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

Una llamada exitosa muestra un HTTP 200 y el "recurso de producto" en el cuerpo de la respuesta. A continuación, se muestran datos de muestra de datos del producto recuperados de un producto con el 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 actualizar un solo producto, usa la siguiente URL de solicitud con el método PATCH y especifica tu ID del comerciante, el ID del producto y un cuerpo JSON que contenga los datos que quieras actualizar para el producto. A diferencia de products.insert, que requiere que se proporcionen todos los campos aplicables, products.update solo requiere que especifiques los campos que deseas cambiar.

Nota: La actualización de un producto se comporta de manera similar a products.insert y tarda unos minutos en procesar los cambios. Si products.update tiene éxito sin errores, la actualización se realizará de forma correcta. Las siguientes llamadas a products.get pueden mostrar el valor anterior hasta que se procese la actualización.

Advertencia: Los cambios realizados con product.update no se mantienen si el producto con el mismo ID de producto se vuelve a enviar mediante el feed principal, el feed complementario o la API. Si deseas que un valor se conserve después de que vuelvas a enviarlo, asegúrate de que el valor actualizado se incluya en el feed o a través de la llamada a la API de products.insert.

Para agregar o modificar un atributo, especifica el campo con el valor nuevo en el cuerpo JSON. En el ejemplo que se muestra, se actualizarán el title y el description de una “camiseta negra de Google” existente con los datos de productos proporcionados en el cuerpo de la solicitud, y todos los demás campos quedarán intactos.

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

Ejemplo de llamada al cuerpo de la solicitud para products.update:

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

Solo los campos de nivel superior se pueden actualizar a través de una solicitud products.update. Si quieres actualizar campos anidados, debes proporcionar el objeto de nivel superior completo.

En el ejemplo que se muestra, se actualizará el objeto salePrice de nivel superior, incluidos los campos anidados de un producto existente, con los datos de producto proporcionados en el cuerpo de la solicitud, y todos los demás campos quedarán intactos.

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

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

Si quieres seleccionar ciertos campos para que se actualicen sin hacer cambios en los demás incluidos en el cuerpo de la solicitud, puedes especificar un updateMask. Este parámetro de cadena de consulta debe ser una lista separada por comas de los campos que deseas modificar. Un updateMask es útil cuando deseas confirmar que solo se actualizarán los campos con nombre. No especificar un updateMask equivale a marcar todos los campos en la solicitud que se actualizará, como se muestra en el ejemplo anterior.

En el ejemplo que se muestra, solo se actualizarán la description y la availability de una “camiseta negra de Google” existente con los datos de producto respectivos proporcionados en el cuerpo de la solicitud, y todos los demás campos, incluido el title, quedarán intactos.

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

Ejemplo de llamada al cuerpo de la solicitud para products.update:

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

Si se proporciona un campo en la lista updateMask, pero no en el cuerpo de la solicitud, se borrará del recurso Product (si existe).

En el ejemplo que se muestra, se usará updateMask para quitar el valor del campo salePrice.

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

El cuerpo de la solicitud de muestra no debe incluir el campo salePrice para borrarlo. También puedes proporcionar ningún cuerpo o un cuerpo vacío. Otros campos permanecerán intactos, siempre que no aparezcan en updateMask.

Advertencia: Cuando uses updateMask, ten cuidado de proporcionar el valor correcto para todos los campos enumerados en el updateMask. Si no incluyes el valor en el cuerpo de la solicitud, será el equivalente a borrar el campo.

Para usar updateMask en una solicitud products.custombatch, se debe especificar updateMask en el cuerpo de la solicitud.

En el ejemplo que se muestra, se actualizarán price y availability de una “camiseta negra de Google” existente usando products.custombatch con los datos de productos proporcionados en la entrada del lote, lo que dejará intactos todos los demás campos, incluidos title y description.

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 borrar un solo producto, usa products.delete con la URL de solicitud HTTP de muestra, tu ID de comerciante y el ID del producto (en formato de ID de REST, como online:en:US:1111111111) del producto que deseas borrar:

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

Una respuesta correcta muestra una HTTP Status 204 sin cuerpo de respuesta.

products.list

products.list enumera todos los productos que tiene un comercio en la base de datos de Merchant Center. Usa la siguiente URL de solicitud:

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

Una llamada exitosa muestra un HTTP 200 y datos JSON para los productos en la clave "recursos".

Se muestran los siguientes tres ejemplos de productos:

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