Gerir os seus Produtos

  • Artigo

A API de Conteúdo é uma API RESTful que utiliza o recurso Produtos para gerir ofertas de produtos na sua loja do Microsoft Merchant Center (MMC).

Segue-se o URI base que utiliza para chamar a API de Conteúdo.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

Cada pedido HTTP tem de incluir o token de acesso OAuth do utilizador e o token de programador. Para especificar o token de acesso do utilizador, defina o cabeçalho AuthenticationToken . Para especificar o token do programador, defina o cabeçalho DeveloperToken .

Se gerir catálogos em nome de outros clientes, tem de definir:

Por predefinição, a API de Conteúdo utiliza objetos JSON para representar a oferta do produto. Para utilizar XML, defina o parâmetro de consulta alt como XML.

Para obter detalhes sobre como utilizar o recurso Produtos, veja as secções seguintes.

Obter uma oferta de produto a partir da loja

Para obter uma oferta de produto específica da loja, acrescente o seguinte modelo ao URI base.

{mmcMerchantId}/products/{productUniqueId}

Defina {mmcMerchantId} para o ID da loja MMC e defina {productUniqueId} como o ID de produto completamente qualificado (por exemplo, Online:en:US:Sku123), e não o offerId do produto. Uma vez que o ID do produto é sensível às maiúsculas e minúsculas, utilize o ID que a API lhe devolveu quando adicionou o produto.

Envie um pedido HTTP GET para o URL resultante. Se o produto tiver sido encontrado, a resposta contém um objeto Product que contém a oferta.

Se inseriu um produto com o mesmo ID em vários catálogos, o serviço devolve apenas um deles, que produto e a partir do qual o catálogo é indeterminado. Por este motivo, não deve inserir um produto com o mesmo ID de produto em vários catálogos.

Para obter um exemplo de código que mostra como obter uma oferta de produto, veja Managing Products Code Example (Exemplo de Código da Gestão de Produtos).

Obter uma lista de ofertas de produtos a partir da loja

Para obter uma lista das ofertas de produtos que estão na loja, acrescente o seguinte modelo ao URI base.

{mmcMerchantId}/products

Defina {mmcMerchantId} para o ID da loja MMC.

Para percorrer a lista de ofertas, utilize os parâmetros de consulta max-results e start-token . Na sua primeira chamada, defina max-results como o número máximo de ofertas que pretende que o serviço devolva. O número máximo de ofertas que o serviço pode devolver é 250. A predefinição é 25. Envie um pedido HTTP GET para o URL resultante. Segue-se um exemplo do pedido.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

Se o arquivo contiver ofertas, a resposta contém um objeto Produto que contém até ao número pedido de ofertas.

Se existirem mais ofertas disponíveis, a resposta inclui o nextPageToken campo (consulte Produtos). O nextPageToken campo contém o valor do token que utiliza para definir o start-token parâmetro como no próximo pedido de Lista. Segue-se um exemplo que utiliza o token.

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

Para obter um exemplo de código que mostra como obter uma lista de ofertas de produtos, veja Managing Products Code Example (Exemplo de Código da Gestão de Produtos).

Eliminar uma oferta da loja

Para eliminar uma oferta de produto específica da loja, acrescente o seguinte modelo ao URI base.

{mmcMerchantId}/products/{productUniqueId}

Defina {mmcMerchantId} para o ID da loja MMC e defina {productUniqueId} como o ID de produto completamente qualificado (por exemplo, Online:en:US:Sku123), e não o offerId do produto. Uma vez que o ID do produto é sensível às maiúsculas e minúsculas, utilize o ID que a API lhe devolveu quando adicionou o produto.

Envie um pedido HTTP DELETE para o URL resultante. Se o produto tiver sido encontrado, será eliminado.

Se inseriu um produto com o mesmo ID de produto em vários catálogos, o serviço elimina-os a todos. Não deve inserir um produto com o mesmo ID de produto em vários catálogos.

