Migrazione dalla versione v1beta alla versione v1

Questa guida ti aiuta a eseguire la migrazione dalla versione dell'API Merchant v1beta alla versione v1, la prima versione per la disponibilità generale. La versione v1 introduce diversi aggiornamenti e alcune modifiche che potrebbero richiedere aggiornamenti del codice. Queste modifiche sono progettate per semplificare l'API e migliorare la gestione del tuo account Merchant Center.

Differenze principali

Di seguito sono riportate le modifiche più importanti di cui devi tenere conto durante la migrazione da v1beta a v1:

• Registrazione una tantum di almeno uno sviluppatore di API per utilizzare l'API Merchant: dovrai chiamare il metodo registerGcp (una sola volta per ogni progetto Google Cloud utilizzato per l'autenticazione) per fornire i tuoi dati di contatto, che ti consentono di utilizzare l'API e di ricevere aggiornamenti e annunci relativi all'API Merchant. Non potrai utilizzare alcuna API v1 o v1alpha finché non avrai completato questo passaggio. Per ulteriori informazioni sulla procedura di registrazione, consulta la sezione Registrazione.

• Codifica del nome del prodotto: i campi ProductInput.name e Product.name supportano la codifica base64url senza padding (RFC 4648 Sezione 5). Segui queste linee guida:

  • Prima della codifica, la stringa deve rispettare il formato contentLanguage~feedLabel~offerId.

  • La codifica è obbligatoria se il nome del prodotto contiene caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL, ad esempio:

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • Se il nome del prodotto rispetta il contentLanguage~feedLabel~offerId formato e non contiene caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL, puoi utilizzare il formato semplice, senza codifica.

  • Per garantire un'analisi coerente e corretta, ti consigliamo di utilizzare la codifica base64url senza padding per tutti i nomi dei prodotti.

• Rimozione dei dati fiscali a livello di prodotto: taxes e taxCategory.

• Product.attributes rinominato: il campo Product.attributes è stato rinominato in Product.productAttributes.

• Rimozione dei dati fiscali a livello di prodotto: I campi taxes e taxCategory sono stati rimossi dall' Product.productAttributes oggetto. Per ulteriori informazioni, consulta l' articolo del Centro assistenza Google Merchant Center relativo alle imposte.

• Modifiche al campo GTIN: Il campo gtin nell'oggetto Product.productAttributes è stato rinominato in gtins per riflettere meglio il fatto che può contenere più valori. Anche il campo gtin nell' OrderTrackingSignals.lineItemDetails oggetto è ora un array ed è stato rinominato in gtins as well.

• Rimozione del campo canale: il campo channel è stato rimosso da prodotti, input di prodotto e origini dati. È stato introdotto un nuovo campo booleano, legacyLocal, per designare chiaramente i prodotti venduti esclusivamente nei negozi fisici. Nota: il campo legacyLocal è un campo ausiliario per facilitare la migrazione e verrà ritirato una volta che i metodi di marketing online e locale potranno essere completamente targetizzati con una singola origine prodotto. Per ulteriori informazioni, consulta la tabella nella sezione seguente.

• Nuovi campi per gli attributi di inventario regionale e locale:

  • Tutti i campi RegionalInventory tranne name, account e region sono ora racchiusi in un nuovo oggetto chiamato regionalInventoryAttributes . Ad esempio, l'attributo RegionalInventory.price si trova ora in RegionalInventory.regionalInventoryAttributes.price.
  • Tutti i LocalInventory campi tranne name, account e storeCode sono ora racchiusi in un nuovo oggetto chiamato localInventoryAttributes . Ad esempio, l'attributo LocalInventory.price si trova ora in LocalInventory.localInventoryAttributes.price.

• Rimozione di customAttributes dagli inventari regionali e locali: Il campo customAttributes è stato rimosso dalle risorse RegionalInventory e LocalInventory.

• Creazione dell'account perfezionata: il campo ridondante users è stato rimosso da CreateAndConfigureAccountRequest. Utilizza il campo user al singolare per associare un utente iniziale a un nuovo account.

• Alcuni tipi di attributi sono stati modificati da stringhe a enum: Alcuni campi all'interno delle risorse Product e Inventory con un elenco breve di valori definiti sono stati modificati dal tipo string al tipo enum per una migliore convalida dei dati (ad esempio, il campo Product.ProductAttributes.condition è ora un enum).

