Risorsa inventario

  • Articolo

Nota

L'API Inventario è disponibile solo per i partecipanti pilota chiusi. L'API e la documentazione sono soggette a modifiche.

La risorsa Inventario consente di aggiornare i prezzi e la disponibilità dei prodotti nello store Microsoft Merchant Center (MMC). Per informazioni sull'uso delle risorse di inventario, vedere Aggiornamento dei prezzi dei prodotti. Per esempi che illustrano come aggiornare prezzi e disponibilità, vedere Esempi di codice.

Base URI

Di seguito è riportato l'URI di base a cui si aggiungono i modelli.

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

Modelli

Per creare gli endpoint usati per aggiornare le offerte di prodotto, aggiungere il modello appropriato all'URI di base.

Modello Verbo HTTP Descrizione
/bmc/{mmcMerchantId}/inventory/batch POST Usare per eseguire più aggiornamenti dei prezzi dei prodotti in una singola richiesta.

Impostare sull'ID {mmcMerchantId} archivio MMC.

Oggetto Request: Batch
Oggetto risposta: Batch
/bmc/{mmcMerchantId}/inventory/{storeCode}/products/{productUniqueId} POST Usare per aggiornare i prezzi e la disponibilità di un singolo prodotto.

Impostare sull'ID {mmcMerchantId} archivio MMC.

Impostare su {storeCode} online.

Impostare {productUniqueId} sull'ID prodotto completo, ad esempio Online:en:US:Sku123.

Oggetto richiesta: Product
Oggetto risposta: Product

Parametri di query

Gli endpoint possono includere i parametri di query seguenti.

Parametro Descrizione
dry-run Facoltativo. Usare quando si esegue il debug dell'applicazione per testare le chiamate. Le chiamate che includono questo parametro non influiscono sui dati di produzione. Se si verifica un errore, la risposta contiene eventuali errori generati normalmente dalla chiamata, ad eccezione dei messaggi di errore secondari, ad esempio la qualità dei dati, i problemi editoriali e le convalide correlate al database. Per altre informazioni sul test dell'applicazione, vedere Sandbox.

Intestazioni

Di seguito sono riportate le intestazioni di richiesta e risposta.

Intestazione Descrizione
AuthenticationToken Intestazione della richiesta.

Impostare questa intestazione su un token di accesso OAuth. Per informazioni su come ottenere un token di accesso, vedere Autenticazione delle credenziali.
Content-Type Intestazione della richiesta e della risposta.

Tipo di contenuto nel corpo della richiesta o della risposta. Impostare su application/json.
CustomerAccountId Intestazione della richiesta.

ID account di qualsiasi account gestito per conto del cliente specificato nell'intestazione CustomerId . Non importa quale account specificare. Specificare questa intestazione solo se si gestisce un account per conto del cliente.
Customerid Intestazione della richiesta.

ID cliente del cliente di cui si gestisce il negozio. Specificare questa intestazione solo se si gestisce lo store per conto del cliente. Se si imposta questa intestazione, è necessario impostare anche l'intestazione CustomerAccountId .
DeveloperToken Intestazione della richiesta.

Token di sviluppo dell'applicazione client. Ogni richiesta deve includere questa intestazione. Per informazioni su come ottenere un token, vedere Le credenziali di Microsoft Advertising e il token per sviluppatori sono disponibili?
Posizione Intestazione della risposta.

URL del prodotto aggiornato.
WebRequestActivityId Intestazione della risposta.

ID della voce di log che contiene i dettagli della richiesta. È consigliabile acquisire sempre questo ID se si verifica un errore. Se non si è in grado di determinare e risolvere il problema, includere questo ID insieme alle altre informazioni fornite al team di supporto.

Oggetti richiesta e risposta

Di seguito sono riportati gli oggetti richiesta e risposta usati dall'API.

Oggetto Descrizione
Lotto Definisce l'elenco di prodotti da aggiornare in una richiesta batch.
Errore Definisce un errore.
ErrorResponse Definisce l'oggetto errore di primo livello per un aggiornamento non batch.
BatchEntryError Definisce gli errori che si sono verificati per un elemento durante l'elaborazione batch.
Voce Definisce una voce in una richiesta o una risposta batch.
Prodotto Definisce un prodotto.
ProductPrice Definisce il prezzo di un prodotto.

Lotto

Definisce l'elenco di prodotti da aggiornare in un batch.

Name Valore Tipo
Voci Elenco di prodotti da aggiornare in un batch. Il numero massimo di prodotti che è possibile specificare è 400. Entry[]

BatchEntryError

Definisce gli errori che si sono verificati per una voce durante l'elaborazione batch.

Name Valore Tipo
Errori Elenco di errori che si sono verificati durante l'elaborazione della voce. Errore[]
code Codice di stato HTTP dell'errore. Stringa
messaggio Messaggio associato all'errore. Stringa

Error

Definisce un errore.

Name Valore Tipo
dominio Solo per uso interno. Stringa
messaggio Descrizione dell'errore. Stringa
motivo Motivo per cui la richiesta non è riuscita. Ad esempio, la convalida del prodotto non è riuscita. Stringa

ErrorResponse

Definisce l'oggetto errore di primo livello per un singolo aggiornamento del prodotto.

Name Valore Tipo
Errore Elenco di errori che si sono verificati durante l'elaborazione dell'elemento. Errori[]

Errori

Definisce l'elenco di errori per un prodotto.

Name Valore Tipo
Errori Elenco di errori che si sono verificati durante l'elaborazione della voce. Errore[]
code Codice di stato HTTP dell'errore. Stringa
messaggio Messaggio associato all'errore. Stringa

Voce

Definisce una voce in una richiesta batch.

