Shopify Global Catalog : migrer de REST vers MCP avant le 2 novembre

Qui doit agir avant le 2 novembre ?

L’arrêt vise les requêtes vers discover.shopifyapps.com/global/…, y compris celles utilisant des catalogues enregistrés. La cible annoncée est https://catalog.shopify.com/api/ucp/mcp. Cela ne désigne pas l’ensemble des API REST de Shopify ni la disparition de tout transport REST dans UCP. Domaine et endpoints concernés.

La documentation distingue le Global Catalog, pour une découverte entre plusieurs marchands, du Storefront Catalog, limité à une boutique. Choisir l’interface de catalogue. Ce choix change le périmètre commercial : un assistant de marque ne doit pas devenir un comparateur global par accident.

Trois situations appellent trois réponses. Si tu possèdes le connecteur, organise la migration et sa recette. Si tu utilises une app éditée par un tiers, demande-lui une confirmation du périmètre et de sa livraison. Si aucun composant ne dépend de l’ancienne API, conserve cette conclusion documentée : ne lance pas un chantier uniquement parce qu’une échéance existe.

La bonne question à poser à l’éditeur est précise : « Votre service appelle-t-il encore le Global Catalog REST historique, et quelle preuve confirme que notre parcours n’en dépendra plus à la date d’arrêt ? » Une réponse « nous utilisons Shopify » ne permet pas de trancher.

Retrouver la dépendance réelle avant de changer le code

Je recommande un inventaire par fonction : recherche, fiche détaillée, résolution d’identifiants et traitement de lots. Pour chaque fonction, note le propriétaire, le code ou service appelant, l’URL utilisée, le parcours utilisateur et le comportement en cas d’échec. Tu peux ainsi traiter le bon composant sans ouvrir une refonte générale.

Dans un dépôt auquel tu as accès, une recherche en lecture seule de discover.shopifyapps.com constitue un premier signal. Examine aussi les variables de configuration par leur nom, les workers, les tâches planifiées, les SDK et les services distants. Ne copie pas de fichiers d’environnement ou de secrets dans un ticket pour prouver que tu as cherché.

Une recherche sans résultat n’est pas une preuve absolue d’absence : le domaine peut être composé dans le code, fourni par une dépendance ou utilisé dans l’infrastructure d’un tiers. Complète par les traces de destination réellement disponibles et par la confirmation de l’éditeur. Qualifie chaque ligne : dépendance confirmée, absence étayée, propriétaire inconnu ou accès manquant.

Le document d’inventaire proposé contient ces champs : fonction, service, responsable, ancien appel, catalogue enregistré éventuel, données consommées, scénario utilisateur, stratégie d’échec et état de migration. Un lien vers le ticket de recette complète la ligne. Ce document est un outil de coordination, pas un diagnostic déjà exécuté sur ton système.

Si le logiciel est externe et que tu n’as pas accès à son code, ne contourne pas cette limite par une modification du thème Shopify. Obtiens une réponse du responsable de l’intégration et prépare les scénarios que tu peux réellement vérifier depuis ton propre parcours.

Faire correspondre les anciens appels sans conserver l’ancien contrat

Shopify indique aussi de transmettre l’identifiant d’un catalogue enregistré via catalog.catalog_id, plutôt que de reprendre son ancienne URL dédiée. Mapping et catalogues enregistrés.

Mon conseil : crée un adaptateur explicite entre la réponse du service et ton modèle d’affichage. Ne fais pas croire à l’interface que l’ancien objet REST est toujours reçu. Donne à chaque champ consommé une règle : identifiant, variante, prix, devise, disponibilité, vendeur et destination du lien.

La spécification distingue notamment la liste products d’une recherche ou d’un lookup, du produit unique product d’un get_product. Un lookup ne garantit pas l’ordre de retour : les entrées inputs servent à corréler les identifiants résolus. Contrat UCP Lookup. Ne raccorde donc pas la deuxième réponse à la deuxième demande par sa seule position.

Migrer en six étapes

1. Choisir une fonction pilote. Commence par un usage borné, avec un responsable et des critères de réussite. Une recherche produit déjà utilisée par l’interface est plus vérifiable qu’un objectif vague « rendre l’agent compatible MCP ». Décris ce que l’utilisateur doit voir et pouvoir faire, ainsi que ce qui doit se produire lorsque rien n’est trouvé.
2. Préparer le profil UCP. Chaque appel pertinent transmet l’URL HTTPS d’un profil. Shopify négocie les capacités déclarées ; un profil invalide, inaccessible ou incompatible ne débouche pas sur une négociation réussie. Profils et négociation. Pour Global Catalog, la référence demande les capacités de base dev.ucp.shopping.catalog.search et dev.ucp.shopping.catalog.lookup, ainsi que l’extension dev.shopify.catalog.global pour les champs enrichis. Capacités du catalogue global. Vérifie la version réellement supportée ; ne copie pas un profil checkout comme preuve de compatibilité catalogue.
3. Vérifier le mode d’accès. L’annonce de migration dit que les credentials Dev Dashboard peuvent continuer à générer des bearer tokens. L’aperçu actuel des catalogues documente aussi l’accès par profil sans clé API, avec des limites propres. Accès aux catalogues. Le tutoriel d’authentification décrit le flux client credentials et le renouvellement des tokens. Flux d’authentification documenté. Ce sont des parcours à vérifier pour ton client, pas une raison de supprimer aveuglément son authentification. Garde les secrets côté serveur et hors des logs.
4. Adapter le transport et les réponses. Utilise un client MCP approprié et le schéma de ses outils. Le binding UCP présente les résultats métier dans structuredContent et distingue ces résultats des erreurs de protocole. Transport MCP du catalogue. Ton adaptateur doit examiner le résultat réel, ses messages et ses champs, pas seulement le statut HTTP. Prévois un rendu explicite pour une absence de produit ou une sélection impossible.
5. Recetter du résultat au lien marchand. Exécute la grille ci-dessous avec des données autorisées, dans un environnement identifié. Vérifie la variante affichée, la devise et le vendeur jusqu’à la destination du lien. Une carte jolie mais reliée au mauvais produit ne passe pas la recette. Note réussi, échec, bloqué ou non exécuté, sans transformer les cases préparées en tests réalisés.
6. Basculer puis surveiller. Fais accepter les critères par le responsable du service, prépare le mode dégradé et vérifie l’absence de trafic vers l’ancienne API dans les surfaces que tu peux observer. Conserve les limites de couverture : un test du frontend n’inspecte pas un worker oublié. La suppression de l’ancien chemin vient après une preuve suffisante, avec son autorisation propre.

