Global Catalog REST è stato interrotto, il Token offline scade forzatamente l'anno prossimo
Global Catalog REST è stato interrotto, il Token offline scade forzatamente l’anno prossimo
A partire dal 2 novembre, l’API Global Catalog REST non servirà più alcun traffico. Tutte le richieste a discover.shopifyapps.com/global/... falliranno direttamente, inclusa la consultazione dei cataloghi salvati. Quando è stata deprecata ad aprile, l’azienda ha fornito un sostituto, il Global Catalog MCP, e il periodo di sei mesi è scaduto.
Dall’altra parte, l’anno prossimo. Il 27 ottobre, Shopify ha fissato la scadenza per l’applicazione del Token offline: il 1 gennaio 2027, le app pubbliche non migrate verranno rimosse, e a partire dal 1 aprile, i vecchi Token restituiranno HTTP 403. Entrambi i casi richiedono modifiche al codice, uno è urgente oggi, l’altro ha ancora due mesi, non sottovalutarlo.
L’interfaccia che è stata interrotta ieri
L’API Global Catalog REST è stata contrassegnata come deprecata ad aprile 2026, il sostituto Global Catalog MCP implementa il Protocollo di Commercio Universale (UCP). Dopo il 2 novembre, quattro endpoint smetteranno di funzionare:
GET /global/v2/searchGET /global/v2/p/{upid}GET /global/v2/p/by-variant/{vid}POST /global/v2/lookup
Le app che aggregano dati tra negozi sono le più colpite. Ad esempio, un team che confronta i prezzi dei prodotti per animali domestici ha salvato duecento articoli da monitorare nel proprio strumento di selezione, utilizzando ogni notte /global/v2/lookup per estrarre i prezzi più recenti e fornire un rapporto di confronto ai propri utenti al mattino. Dopo il 2 novembre, la prima richiesta di questo compito fallirà, il rapporto sarà vuoto e i commercianti si accorgeranno subito che i prezzi non si muovono più. Funzionalità come il confronto dei prezzi, la ricerca su tutto il web e la ricerca di prodotti tra negozi, che dipendono da questo endpoint del catalogo, perderanno la loro fonte di dati nello stesso giorno.
Anche i cataloghi salvati non funzioneranno. Dopo l’interruzione del servizio, non è chiaro se ci sarà un buffer o se gli indirizzi obsoleti verranno reindirizzati; l’azienda non ha specificato, il changelog riporta solo che smette di servire traffico. Ho trattato come se non ci fosse un buffer, i compiti programmati stanno ancora colpendo questo dominio, e ora dovrebbero ricevere un allerta.
Cambiamenti
Il punto centrale è sostituire le quattro chiamate REST con tre strumenti UCP, inviandoli a https://catalog.shopify.com/api/ucp/mcp:
- Ricerca →
search_catalog, supporta filtri, paginazione, contesto dell’acquirente - Prodotto e variante →
get_product, identificatore passato comegid://shopify/p/{upid}ogid://shopify/ProductVariant/{id} - Elaborazione in blocco →
lookup_catalog, massimo 50 alla volta
Due dettagli facili da trascurare: ogni richiesta deve includere meta.ucp-agent.profile, il valore è l’URL del profilo dell’agente; per consultare i cataloghi salvati, inviare catalog.catalog_id, non concatenare più l’URL del vecchio endpoint.
Il metodo di autenticazione rimane invariato, si utilizza ancora il client credentials del Dev Dashboard per ottenere il bearer token.
Se vuoi provare prima di modificare, utilizza UCP CLI per eseguire ucp catalog search, il CLI è disponibile su github.com/Shopify/ucp-cli. Non ho ancora provato la forma di errore di UCP nel traffico reale, quindi non posso garantire, è meglio eseguire prima nel ambiente di test prima di passare alla produzione.
changelog: https://shopify.dev/changelog/posts/global-catalog-rest-api-stops-serving-traffic-on-november-2-2026
Le tre date del Token, solo il 1 gennaio è quella che devi affrontare
Questa questione è stata preparata dall’inizio dell’anno: a partire dal 1 aprile 2026, le nuove app pubbliche hanno già il token in scadenza obbligatorio, il 20 maggio il changelog ha esteso l’ambito a tutte le app pubbliche. All’epoca era stata fornita solo la data del 1 gennaio, il 27 ottobre l’azienda ha completato la scadenza:
- 1 gennaio 2027: le app non migrate verranno rimosse dall’App Store e non sarà possibile installarle di nuovo, le installazioni esistenti continueranno a funzionare.
- 15 gennaio 2027: i commercianti vedranno un avviso nell’amministrazione di Shopify.
- 1 aprile 2027: le richieste API Admin con token offline non scaduti restituiranno HTTP 403.
La posizione ufficiale è molto chiara: il 1 gennaio è la scadenza per la migrazione, le altre due date sono un buffer per i commercianti, non un’estensione per te. Il codice deve essere modificato entro il 31 dicembre.
Perché questa scadenza così rigida? La ragione ufficiale è il raggio di esposizione. Un token non scaduto, se esposto, è permanentemente valido, senza limiti di finestra di attacco; il token in scadenza scade dopo 60 minuti e viene ruotato automaticamente, riducendo l’impatto a un’ora. È importante chiarire l’ambito: le app pubbliche che chiamano l’API Admin sono quelle colpite, le app personalizzate, le app create dai commercianti e i token di accesso online non sono inclusi. Molti team hanno creato app pubbliche per strumenti interni, questa parte è la più facile da trascurare e vale la pena controllarla prima di procedere.
La migrazione è più semplice del previsto. I commercianti non devono reinstallare, basta scambiare il token esistente nel codice; i modelli ufficiali e le librerie API hanno già implementato il refresh, l’unica cosa che devi fare è lo scambio del token e l’aggiornamento della memorizzazione. Guida: https://shopify.dev/docs/apps/build/authentication-authorization/migrate-to-expiring-offline-access-tokens
Alla fine di ottobre c’è anche una rete di sicurezza utile: accesso con credenziali client. In passato, se il token di refresh veniva perso, si doveva aspettare che il commerciante riaprisse l’app, ora il backend può utilizzare la chiave privata dell’app per firmare e ottenere direttamente un nuovo token di accesso. Per le vecchie app installate in migliaia di negozi, questa rete di sicurezza vale il costo della migrazione.
Facile
Lo stesso annuncio ha fornito due interruttori a basso costo: la sezione [network_access] è stata aggiunta a shopify.app.toml, dichiarando i server e i siti a cui l’app può accedere; il Dev Dashboard supporta l’IP allowlist. Esegui un controllo di sicurezza dell’app shopify app security check prima della pubblicazione.
Programmazione
Non c’è un programma per chi sta ancora utilizzando REST, l’interfaccia è già morta, oggi è il giorno della migrazione. Per chi utilizza token non scaduti, pianifica la migrazione nel Q4, non aspettare fino a gennaio quando i commercianti iniziano a vedere avvisi e i ticket di supporto arrivano.