NovitàProduct Score, 4T Segmentation, Price War e Broken Size sono disponibili.Scopri le novità
Feedance
Articolo

Risolvere gli errori 410 della Content API di Google: migrare la pipeline del feed alla Merchant API

La Content API for Shopping restituisce errori 410. Trova le chiamate rimaste, mappale sulla Merchant API e verifica i prodotti in Merchant Center.

Cagdas PolatCagdas Polat
9 min di lettura
Risolvere gli errori 410 della Content API di Google: migrare la pipeline del feed alla Merchant API

La Content API for Shopping di Google è stata dismessa il 18 agosto 2026. Dal 1° settembre, le richieste provenienti da progetti senza un'estensione approvata falliscono a intermittenza con HTTP 410, e gli endpoint verranno disattivati completamente all'inizio del 2027 (avviso di dismissione di Google). Se uno script, un plugin o un connettore interno invia ancora i tuoi prodotti a Merchant Center tramite la vecchia API, alcuni di quegli aggiornamenti vengono già persi.

Questa guida è per sviluppatori e responsabili del feed che gestiscono in prima persona quella pipeline. Alla fine saprai individuare tutte le chiamate alla Content API ancora presenti, mappare ciascuna sul suo equivalente nella Merchant API, creare la fonte dati richiesta dalla nuova API e verificare in Merchant Center che prodotti e prezzi continuino ad arrivare.

Come capire se la dismissione ti sta colpendo

Il problema è facile da non notare perché è intermittente. Google documenta il corpo dell'errore come un 410 con un messaggio che inizia con "Content API for Shopping was sunset on August 18, 2026" e che include l'ID del progetto Google Cloud, il numero del progetto e un link al centro assistenza. Cerca quella stringa nei log della tua integrazione, insieme a shoppingcontent.googleapis.com.

Di solito compaiono tre sintomi prima che qualcuno legga un log:

  • Le variazioni di prezzo o disponibilità arrivano a Google con ore di ritardo, o solo in alcune esecuzioni.
  • Un job giornaliero segnala il successo sulla maggior parte dei batch e fallisce su alcuni.
  • Merchant Center mostra dati obsoleti mentre il tuo negozio mostra il prezzo corretto.

L'ultimo sintomo ha una seconda causa possibile: gli aggiornamenti automatici degli articoli di Google che sovrascrivono i tuoi valori. Ne parliamo separatamente in come impedire a Google di sovrascrivere silenziosamente prezzo e disponibilità del tuo feed. Escludi prima gli errori 410, perché verificarli costa meno.

Passo 1: censisci ogni chiamante della vecchia API

Le indicazioni di Google sono di esaminare il codice dell'applicazione alla ricerca di chiamate dirette agli endpoint della Content API. In pratica le chiamate si nascondono in quattro posti: il plugin Google della piattaforma del negozio, uno script personalizzato scritto da uno sviluppatore precedente, un middleware di feed o ERP e uno script di Google Ads o Apps Script che qualcuno ha pianificato anni fa.

Crea un breve registro con una riga per chiamante. Annota cosa fa, con quale progetto Google Cloud si autentica e chi ne è responsabile. L'ID del progetto è importante perché le estensioni e il messaggio 410 sono legati a esso.

ChiamanteCosa inviaResponsabileAzione
Plugin del negozioCatalogo completo, ogni giornoFornitore della piattaformaChiedere quale versione dell'API usa ora
Script di inventarioPrezzo e stock, ogni oraIl tuo sviluppatoreMigrare alla Merchant API
Strumento di feed managementFeed ottimizzatoFornitore dello strumentoChiedere conferma scritta della migrazione

Se la connessione è gestita da un fornitore, il tuo compito è chiedere, non ricostruire. Productsup e Feedonomics hanno entrambi pubblicato documentazione sulla migrazione, e un fornitore maturo avrà già effettuato il passaggio. Fai a ogni fornitore della tua lista la stessa domanda e conserva le risposte.

Passo 2: decidi se ti serve un'estensione

Google offre un modulo di richiesta di estensione della Content API per le organizzazioni che hanno bisogno di più tempo. Le estensioni approvate proteggono un progetto dalle risposte di errore pianificate per il periodo approvato e non vanno oltre la disattivazione definitiva all'inizio del 2027. Google non specifica chi ne abbia diritto.

Usa questa regola decisionale. Se ogni chiamante può essere migrato e testato entro poche settimane, salta l'estensione e dedica il tempo alla migrazione. Se un chiamante appartiene a un fornitore con una migrazione confermata ma non ancora pianificata, richiedi un'estensione solo per quel progetto. Un'estensione è un margine di sicurezza, non un piano.

Passo 3: mappa ogni chiamata sul suo equivalente nella Merchant API

La Merchant API suddivide il vecchio monolite in sub-API e versiona l'URL (/products/v1/). La versione v1 ha raggiunto la disponibilità generale a luglio 2025 e la v1beta è stata dismessa il 28 febbraio 2026, quindi sviluppa sulla v1 e ignora i tutorial sulla v1beta che dovessi trovare (note di rilascio della Merchant API).

