Esta página explica como fazer upload e gerenciar seus produtos de forma programática. Com a API Merchant Products, é possível inserir ou atualizar um produto em uma fonte de dados, recuperar um produto da sua conta e excluir um produto de uma fonte de dados.
A API Merchant Products contém dois recursos.
productInputsrepresenta as partes de entrada dos seus produtos.productsrepresenta os produtos processados que foram criados com as partes de entrada.
O productInputs pode ser principal e complementar, dependendo se ele é
enviado para uma
fonte de dados principal
ou uma
fonte de dados complementar.
Cada product será criado a partir de um único productInput principal e qualquer
número de productInputs complementares.
É possível usar a API Merchant Products para criar catálogos de lojas on-line ou locais. Esses produtos podem aparecer em vários destinos de compras.
É possível usar o recurso productInputs depois de criar sua conta do Merchant Center, configurar sua primeira fonte de dados e fazer upload de um conjunto inicial de produtos pela API.
Embora os comerciantes possam fazer upload de produtos usando um arquivo chamado PrimaryProductDataSource, há várias vantagens em criar e excluir produtos usando a API Merchant. Essas vantagens incluem tempo de resposta mais rápido e a capacidade de atualizar produtos em tempo real, sem a necessidade de gerenciar arquivos grandes. Pode levar até várias horas para que as mudanças de produtos feitas por chamadas de API sejam mostradas no banco de dados do Shopping.
Pré-requisitos
Se você não tiver uma fonte de dados, crie uma usando a API Merchant Data Sources ou o Merchant Center.
Se você já tiver uma fonte de dados criada usando a interface do Merchant Center ou a API, poderá usar a API Merchant Products para adicionar seus produtos. Se você estiver usando a API Content for Shopping para adicionar produtos, consulte o guia de migração para entender como começar a usar a API Merchant Products.
Você é responsável por obedecer às políticas de anúncios do Shopping e listagens sem custo financeiro. Os anúncios do Shopping se reservam o direito de aplicar essas políticas e responder adequadamente se encontrarmos conteúdo ou comportamento que viole essas políticas.
Recursos
O recurso products permite recuperar informações do produto do banco de dados do Shopping.
O recurso
productInput
representa os dados de entrada enviados para um produto. Ele também fornece
métodos que permitem atualizar ou excluir informações de produtos uma por vez ou
várias de uma só vez no modo de lote. Um recurso
productInput precisa ter os seguintes campos:
channel: o canal do produto.offerId: o identificador exclusivo do produto.contentLanguage: o código de idioma ISO 639-1 de duas letras do produto.feedLabel: o rótulo que permite categorizar e identificar seus produtos. O máximo de caracteres permitidos é 20, e os caracteres aceitos sãoA-Z,0-9, hífen e sublinhado. O rótulo do feed não pode conter espaços. Para mais informações, consulte Como usar os identificadores de feed.
Fazer upload de uma entrada de produto na sua conta
Para fazer upload de uma entrada de produto na sua conta, use o
método accounts.productInputs.insert. É necessário transmitir o
identificador exclusivo da fonte de dados principal ou
complementar.
O exemplo de solicitação a seguir mostra como usar o
método accounts.productInputs.insert para fazer upload de uma entrada de produto na
sua conta de comerciante. A solicitação define o preço e a região do frete, além de atributos
personalizados, como data de fabricação e tamanho.
POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /productInputs:insert?dataSource={DATASOURCE}
{
"name": "{PRODUCT_TITLE} ",
"versionNumber": {VERSION_NUMBER} ,
"contentLanguage": "{CONTENT_LANGUAGE} ",
"feedLabel": "{FEED_LABEL} ",
"offerId": "{OFFER_ID} ",
"channel": "ONLINE",
"attributes": {
"availability": "in stock",
"imageLink": "{IMAGE_LINK} ",
"link": "{PRODUCT_LINK} ",
"brand": "{BRAND_NAME} ",
"price": {
"currencyCode": "{CURRENCY_CODE} ",
"amountMicros": {PRICE}
},
"color": "red",
"productWeight": {
"value": 320,
"unit": "g"
},
"adult": false,
"shipping": [
{
"country": "GB",
"price": {
"amountMicros": {SHIPPING_COST} ,
"currencyCode": "{CURRENCY_CODE_SHIPPING} "
},
"postalCode": "{SHIPPING_POSTALCODE} ",
"service": "",
"region": "{SHIPPING_REGION} ",
"maxHandlingTime": "{MAX_HANDLING_TIME} ",
"minHandlingTime": "{MIN_HANDLING_TIME} ",
"maxTransitTime": "{MAX_TRANSIT_TIME} ",
"minTransitTime": "{MIN_TRANSIT_TIME} "
}
],
"gender": "Female"
},
"customAttributes": [
{
"name": "size",
"value": "Large"
},
{
"name": "Date of Manufacturing",
"value": "2024-05-05"
}
]
}
Substitua:
- {ACCOUNT_ID}: o identificador exclusivo da sua conta do Merchant Center.
- {DATASOURCE}: o identificador exclusivo da fonte de dados. Ele precisa estar no formato
accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}. - {PRODUCT_TITLE}: o nome do produto.
- {VERSION_NUMBER}: o número da versão do produto. Opcional.
- {CONTENT_LANGUAGE}: o código de idioma ISO 639-1 de duas letras do produto. Obrigatório.
- {FEED_LABEL}: o rótulo que permite categorizar
e identificar seus produtos. O número máximo de caracteres permitidos é 20, e os
caracteres aceitos são
A-Z,0-9, hífen e sublinhado. O rótulo do feed não pode incluir espaços. - {OFFER_ID}: o identificador exclusivo do produto. Obrigatório.
- {IMAGE_LINK}: o link para a imagem do produto no seu site. Opcional.
- {PRODUCT_LINK}: o link para o produto no seu site. Opcional.
- {CURRENCY_CODE}: é a moeda do preço usando sigla de três letras de acordo com a ISO 4217. Opcional.
- {PRICE}: o preço do produto representado como um número em micros. Opcional.
- {SHIPPING_COST}: o preço de frete fixo representado como um número. Opcional.
- {SHIPPING_POSTALCODE}: o intervalo de código postal em que a taxa de frete é válida. Opcional.
- {MAX_HANDLING_TIME}: o tempo máximo em separação em dias úteis entre o recebimento e o envio do pedido. Opcional.
- {MIN_HANDLING_TIME}: o tempo mínimo em separação em dias úteis entre o recebimento e o envio do pedido. O valor 0 significa que o pedido é entregue no mesmo dia em que é recebido. Opcional.
- {MAX_TRANSIT_TIME}: o tempo máximo em trânsito em dias úteis entre o envio e a entrega do pedido. Opcional.
- {MIN_TRANSIT_TIME}: o tempo mínimo em trânsito em dias úteis entre o envio e a entrega do pedido. O valor 0 significa que o pedido é entregue no mesmo dia em que é enviado. Opcional.
Quando a solicitação for executada, você vai receber a seguinte resposta:
{
"name": "{PRODUCT_NAME} ",
"product": "{PRODUCT_ID} ",
"channel": "ONLINE",
"offerId": "{OFFER_ID} ",
"contentLanguage": "{CONTENT_LANGUAGE} ",
"feedLabel": "{FEED_LABEL} ",
"versionNumber": "{VERSION_NUMBER} ",
"attributes": {
"link": "{PRODUCT_LINK} ",
"imageLink": "{IMAGE_LINK} ",
"adult": false,
"availability": "in stock",
"brand": "{BRAND_NAME} ",
"color": "red",
"gender": "Female",
"price": {
"amountMicros": "{PRICE} ",
"currencyCode": "{CURRENCY_CODE} "
},
"shipping": [
{
"price": {
"amountMicros": "{SHIPPING_COST} ",
"currencyCode": "{CURRENCY_CODE} "
},
"country": "{SHIPPING_COUNTRY} ",
"region": "{SHIPPING_REGION} ",
"postalCode": "{SHIPPING_POSTALCODE} ",
"minHandlingTime": "{MIN_HANDLING_TIME} ",
"maxHandlingTime": "{MAX_HANDLING_TIME} ",
"minTransitTime": "{MIN_TRANSIT_TIME} ",
"maxTransitTime": "{MAX_TRANSIT_TIME} "
}
],
"productWeight": {
"value": 320,
"unit": "g"
}
},
"customAttributes": [
{
"name": "Size",
"value": "Large"
},
{
"name": "Date of Manufacturing",
"value": "2024-05-05"
}
]
}
Para adicionar um produto à sua conta do Merchant Center, use o método
google.shopping.merchant.accounts.v1beta.InsertProductInputSample, conforme mostrado no exemplo a seguir.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.Attributes;
import com.google.shopping.merchant.products.v1beta.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInput;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1beta.Shipping;
import com.google.shopping.type.Channel.ChannelEnum;
import com.google.shopping.type.Price;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to insert a product input */
public class InsertProductInputSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void insertProductInput(Config config, String dataSource) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to insert the product.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
// Price to be used for shipping ($33.45).
Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();
Shipping shipping =
Shipping.newBuilder()
.setPrice(price)
.setCountry("GB")
.setService("1st class post")
.build();
Shipping shipping2 =
Shipping.newBuilder()
.setPrice(price)
.setCountry("FR")
.setService("1st class post")
.build();
Attributes attributes =
Attributes.newBuilder()
.setTitle("A Tale of Two Cities")
.setDescription("A classic novel about the French Revolution")
.setLink("https://exampleWebsite.com/tale-of-two-cities.html")
.setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
.setAvailability("in stock")
.setCondition("new")
.setGoogleProductCategory("Media > Books")
.setGtin(0, "9780007350896")
.addShipping(shipping)
.addShipping(shipping2)
.build();
// The datasource can be either a primary or supplemental datasource.
InsertProductInputRequest request =
InsertProductInputRequest.newBuilder()
.setParent(parent)
// You can only insert products into datasource types of Input "API" and "FILE", and
// of Type "Primary" or "Supplemental."
// This field takes the `name` field of the datasource.
.setDataSource(dataSource)
// If this product is already owned by another datasource, when re-inserting, the
// new datasource will take ownership of the product.
.setProductInput(
ProductInput.newBuilder()
.setChannel(ChannelEnum.ONLINE)
.setContentLanguage("en")
.setFeedLabel("label")
.setOfferId("sku123")
.setAttributes(attributes)
.build())
.build();
System.out.println("Sending insert ProductInput request");
ProductInput response = productInputsServiceClient.insertProductInput(request);
System.out.println("Inserted ProductInput Name below");
// The last part of the product name will be the product ID assigned to a product by Google.
// Product ID has the format `channel~contentLanguage~feedLabel~offerId`
System.out.println(response.getName());
System.out.println("Inserted Product Name below");
System.out.println(response.getProduct());
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// Identifies the data source that will own the product input.
String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{INSERT_DATASOURCE_ID}";
insertProductInput(config, dataSource);
}
}
Extrair um produto processado da sua conta
Para recuperar um produto processado da sua conta, use o método
accounts.products.get. Pode levar alguns minutos para
que o produto processado apareça após a inserção.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /products/{PRODUCT_NAME}
Substitua {PRODUCT_NAME} pelo nome do recurso de entrada
de produto que você quer excluir. Por exemplo, online~en~US~sku123.
É possível acessar o nome do recurso do produto processado no campo product
na
resposta de accounts.productInputs.insert.
Para recuperar um único produto de uma determinada conta do Merchant Center, use o método
google.shopping.merchant.accounts.v1beta.GetProductRequest, conforme mostrado no exemplo a seguir.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.GetProductRequest;
import com.google.shopping.merchant.products.v1beta.Product;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to get a single product for a given Merchant Center account */
public class GetProductSample {
public static void getProduct(Config config, String product) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The name has the format: accounts/{account}/products/{productId}
GetProductRequest request = GetProductRequest.newBuilder().setName(product).build();
System.out.println("Sending get product request:");
Product response = productsServiceClient.getProduct(request);
System.out.println("Retrieved Product below");
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// The name of the `product`, returned after a `Product.insert` request. We recommend
// having stored this value in your database to use for all future requests.
String product = "accounts/{datasource}/products/{productId}";
getProduct(config, product);
}
}
Excluir uma entrada de produto da sua conta
Para excluir uma entrada de produto da sua conta, use o método
accounts.productInputs.delete. É necessário transmitir o
identificador exclusivo da fonte de dados principal ou complementar à qual o produto
pertence para excluir um produto usando a API Merchant Products.
A solicitação abaixo mostra como usar o método accounts.productInputs.delete
para excluir uma entrada de produto:
DELETE https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /productInputs/{PRODUCT_NAME} ?dataSource=accounts/{ACCOUNT_ID} /dataSources/{DATASOURCE_ID}
Substitua {PRODUCT_NAME} pelo nome do recurso de entrada
de produto que você quer excluir. Por exemplo, online~en~US~sku123.
Para excluir um produto de uma determinada conta do Merchant Center, use o método
google.shopping.merchant.accounts.v1beta.DeleteProductInputRequest, conforme mostrado no exemplo a seguir.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.DeleteProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInputName;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to delete a product for a given Merchant Center account */
public class DeleteProductInputSample {
public static void deleteProductInput(Config config, String productId, String dataSource)
throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates product name to identify product.
String name =
ProductInputName.newBuilder()
.setAccount(config.getAccountId().toString())
.setProductinput(productId)
.build()
.toString();
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
DeleteProductInputRequest request =
DeleteProductInputRequest.newBuilder().setName(name).setDataSource(dataSource).build();
System.out.println("Sending deleteProductInput request");
productInputsServiceClient.deleteProductInput(request); // no response returned on success
System.out.println(
"Delete successful, note that it may take a few minutes for the delete to update in"
+ " the system. If you make a products.get or products.list request before a few"
+ " minutes have passed, the old product data may be returned.");
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// An ID assigned to a product by Google. In the format
// channel~contentLanguage~feedLabel~offerId
String productId = "online~en~label~sku123";
// The name of the dataSource from which to delete the product. If it is a primary feed, this
// will delete the product completely. If it's a supplemental feed, it will only delete the
// product information from that feed, but the product will still be available from the primary
// feed.
String dataSource = "accounts/{account}/dataSources/{dataSource}";
deleteProductInput(config, productId, dataSource);
}
}
Listar produtos da sua conta
Para listar os produtos processados na sua conta, use o método accounts.products.list, conforme mostrado na solicitação a seguir.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /products
Para listar um produto em uma determinada conta do Merchant Center, use o método
google.shopping.merchant.accounts.v1beta.ListProductsRequest, conforme mostrado no exemplo a seguir.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.ListProductsRequest;
import com.google.shopping.merchant.products.v1beta.Product;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient.ListProductsPagedResponse;
import com.google.shopping.merchant.products.v1beta.ProductsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to list all the products for a given merchant center account */
public class ListProductsSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void listProducts(Config config) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify the account from which to list all products.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The parent has the format: accounts/{account}
ListProductsRequest request = ListProductsRequest.newBuilder().setParent(parent).build();
System.out.println("Sending list products request:");
ListProductsPagedResponse response = productsServiceClient.listProducts(request);
int count = 0;
// Iterates over all rows in all pages and prints the datasource in each row.
// Automatically uses the `nextPageToken` if returned to fetch all pages of data.
for (Product product : response.iterateAll()) {
System.out.println(product); // The product includes the `productStatus` field
// That shows approval and disapproval information.
count++;
}
System.out.print("The following count of products were returned: ");
System.out.println(count);
} catch (Exception e) {
System.out.println("An error has occured: ");
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
listProducts(config);
}
}