Recevoir le parcours, pas seulement la requête

Exemple fictif : l’acheteur demande un sac bleu d’une taille précise ; aucune variante ne satisfait les deux options. Le protocole prévoit une sélection effective pouvant être assouplie et demande de comparer product.selected à la demande. Sélection et relaxation des options. La bonne interface explique ce qui a changé et laisse l’utilisateur choisir ; elle ne valide pas discrètement un autre article.

Autre exemple fictif : deux identifiants d’entrée se résolvent vers une même variante. Une interface qui s’appuie sur les positions peut afficher une ligne en double ou raccorder le mauvais lien. Écris un test local pour ce cas avec des données synthétiques ; ne simule pas sa réussite par un screenshot de la documentation.

Chaque résultat de recette doit porter un environnement, une version du client, une date, un responsable et une observation. Distingue validation syntaxique du JSON, comportement local de l’adaptateur et appel accepté par le service distant. Aucun de ces niveaux ne remplace à lui seul la vérification du parcours commercial.

Traiter les limites sans les masquer

Dans la référence Global Catalog, total_count est estimé ; le curseur est opaque et la pagination est plafonnée à 1 000 résultats. Certains champs sont marqués Inferred, car générés ou enrichis, parfois absents ou d’exactitude variable. Pagination et champs enrichis. Ne transforme pas une découverte en inventaire exhaustif ni une description enrichie en déclaration certaine du marchand.

La spécification Search rappelle que limit est une taille demandée, pas une garantie de nombre de résultats. Le contexte de l’acheteur sert la pertinence ; il ne remplace pas les données transactionnelles vérifiées au checkout. Contexte et pagination UCP Search.

Shopify interdit de mettre en cache les résultats de recherche et de télécharger les images du Catalog sur un serveur pour les réutiliser ; ces images doivent être affichées en temps réel avec la fiche du marchand concerné. Règles d’usage du catalogue. Le mode dégradé proposé ici n’est donc pas une sauvegarde des anciennes cartes, prix ou photos pour continuer à les présenter comme actuels.

Pour les traces, privilégie des métadonnées minimisées : fonction, durée, catégorie de résultat et version de l’adaptateur. Ne transforme pas ton journal d’incidents en copie persistante du catalogue ou en dépôt de données acheteur. Le guide monitoring Shopify aide à organiser le diagnostic ; toutes ses surfaces ne couvrent pas forcément ce connecteur externe.

Préparer la bascule et le mode dégradé

Proposition de plan : valider une fonction pilote, migrer les autres appels recensés, recetter les parcours concernés, puis couper la dépendance historique avec une décision explicite. Sépare l’activation du nouveau client et la suppression de l’ancien code : ces actions n’ont pas les mêmes risques.

Un retour temporaire à l’ancienne implémentation ne constitue pas un plan durable après son arrêt annoncé. Prépare plutôt un mode dégradé honnête : suspendre la recommandation automatisée concernée, afficher un message clair et orienter vers une recherche ou navigation marchande autorisée. Cela vaut mieux qu’un ancien résultat qui laisse croire à une disponibilité actuelle.

Choisis les indicateurs avant la bascule : erreurs par fonction, requêtes vers le domaine historique dans le périmètre observé, latence, sélections non résolues et abandon du parcours testé. Mesure d’abord une base de comparaison ; aucun seuil universel ou gain de conversion n’est promis. Distingue trafic réel et tests techniques.

La note de bascule proposée tient en une page : propriétaire, périmètre, version, critères acceptés, scénarios bloqués, mode dégradé, contacts internes et date de contrôle suivante. Si une fonction n’a pas été testée, elle reste explicitement non validée ; une date de déploiement ne remplit pas cette case.

La migration sécurise une dépendance technique. Elle ne garantit ni référencement, ni présence dans une réponse IA, ni commande. Pour le modèle général du commerce agentique, consulte le guide UCP, sans confondre ses perspectives avec une recette de ton connecteur.

La décision à prendre maintenant

En tant que marchand, identifie d’abord qui exploite le connecteur : ton équipe, une agence ou l’éditeur d’une app. Demande une réponse écrite sur l’usage de l’ancien Global Catalog et la preuve de migration. Si tu n’es pas concerné, n’ajoute pas d’infrastructure MCP inutile à ta boutique.

En tant que responsable technique, commence par une ligne de l’inventaire et un scénario visible. Tu dois pouvoir relier un ancien appel à son remplacement, expliquer le profil et le mode d’accès retenus, puis montrer un résultat de recette daté. Une bibliothèque mise à jour ou un HTTP 200 isolé ne suffit pas.

Tu veux cadrer les dépendances de tes apps, la fiabilité des données et le parcours Shopify avant de généraliser ? Parlons de ton intégration. Le périmètre de l’audit Shopify permet de définir les vérifications utiles et les responsabilités, sans promettre de migrer un logiciel tiers auquel personne n’a accès.