Content APIMerchant APICosa cambia
products.insertproductInputs.insertRichiede un parametro di query dataSource
products.updateproductInputs.patchAggiornamento persistente di un singolo input di prodotto
products.deleteproductInputs.deleteRichiede un parametro dataSource
products.get / listproducts.get / listRestituisce il prodotto elaborato, in sola lettura
productstatuses.get / listproducts.get / listLo stato ora fa parte della risorsa Product
custombatchChiamate asincrone paralleleNon esiste alcun metodo customBatch
datafeedsdataSourcesOgni fonte dati è associata a una sola feed label e una sola lingua

Fonte: la mappatura della migrazione dei prodotti e la mappatura delle fonti dati di Google. Il cambiamento concettuale è la separazione tra un ProductInput, cioè i dati grezzi che scrivi, e un Product, cioè il risultato elaborato che puoi solo leggere. Un prodotto elaborato viene costruito da un input primario più eventuali input supplementari, dopo l'esecuzione delle regole del feed (panoramica dei prodotti).

Passo 4: crea la fonte dati API prima di inserire qualsiasi cosa

È il passaggio che fa fallire la maggior parte delle prime migrazioni. La Content API creava automaticamente una fonte dati "Content API" al primo inserimento. La Merchant API no. Google specifica che devi creare almeno una fonte dati di tipo API e che la sub-API Products può scrivere solo su fonti dati di quel tipo (migrazione delle fonti dati).

Ogni fonte dati ora corrisponde a una singola combinazione di feedLabel e contentLanguage. Se servivi la Turchia in turco e gli Emirati Arabi Uniti in inglese da un unico feed multi-target, ora ti servono fonti dati separate. Creale tramite la sub-API Data Sources o in Merchant Center, poi usa il nome di risorsa risultante, nel formato accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}, in ogni scrittura.

Passo 5: riscrivi il payload, con un esempio pratico

Tre modifiche ai campi causano la maggior parte dei bug. Il prezzo passa da una stringa decimale a micros interi, dove un milione di micros equivale a un'unità di valuta. Gli attributi di prodotto si spostano in un oggetto productAttributes. E targetCountry viene sostituito da feedLabel, mentre channel scompare.

Il vecchio identificativo di prodotto era così, mentre quello nuovo usa le tilde ed elimina il canale:

Content API:  online:en:US:SKU12345
Merchant API: en~US~SKU12345

Un input di prodotto usato come esempio nella guida di Google è il seguente (inseriscilo con POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}):

{
  "offerId": "SKU12345",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "title": "Classic Cotton T-Shirt",
    "link": "https://www.example.com/p/SKU12345",
    "imageLink": "https://www.example.com/img/SKU12345.jpg",
    "availability": "IN_STOCK",
    "price": { "amountMicros": "15990000", "currencyCode": "USD" },
    "condition": "NEW",
    "gtins": ["9780007350896"]
  }
}

Confrontalo con la vecchia struttura: "price": {"value": "15.99", "currency": "USD"} diventa amountMicros e currencyCode, e la disponibilità diventa un enum, quindi in stock diventa IN_STOCK. Fonte: la guida di Google per aggiungere e gestire i prodotti.

Per la lira turca, 1.249,90 TRY corrisponde a "amountMicros": "1249900000". Calcola i micros con aritmetica intera sull'unità minore, non moltiplicando un float, altrimenti invierai 1249899999 e ti chiederai perché i prezzi differiscono di un soffio.

Usa anche il nuovo campo versionNumber quando più job scrivono lo stesso prodotto. Impedisce che un aggiornamento più vecchio sovrascriva uno più recente quando le richieste arrivano fuori ordine.

Passo 6: sostituisci il batching e leggi lo stato dal prodotto

Non esiste customBatch. Sostituiscilo con richieste asincrone parallele e limita la concorrenza, poi riprova solo quelle fallite. Mantieni un log dei risultati per ogni offerta, così un errore parziale non si trasforma silenziosamente in un catalogo obsoleto.

Per lo stato, smetti di chiamare productstatuses. Leggi invece il Product elaborato, che contiene il proprio stato. Google segnala che può esserci un ritardo di alcuni minuti tra un inserimento o un aggiornamento e la disponibilità del prodotto finale, quindi una lettura subito dopo una scrittura non è un test di errore.

Passo 7: verifica prima di disattivare il vecchio percorso

Esegui prima il nuovo percorso su una porzione piccola e a basso rischio, ad esempio 50 prodotti in una feed label. Poi valuta il passaggio con questa checklist. Ogni voce deve avere risposta affermativa prima di dismettere il vecchio chiamante.

  • Il chiamante si autentica con il progetto che hai registrato e non restituisce alcun 410 per sette giorni consecutivi.
  • Esiste una fonte dati API per ogni coppia di feed label e lingua che servi.
  • Per la porzione di test, il prodotto elaborato corrisponde alla tua fonte di verità per prezzo, disponibilità e link.
  • Nient'altro scrive ancora gli stessi ID offerta dalla vecchia fonte dati.
  • Le offerte fallite vengono registrate con un nuovo tentativo, non scartate.
  • Tutti i chiamanti gestiti da fornitori presenti nel tuo registro hanno una conferma scritta della migrazione.

