Compartilhar via

Recurso de inventário

  • Artigo

Nota

A API de Inventário está disponível apenas para participantes piloto fechados. A API e a documentação estão sujeitas a alterações.

O recurso Inventário permite-lhe atualizar os preços e a disponibilidade dos produtos na loja do Microsoft Merchant Center (MMC). Para obter informações sobre como utilizar os recursos de Inventário, veja Atualizar os preços dos produtos. Para obter exemplos que mostram como atualizar os preços e a disponibilidade, veja Exemplos de Código.

Base URI

Segue-se o URI base ao qual acrescenta os modelos.

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

Modelos

Para criar os pontos finais utilizados para atualizar as ofertas de produtos, acrescente o modelo adequado ao URI base.

Modelo Verbo HTTP Descrição
/bmc/{mmcMerchantId}/inventory/batch POST Utilize para efetuar várias atualizações de preços de produtos num único pedido.

Defina {mmcMerchantId} para o ID da loja MMC.

Objeto de pedido: Batch
Objeto de resposta: Batch
/bmc/{mmcMerchantId}/inventory/{storeCode}/products/{productUniqueId} POST Utilizado para atualizar os preços e a disponibilidade de um único produto.

Defina {mmcMerchantId} para o ID da loja MMC.

Defina {storeCode} como online.

Defina {productUniqueId} como o ID de produto completamente qualificado (por exemplo, Online:en:US:Sku123).

Objeto do pedido: Produto
Objeto de resposta: Produto

Parâmetros de consulta

Os pontos finais podem incluir os seguintes parâmetros de consulta.

Parâmetro Descrição
dry-run Opcional. Utilize ao depurar a sua aplicação para testar chamadas. As chamadas que incluem este parâmetro não afetarão os dados de produção. Se ocorrer um erro, a resposta contém quaisquer erros que a chamada gera normalmente, exceto mensagens de erro secundárias, como qualidade de dados, problemas editoriais e validações relacionadas com a base de dados. Para obter mais informações sobre como testar a sua aplicação, consulte Sandbox.

Cabeçalhos

Seguem-se os cabeçalhos de pedido e resposta.

Cabeçalho Descrição
AuthenticationToken Cabeçalho do pedido.

Defina este cabeçalho para um token de acesso OAuth. Para obter informações sobre como obter um token de acesso, consulte Autenticar as suas credenciais.
Tipo de Conteúdo Cabeçalho de pedido e resposta.

O tipo de conteúdo no corpo do pedido ou resposta. Definido como application/json.
CustomerAccountId Cabeçalho do pedido.

O ID de conta de qualquer conta que gere em nome do cliente especificado no CustomerId cabeçalho. Não importa a conta que especificar. Especifique este cabeçalho apenas se gerir uma conta em nome do cliente.
CustomerId Cabeçalho do pedido.

O ID de cliente do cliente cuja loja gere. Especifique este cabeçalho apenas se gerir a loja em nome do cliente. Se definir este cabeçalho, também tem de definir o CustomerAccountId cabeçalho.
DeveloperToken Cabeçalho do pedido.

O token de programador da aplicação cliente. Cada pedido tem de incluir este cabeçalho. Para obter informações sobre como obter um token, consulte Tem as credenciais do Microsoft Advertising e o token de programador?
Localização Cabeçalho de resposta.

O URL do produto que foi atualizado.
WebRequestActivityId Cabeçalho de resposta.

O ID da entrada de registo que contém os detalhes do pedido. Deve sempre capturar este ID se ocorrer um erro. Se não conseguir determinar e resolver o problema, inclua este ID juntamente com as outras informações que fornecer à equipa de Suporte.

Objetos de pedido e resposta

Seguem-se os objetos de pedido e resposta utilizados pela API.

Objeto Descrição
Batch Define a lista de produtos a atualizar num pedido de lote.
Erro Define um erro.
ErrorResponse Define o objeto de erro de nível superior para uma atualização não lote.
BatchEntryError Define os erros que ocorreram para um item durante o processamento em lotes.
Entrada Define uma entrada num pedido ou resposta em lote.
Produto Define um produto.
PreçoDoProduto Define o preço de um produto.

Batch

Define a lista de produtos a atualizar num lote.

Name Valor Tipo
entradas Uma lista de produtos a atualizar num lote. O número máximo de produtos que pode especificar é 400. Entrada[]

BatchEntryError

Define os erros que ocorreram para uma entrada durante o processamento em lotes.

Name Valor Tipo
erros Uma lista de erros que ocorreram durante o processamento da entrada. Erro[]
código O código de estado HTTP do erro. Cadeia
Mensagem A mensagem associada ao erro. Cadeia

Erro

Define um erro.

Name Valor Tipo
domínio Apenas para utilização interna. Cadeia
Mensagem Uma descrição do erro. Cadeia
motivo O motivo pelo qual o pedido falhou. Por exemplo, a validação do produto falhou. Cadeia

ErrorResponse

Define o objeto de erro de nível superior para uma única atualização de produto.

Name Valor Tipo
erro Uma lista de erros que ocorreram durante o processamento do item. Erros[]

Erros

Define a lista de erros de um produto.

Name Valor Tipo
erros Uma lista de erros que ocorreram durante o processamento da entrada. Erro[]
código O código de estado HTTP do erro. Cadeia
Mensagem Uma mensagem associada ao erro. Cadeia

Entrada

Define uma entrada num pedido de lote.