Para obter um exemplo de código que mostra como eliminar uma oferta de produto, veja Managing Products Code Example (Exemplo de Código da Gestão de Produtos).

Adicionar e atualizar uma oferta de produto

Adicionar ou atualizar uma oferta é uma operação de inserção. Uma vez que uma atualização é uma operação de inserção, tem de incluir todos os campos da oferta no pedido; não é possível atualizar um único campo.

Para inserir uma oferta de produto, acrescente o seguinte modelo ao URI base.

{mmcMerchantId}/products

Defina {mmcMerchantId} para o ID da loja MMC.

Enviar um pedido HTTP POST para o URL resultante escreve a oferta no catálogo de lojas predefinido. Para escrever a oferta num catálogo específico, inclua o parâmetro de consulta bmc-catalog-id .

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

Se o produto tiver sido inserido, a resposta contém um objeto Produto . O Product objeto inclui o ID do produto, que utiliza para obter e eliminar a oferta.

Uma oferta tem de incluir os seguintes campos:

A API utiliza , channelcontentLanguage, targetCountrye offerId para gerar o ID do produto. Uma vez que estes campos são utilizados para gerar o ID, pode não atualizá-los. O ID do produto é sensível às maiúsculas e minúsculas; o ID utiliza a mesma caixa que utilizou para especificar channel, contentLanguage, targetCountrye offerId.

Atenção

Certifique-se de que utiliza a mesma caixa para channel, contentLanguage, targetCountrye offerId porque pode efetivamente adicionar o mesmo produto várias vezes se a caixa for diferente.

Os seguintes campos também são necessários se os valores atribuídos pelo fabricante forem atribuídos.

Tem de especificar os valores, se conhecidos. Se não especificar nenhum deles, tem de definir o campo identifierExists como falso. A predefinição é true.

Se o produto tiver estes identificadores e não os especificar, a MMC aceita o produto por enquanto, mas o Product objeto na resposta inclui o warnings campo . Deve sempre verificar se o warnings campo existe e corrigir todos os problemas identificados.

Além dos campos necessários, também deve especificar a data e hora em que pretende que a oferta expire (veja expirationDate). Por predefinição, a oferta expira 30 dias a partir da data e hora em que é escrita na loja ou catálogo. Deve controlar os produtos que estão prestes a expirar e antes de expirarem atualizar a data de expiração ou simplesmente atualizar o produto (não tem de atualizar nenhum dos campos do produto), o que prolonga automaticamente a data de expiração mais 30 dias. Se definir explicitamente a data de expiração, tem de definir uma nova data de expiração manualmente; atualizar o produto não prolongará automaticamente a data de expiração mais 30 dias neste caso.

Todos os outros campos são considerados opcionais; no entanto, deve especificar quantos forem necessários para descrever com precisão o produto.

Nota

O Product objeto tem de incluir apenas campos definidos como valores. Não inclua campos nulos no Product objeto. Por exemplo, não inclua "adult":null.

A Microsoft não utiliza todos os Product campos. Para obter uma lista dos campos que a API aceita mas não utiliza, consulte Que atributos do Google posso utilizar? Todos os outros campos utilizados pela Microsoft são utilizados para filtrar os produtos ao servir anúncios de produtos.

Se especificar um campo desconhecido para a API de Conteúdo, o serviço ignora o campo.

Quando insere uma oferta, o serviço efetua validações básicas na oferta e devolve erros e avisos conforme adequado. Se ocorrer um erro, a resposta contém um ErrorResponse objeto. Se ocorrerem avisos, a resposta contém um Product objeto e o warnings campo lista os avisos.

Se a oferta passar as validações básicas, passa por validações e revisões offline, como críticas editoriais, que podem demorar até 36 horas. A oferta não servirá até que todas as validações e revisões estejam concluídas. Para determinar o estado de uma oferta, utilize o recurso Estado .