• Rimozione del metodo di aggiornamento delle norme sui resi online: Il onlineReturnPolicy.update metodo viene rimosso in v1. Crea invece una norma sui resi online utilizzando il onlineReturnPolicy.create metodo.

Come eseguire la migrazione

La versione v1beta dell'API Merchant verrà ritirata il 28 febbraio 2026. Per ulteriori informazioni sulla pianificazione del ritiro, consulta la guida al controllo delle versioni dell'API Merchant.

• Il primo passo per la migrazione è eseguire una registrazione una tantum dello sviluppatore (vedi Registrarsi come sviluppatore). Prima che i metodi v1 funzionino, devi chiamare il metodo registerGcp per ogni progetto cloud di Google Cloud che utilizzi per l'autenticazione.

• Indipendentemente dalla modalità di chiamata delle API (con REST, gRPC o utilizzando le librerie client), puoi eseguire la migrazione in più fasi. Ciò significa che puoi aggiornare ed eseguire la migrazione del codice un'API alla volta (ad esempio, spostando l'API Products su v1 mantenendo l'API Accounts su v1beta) senza dover aggiornare l'intera integrazione contemporaneamente.

Modifiche dettagliate dei campi

Questa tabella fornisce un confronto dettagliato dei campi che sono stati modificati tra le v1beta e v1 versioni.

v1beta	v1	Descrizione
ProductInput.name	ProductInput.name	Unpadded base64url encoding supportata e obbligatoria per i nomi dei prodotti che contengono caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL.
Product.name	Product.name	Unpadded base64url encoding supportata e obbligatoria per i nomi dei prodotti che contengono caratteri utilizzati dall'API Merchant o caratteri riservati per gli URL.
Product.gtin	Product.gtins	Il campo per i GTIN è stato rinominato.
Product.taxes	Rimosso	Il campo taxes è stato rimosso.
Product.taxCategory	Rimosso	Il campo taxCategory è stato rimosso.
Product.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il legacyLocal campo per i casi d'uso locali.
Product.attributes	Product.productAttributes	Il campo attributes è stato rinominato in productAttributes.
availability, condition, gender, includedDestinations e excludedDestinations nei campi Product sono rappresentati come strings (o array di strings)	Questi campi sono ora enums (o array di enums)	I campi con un elenco breve di valori definiti sono stati modificati dal tipo string al tipo enum.
price, salePrice, salePriceEffectiveDate e availability in RegionalInventory	Spostato in RegionalInventory.regionalInventoryAttributes	Questi campi sono stati spostati in regionalInventoryAttributes.
Il campo RegionalInventory.availability è una string	RegionalInventory.regionalInventoryAttributes.availability è ora un enums	Il tipo di disponibilità è stato modificato da string a enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla e instoreProductLocation in LocalInventory	Spostato in LocalInventory.localInventoryAttributes	Questi campi sono stati spostati in localInventoryAttributes.
Il campo LocalInventory.availability è una string	LocalInventory.localInventoryAttributes.availability è ora un enums	Il tipo di disponibilità è stato modificato da string a enum.
LocalInventory.customAttributes	Rimosso	Gli attributi personalizzati non sono più supportati per l'inventario locale.
RegionalInventory.customAttributes	Rimosso	Gli attributi personalizzati non sono più supportati per l'inventario regionale.
ProductInput.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il legacyLocal campo per i casi d'uso locali.
DataSource.channel	Rimosso	Il campo channel è stato rimosso. Utilizza il legacyLocal campo per i casi d'uso locali.
Non disponibile	ProductInput.legacyLocal	Un nuovo campo booleano per indicare che un prodotto può essere targetizzato solo con metodi di marketing locali marketing. L'ID risorsa prodotto avrà il prefisso "local~".
Non disponibile	Product.legacyLocal	Un nuovo campo booleano per indicare che un prodotto viene venduto solo nei negozi locali e non è disponibile per l'acquisto online.
Non disponibile	DataSource.legacyLocal	Un nuovo campo booleano per indicare che un'origine dati contiene prodotti venduti solo nei negozi locali.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Il campo gtin è stato rinominato in gtins e è ora un array di stringhe (anziché una stringa).
CreateAndConfigureAccountRequest.users	Rimosso	Il campo users è stato rimosso. Utilizza il user campo per aggiungere l'amministratore iniziale all'account.