Name Valor Tipo
batchId Um ID definido pelo utilizador que identifica exclusivamente esta entrada no pedido de lote. Por exemplo, se o lote contiver 10 entradas, pode atribuir-lhes IDs de 1 a 10. Número Inteiro Não Assinado
erros Um objeto de erro que contém uma lista de erros de validação que ocorreram. A resposta inclui este campo apenas quando ocorre um erro. BatchEntryError
inventário O preço e a disponibilidade atualizados. Produto
merchantId O ID da loja Merchant Center. Uma vez que o URL inclui o ID de arquivo, este campo é ignorado. Sem Assinatura Por Extenso
productId O ID de produto completamente qualificado (por exemplo, Online:en:US:Sku123) do produto a atualizar. Não inclua múltiplas entradas com o mesmo ID de produto. Cadeia
storeCode O código que identifica o arquivo a atualizar. Defina como online para atualizar o preço e a disponibilidade dos produtos na loja online. Cadeia

Produto

Define um produto.

Propriedade Descrição Tipo Obrigatório
disponibilidade A disponibilidade do produto. Valores possíveis:
  • em stock
  • fora de stock
  • pré-encomenda
 Cadeia Sim
tipo O tipo do objeto. Defina como conteúdo#inventário. Cadeia Não
preço O novo preço do produto. Especifique o preço na moeda do país ou região de destino. Para obter informações sobre se deve incluir impostos no preço, consulte Política fiscal do catálogo do Centro de Comerciantes da Microsoft.

O preço tem de corresponder ao preço apresentado na página Web do produto e tem de estar entre 0,01 (1 cêntimo) e 10000000,00 (10 milhões). No entanto, se as seguintes condições forem cumpridas, pode definir o preço como 0,0 (zero).
  1. O campo do googleProductCategory produto está definido para uma das seguintes categorias:
    • Telefones > Móveis de Telefonia de > Comunicações Eletrónicas >
    • Computadores Eletrónicos > Tablet > Computadores
  2. O campo do title produto contém uma das seguintes palavras-chave:
    • contrato
    • prestação
    • concessão
    • pagamento
    As palavras-chave acima são apresentadas em inglês; no entanto, o título e a palavra-chave têm de estar no idioma do mercado especificado.

    Normalmente, o título contém sintagmas como "... com plano de prestação" ou "... apenas com contrato". A palavra-chave do contrato pode ser utilizada em todos os mercados; no entanto, a prestação, o pagamento e a concessão só podem ser utilizados no mercado norte-americano.
 PreçoDoProduto Sim
salePrice O preço de venda do produto. Para itens de venda, defina o preço de venda e a data efetiva da venda (consulte salePriceEffectiveDate). Se definir o preço de venda, mas não a data efetiva do preço de venda, o preço de venda continuará a ser utilizado até que o produto expire ou defina uma data efetiva.

O preço de venda tem de estar entre 0,01 (1 cêntimo) e 10000000,00 (10 milhões). No entanto, se as seguintes condições forem cumpridas, pode definir o preço de venda como 0,0 (zero).
  1. O campo googleProductCategory está definido para uma das seguintes categorias:
    • Telefones > Móveis de Telefonia de > Comunicações Eletrónicas >
    • Computadores Eletrónicos > Tablet > Computadores
  2. O campo de título contém uma das seguintes palavras-chave:
    • contrato
    • prestação
    • concessão
    • pagamento
    As palavras-chave acima são apresentadas em inglês; no entanto, o título e a palavra-chave têm de estar no idioma do mercado especificado.

    Normalmente, o título contém sintagmas como "... com plano de prestação" ou "... apenas com contrato". A palavra-chave do contrato pode ser utilizada em todos os mercados; no entanto, a prestação, o pagamento e a concessão só podem ser utilizados no mercado norte-americano.
Se não for especificado, o preço da venda atual é removido da oferta. Não passe nulo.		 PreçoDoProduto Não
salePriceEffectiveDate A data de início e fim utc da venda. Especifique uma data apenas se definir salePrice.

Especifique as datas de início e de fim no formato ISO 8601 . Por exemplo, 2016-04-05T08:00-08:00/2016-04-10T19:30-08:00 (utilize uma barra ('/') para separar as datas de início e de fim). Para obter mais informações, consulte salePrice.

Se não for especificado, a data da venda atual é removida da oferta. Não passe nulo.		 Cadeia Não

PreçoDoProduto

Define o preço ou o preço de venda de um produto.

Name Valor Tipo
moeda A moeda em que o preço é indicado. Valores possíveis:
  • AUD (dólar australiano)
  • CAD (dólar canadiano)
  • CHF (franco suíço)
  • EUR (Euro)
  • GBP (libra da Grã-Bretanha)
  • INR (rupia indiana)
  • SEK (coroa sueca)
  • USD (dólar Estados Unidos)
 Cadeia
valor O preço do produto. Duplo

Códigos de estado HTTP

Os pedidos podem devolver os seguintes códigos de estado HTTP.

Código de estado Descrição
200 Sucesso.
400 Pedido incorreto. Um valor de parâmetro de consulta não é válido ou algo no corpo do pedido não é válido.

Se ocorrer um erro, a entrada em lote que falhou incluirá os erros.
401 Não autorizado. As credenciais do utilizador não são válidas.
403 Proibido. O utilizador não tem permissões para utilizar o recurso.
404 Não encontrado.
409 Conflito. Não foi possível concluir a operação devido a um conflito com o estado atual do recurso.
413 Entidade de pedido demasiado grande. O tamanho do pedido excede o máximo permitido.
500 Erro do servidor.