Tenha em atenção que a API não fornece controlos de simultaneidade, como ETags. Se duas aplicações estiverem a tentar adicionar ou atualizar o mesmo produto, a última ganha.

Uma oferta que é apresentada num anúncio de produto inclui o preço, título, nome da loja (ou sellerName, se especificado), uma ligação para a página Web que contém mais informações sobre o produto e uma imagem do produto.

Para produtos de vestuário disponíveis em múltiplas cores, padrões ou materiais, crie um produto para cada variante e utilize o campo itemGroupId para agrupar todas as variantes do produto.

Para obter um exemplo de código que mostra como inserir uma oferta de produto, veja Managing Products Code Example (Exemplo de Código da Gestão de Produtos).

Utilizar o processamento em lotes

Se estiver a processar várias ofertas de produtos, deve considerar utilizar a funcionalidade de processamento em lotes da API. Esta funcionalidade permite-lhe processar várias inserções, obténs e eliminações num único pedido. Processar várias ofertas no mesmo pedido é mais eficiente do que enviar um pedido separado para cada oferta. O custo incorrido com o processamento de um único pedido é distribuído por milhares de ofertas no pedido de lote em vez de incorrer nesse custo para cada pedido individual.

Não insira, obtenha ou elimine o mesmo produto no mesmo pedido.

Para enviar um pedido em lote, acrescente o seguinte modelo ao URI base.

{mmcMerchantId}/products/batch

Defina {mmcMerchantId} para o ID da loja MMC.

Enviar um pedido HTTP POST para o URL resultante aplica as operações de inserção ao catálogo de arquivo predefinido. Para aplicar as ofertas a um catálogo específico, inclua o parâmetro de consulta bmc-catalog-id .

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

O corpo do POST é um objeto do Batch que contém uma matriz de objetos de Item . Para todas as operações, defina os batchIdcampos e merchantIdmethod . O batchId é um ID definido pelo utilizador que utiliza para identificar o item de lote na resposta; o é o merchantId seu ID de arquivo; e é a method operação a ser executada (por exemplo, inserir, eliminar ou obter).

Se method for inserido, defina o product campo como um objeto Produto que contém a oferta a adicionar ou atualizar. Caso contrário, se method for um get ou delete, defina productId para o ID completamente qualificado da oferta que pretende obter ou eliminar.

O tamanho do corpo de um pedido em lote pode não exceder os 4 MB. Se o corpo exceder 4 MB, a resposta devolve o código de estado HTTP 413. Consoante o tamanho de cada oferta (o número de campos que especificar), pode enviar entre 2000 e 6000 ofertas. Se comprimir o corpo, pode enviar o número máximo de ofertas, que é 12 000 (consoante o respetivo tamanho).

Para comprimir o corpo, utilize apenas compressão GZip e defina o cabeçalho Content-Encoding do pedido como gzip.

O serviço processa cada item no lote. A resposta contém um objeto que contém cada um BatchItem que estava no pedido. Tenha em atenção que não há garantias de que a ordem dos itens na resposta esteja na mesma ordem que os itens no pedido.

Para operações de inserção, o item inclui apenas os batchId campos e product . O product campo contém a mesma oferta que enviou no pedido, mas também inclui o ID de produto completamente qualificado. Se ocorrer um erro ou aviso, o item inclui os batchIdcampos , methode error . O error campo contém os motivos pelos quais a inserção falhou ou avisos sobre problemas com a oferta que precisa de corrigir.

Para obter operações, o item inclui os batchId campos e product . O product campo contém a oferta que pediu. Se o produto não for encontrado, o objeto não incluirá o product campo.

Para operações de eliminação, o item inclui apenas o batchId campo; não há indicação se a oferta existe e foi eliminada.

Para obter um exemplo de código que mostra como utilizar o processamento em lotes, veja Creating a Batch Request (Criar um Pedido do Batch).