Il quarto punto merita attenzione. Un secondo scrittore per lo stesso ID offerta, ad esempio il vecchio chiamante e una nuova fonte dati API, è il modo in cui si ottengono valori in conflitto. Decidi quale fonte è responsabile di ogni prodotto e rimuovi l'altra.

Dove questa guida non arriva

Abbiamo scritto questa guida basandoci sulla documentazione pubblicata da Google e non abbiamo migrato il tuo codice. Diversi aspetti restano fuori. Google non specifica i requisiti per le estensioni, quindi non possiamo dirti se un determinato progetto verrà approvato. La panoramica dei prodotti non documenta tempistiche oltre ad "alcuni minuti", quindi qualsiasi aspettativa di latenza più stringente va misurata da te. Inventario locale, inventario regionale, promozioni e recensioni hanno ciascuno le proprie sotto-risorse nella Merchant API, e qui non ne abbiamo trattato le mappature.

Se non vuoi farti carico di un'integrazione API, una piattaforma di feed gestita è una risposta migliore di una riscrittura. Productsup e Feedonomics pubblicano entrambi indicazioni sulla migrazione alla Merchant API e, per un team enterprise con modelli di dati particolari, entrambi potrebbero adattarsi meglio della nostra soluzione. Per Google Shopping in particolare, la nostra configurazione è descritta nella pagina dell'integrazione con Google Merchant Center.

Domande frequenti

La Content API for Shopping funziona ancora?

Non in modo affidabile. Google dichiara che è stata dismessa il 18 agosto 2026, che dal 1° settembre 2026 le richieste senza un'estensione attiva hanno iniziato a fallire a intermittenza con HTTP 410 e che tutti gli endpoint verranno disattivati all'inizio del 2027.

Cosa dice l'errore 410 della Content API?

Il messaggio inizia con "Content API for Shopping was sunset on August 18, 2026". La risposta include l'ID e il numero del tuo progetto GCP e un link al centro assistenza, che ti indicano quale progetto migrare o estendere.

Posso ottenere più tempo con un'estensione?

Google mette a disposizione un modulo di richiesta di estensione della Content API. Le estensioni approvate proteggono il tuo progetto dagli errori pianificati solo per il periodo approvato e non vanno oltre la disattivazione di inizio 2027.

Perché productInputs.insert richiede un dataSource?

Nella Merchant API le scritture appartengono a una fonte dati esplicita. A differenza della vecchia API, non crea una fonte dati "Content API" al primo inserimento, quindi devi creare una fonte dati di tipo API e passarne il nome di risorsa.

Come invio i prezzi nella Merchant API?

Usa amountMicros come stringa intera e currencyCode in formato ISO 4217. Un milione di micros equivale a un'unità di valuta, quindi 15,99 USD corrisponde a 15990000.

La Merchant API supporta il batching?

Non esiste un metodo customBatch. Le indicazioni di Google sono di usare chiamate asincrone parallele, il che significa che dovresti aggiungere un tuo limite di concorrenza e nuovi tentativi per ogni offerta.

Che fine ha fatto productstatuses?

Lo stato ora fa parte della risorsa Product elaborata. Usa products.get o products.list per leggerlo, ricordando che l'elaborazione può essere in ritardo di alcuni minuti rispetto all'inserimento.

Su quale versione della Merchant API dovrei sviluppare?

Sviluppa sulla v1, che ha raggiunto la disponibilità generale a luglio 2025. La versione v1beta è stata dismessa il 28 febbraio 2026, quindi i tutorial scritti per essa non funzioneranno.

Controlla cosa vede davvero Google

Dopo la migrazione, il controllo più rapido è confrontare il tuo feed di origine con ciò che Merchant Center ha elaborato. Analizza il tuo feed live con il nostro strumento gratuito di audit del feed di prodotto per ottenere un punteggio di completezza e qualità, e correggi tutto ciò che segnala prima del prossimo ciclo pubblicitario.

Vuoi un secondo parere sul tuo feed? Lo analizziamo insieme a te e ti mostriamo le lacune prima del prossimo invio.
Richiedi un audit gratuito
Cagdas Polat
Scritto da
Cagdas Polat

Co-founder di Feedance, dove mette a frutto il suo background di ingegnere informatico e marketer per ricavare insight analitici. Con una forte attenzione alla trasformazione dei dati in strategie concrete, si dedica ad aiutare i brand a ottenere una crescita significativa nel panorama digitale.

LinkedIn

Scopri quali
prodotti rendono.

Collega il tuo feed e GA4. Mostriamo Product Score, 4T, Price War e Broken Size sul tuo catalogo.