Name Valore Tipo
Batchid ID definito dall'utente che identifica in modo univoco questa voce nella richiesta batch. Ad esempio, se il batch contiene 10 voci, è possibile assegnargli gli ID da 1 a 10. Unsigned Integer
Errori Oggetto errore che contiene un elenco di errori di convalida che si sono verificati. La risposta include questo campo solo quando si verifica un errore. BatchEntryError
Inventario Prezzo e disponibilità aggiornati. Prodotto
merchantId ID archivio Merchant Center. Poiché l'URL include l'ID archivio, questo campo viene ignorato. Long senza segno
Productid ID prodotto completo (ad esempio, Online:en:US:Sku123) del prodotto da aggiornare. Non includere più voci con lo stesso ID prodotto. Stringa
storeCode Codice che identifica l'archivio da aggiornare. Impostare su online per aggiornare il prezzo e la disponibilità dei prodotti nel negozio online. Stringa

Prodotto

Definisce un prodotto.

Proprietà Descrizione Tipo Obbligatorio
Disponibilità Disponibilità del prodotto. Valori possibili:
  • in magazzino
  • esaurito
  • Preorder
 Stringa Sì
gentile Tipo dell'oggetto. Impostare su content#inventory. Stringa No
Prezzo Nuovo prezzo del prodotto. Specificare il prezzo nella valuta del paese o dell'area geografica di destinazione. Per informazioni sull'inclusione delle imposte nel prezzo, vedere Criteri fiscali del catalogo di Microsoft Merchant Center.

Il prezzo deve corrispondere al prezzo visualizzato nella pagina Web del prodotto e deve essere compreso nell'intervallo da 0,01 (1 cent) a 10000000,00 (10 milioni). Tuttavia, se vengono soddisfatte le condizioni seguenti, è possibile impostare il prezzo su 0,0 (zero).
  1. Il campo del googleProductCategory prodotto è impostato su una delle categorie seguenti:
    • Elettronica > Comunicazioni > Telefonia > Cellulare
    • Computer elettronici >> Tablet Computer
  2. Il campo del title prodotto contiene una delle parole chiave seguenti:
    • Contratto
    • Rata
    • Locazione
    • Pagamento
    Le parole chiave precedenti sono visualizzate in inglese; tuttavia, il titolo e la parola chiave devono essere nella lingua del mercato specificato.

    In genere, il titolo conterrà formulazioni come "... con piano di rata" o "... solo con contratto". La parola chiave contract può essere usata in tutti i mercati; tuttavia, la rata, il pagamento e il lease possono essere usati solo nel mercato statunitense.
 ProductPrice Sì
salePrice Prezzo di vendita del prodotto. Per gli articoli in vendita, impostare sia il prezzo di vendita che la data di validità della vendita (vedere salePriceEffectiveDate). Se si imposta il prezzo di vendita ma non la data di validità del prezzo di vendita, il prezzo di vendita continuerà a essere utilizzato fino alla scadenza del prodotto o all'impostazione di una data di validità.

Il prezzo di vendita deve essere compreso tra 0,01 (1 cent) e 100000000,00 (10 milioni). Tuttavia, se vengono soddisfatte le condizioni seguenti, è possibile impostare il prezzo di vendita su 0,0 (zero).
  1. Il campo googleProductCategory è impostato su una delle categorie seguenti:
    • Elettronica > Comunicazioni > Telefonia > Cellulare
    • Computer elettronici >> Tablet Computer
  2. Il campo del titolo contiene una delle parole chiave seguenti:
    • Contratto
    • Rata
    • Locazione
    • Pagamento
    Le parole chiave precedenti sono visualizzate in inglese; tuttavia, il titolo e la parola chiave devono essere nella lingua del mercato specificato.

    In genere, il titolo conterrà formulazioni come "... con piano di rata" o "... solo con contratto". La parola chiave contract può essere usata in tutti i mercati; tuttavia, la rata, il pagamento e il lease possono essere usati solo nel mercato statunitense.
Se non specificato, il prezzo della vendita corrente viene rimosso dall'offerta. Non passare null.		 ProductPrice No
salePriceEffectiveDate Data di inizio e fine UTC della vendita. Specificare una data solo se si imposta salePrice.

Specificare le date di inizio e fine nel formato ISO 8601 . Ad esempio, 2016-04-05T08:00-08:00/2016-04-10T19:30-08:00 (usare una barra ('/') per separare le date di inizio e fine). Per ulteriori informazioni, vedere salePrice.

Se non specificato, la data di vendita corrente viene rimossa dall'offerta. Non passare null.		 Stringa No

ProductPrice

Definisce il prezzo o il prezzo di vendita di un prodotto.

Name Valore Tipo
Valuta Valuta in cui viene indicato il prezzo. Valori possibili:
  • AUD (dollaro australiano)
  • CAD (dollaro canadese)
  • CHF (franco svizzero)
  • EUR (Euro)
  • GBP (Gran Bretagna)
  • INR (rupia indiana)
  • SEK (corona svedese)
  • USD (Stati Uniti dollaro)
 Stringa
valore Prezzo del prodotto. Double

Codici di stato HTTP

Le richieste possono restituire i codici di stato HTTP seguenti.

Codice di stato Descrizione
200 Completato.
400 Richiesta non valida. Un valore del parametro di query non è valido o un elemento nel corpo della richiesta non è valido.

Se si verifica un errore, la voce batch non riuscita includerà gli errori.
401 Non autorizzato. Le credenziali dell'utente non sono valide.
403 Proibito. L'utente non dispone delle autorizzazioni per usare la risorsa.
404 Non trovato.
409 Conflitto. Impossibile completare l'operazione a causa di un conflitto con lo stato corrente della risorsa.
413 Entità richiesta troppo grande. Le dimensioni della richiesta superano il massimo consentito.
500 Errore del server.