Catalogue Shopify Storefront et devis de livraison

Ce guide relie l’API GraphQL Shopify Storefront à Answers. Il couvre les réglages Shopify et WordPress. Commencez avec une boutique de test et un profil de conversation non destiné à la production.

Choisir la bonne connexion​

Connexion	Emplacement de configuration	Fonction
Catalogue UCP Shopify, dont le préréglage shopify-storefront-catalog	Configuration guidée d’Answers / outils MCP approuvés	Opérations de catalogue vérifiées exposées par le service MCP distant
Adaptateur Shopify Storefront typé	Profil de conversation → Tools → External REST read tools	Recherches GraphQL Storefront fixes, lecture exacte d’un produit et capacités de la boutique
Consentement au devis de livraison	Réglage de devis distinct de l’adaptateur typé	Préparer un formulaire visible ; créer un panier de devis seulement après confirmation du visiteur

Le nom du préréglage UCP ne signifie pas qu’il active l’adaptateur typé. Ajouter une connexion MCP n’ajoute pas automatiquement les lectures de stock, les droits de panier ou les estimations de livraison. L’adaptateur typé envoie une requête GraphQL définie dans le code par HTTPS POST ; l’assistant ne peut ni fournir du GraphQL arbitraire ni changer de marchand.

Pour la connexion UCP guidée et les liens vers les fiches WordPress, consultez Configuration d’Answers. Si les deux connexions restent actives, décrivez leurs fonctions distinctement afin que les demandes de stock et de devis utilisent les outils Storefront typés. Évitez deux outils de recherche de catalogue impossibles à distinguer.

1. Préparer la boutique Shopify​

Confirmez le domaine d’origine your-store.myshopify.com dans les réglages de domaine Shopify. Le connecteur exige ce nom d’hôte exact, pas le domaine personnalisé de la boutique, une URL d’administration ou une URL de produit.

Préparez des produits représentatifs : produits publiés, variantes nommées, prix du marché visé, suivi du stock lorsque pertinent et article volontairement indisponible. Rendez-les disponibles sur le canal de vente de la storefront/app concernée. Leur disponibilité sur Online Store ne prouve pas leur disponibilité sur un autre canal. Shopify décrit la publication par canal et les autorisations dans Gérer le canal Headless.

Choisissez l’un des modes de provisionnement ci-dessous. Une connexion n’exige pas les deux apps.

Option A : Canal Headless de Shopify​

1. Avec les droits d’administration des apps et canaux, installez le canal de vente Headless de Shopify.
2. Ouvrez le canal et créez une storefront pour cette intégration.
3. Ouvrez Storefront API permissions → Edit dans cette storefront, approuvez les accès nécessaires indiqués ci-dessous et enregistrez.
4. Faites provisionner le jeton Storefront approprié de façon sécurisée dans le backend. L’éditeur AI Kit actuel utilise le type de jeton Storefront public, mais conserve sa valeur côté serveur. Ne collez aucun jeton dans le profil de conversation.

Shopify fournit des jetons publics et privés dans ce parcours. Leurs en-têtes d’authentification diffèrent ; un jeton privé ne peut pas remplacer un jeton public dans le champ prévu pour ce dernier. Consultez Premiers pas avec l’API Storefront.

Option B : Une app gérée par un développeur​

1. Dans Dev Dashboard → Apps, créez une app et configurez une version avec les autorisations Storefront requises.
2. Publiez la configuration de l’app, sélectionnez Install app sur sa carte Installs et approuvez l’installation sur la boutique prévue.
3. L’opérateur de l’intégration doit authentifier l’app avec le parcours d’installation et d’authentification pris en charge par Shopify. Le mode client-credentials vise les boutiques éligibles de la propre organisation de l’app ; il ne remplace pas généralement l’installation OAuth d’un autre marchand.
4. Pendant le provisionnement, utilisez l’Admin API authentifiée pour créer un jeton d’accès Storefront et vérifier ses droits. Stockez uniquement ce jeton Storefront dans le paramètre d’exécution du connecteur. Un jeton Admin API, un client secret et un jeton Storefront sont des identifiants différents.
5. Après une modification des droits, publiez la configuration mise à jour et demandez au marchand d’approuver le nouvel accès. Vérifiez les droits réellement accordés à l’installation et l’accès du jeton d’exécution ; modifier le brouillon de configuration de l’app ne suffit pas.

Suivez le guide des apps Dev Dashboard de Shopify pour l’installation et l’approbation. L’opération de provisionnement est décrite dans storefrontAccessTokenCreate. AI Kit n’effectue pas ces opérations administratives à votre place. Ne remplacez pas le parcours Shopify actuel par un ancien tutoriel de création d’app privée.

Autorisations requises​

Autorisation Storefront	Nécessaire pour
unauthenticated_read_product_listings	Produits, collections et variantes utilisés par les lectures du catalogue
unauthenticated_read_product_inventory	Quantité de variante renvoyée, utilisée dans les conditions de quantité
unauthenticated_read_product_tags	Étiquettes de produit renvoyées et vérifiées par l’adaptateur
unauthenticated_read_checkouts	Lectures facultatives du panier de devis
unauthenticated_write_checkouts	Création facultative et expressément confirmée du panier de devis

Les trois premières concernent le catalogue. N’ajoutez les deux dernières que si le propriétaire active explicitement les devis de livraison. Les droits Shopify dont le nom contient checkout couvrent la Cart API et sont plus larges que l’usage limité de cette intégration ; ils ne sont pas réservés aux devis. L’intégration ne commande pas et ne paie pas. Comparez les droits installés à la référence des autorisations Storefront de Shopify.

2. Préparer les filtres et les données sources​

Installez ou ouvrez Search & Discovery de Shopify et configurez les filtres storefront souhaités. Disponibilité et prix sont des filtres par défaut ; fournisseur, type de produit, étiquettes et options de variante nécessitent les réglages correspondants. Utilisez les vrais noms et valeurs d’options, par exemple Color et Ice, sans déduire une couleur de la photo du produit. Consultez le guide de configuration des filtres de Shopify.

L’adaptateur transmet à Shopify les filtres pris en charge de prix, disponibilité, fournisseur, type de produit, étiquette et option de variante. Le backend vérifie aussi les faits renvoyés : les conditions combinées de prix, disponibilité, option et quantité doivent s’appliquer à la même variante. Une variante bon marché et une autre bien approvisionnée ne doivent pas former une offre fictive.

Le ProductFilter de Shopify Storefront ne fournit pas de condition de quantité minimale en stock. Le backend vérifie donc minQuantity de manière déterministe à partir du stock de variantes renvoyé, sans demander au modèle de filtrer une page. Ne supposez pas que la syntaxe de recherche de l’Admin API est prise en charge par Storefront.

Le champ nullable quantityAvailable décrit la quantité vendable d’une variante sur les canaux en ligne, pas une garantie de stock par entrepôt. Une quantité inconnue n’est pas zéro ; « disponible à la vente » n’est ni une quantité exacte ni une promesse de livraison. Pour les conditions de note, l’adaptateur lit le métachamp pris en charge reviews.rating lorsqu’il est disponible. Une note absente ou inaccessible reste inconnue ; configurer un filtre ne crée pas de données produit.

Pages logiques complètes avec Deployment Access v1.0.130​

Avec le modèle Deployment Access v1.0.129, la validation du backend s’applique à une page du fournisseur. Des conditions locales peuvent laisser moins de résultats visibles que la taille demandée, alors que Shopify dispose encore de pages sources. Une page vide après filtrage ne prouve pas l’absence de résultats dans tout le catalogue.

À partir du modèle Deployment Access v1.0.130, l’adaptateur construit une page logique de correspondances vérifiées dans le code du backend. Il conserve tous les filtres aux lectures suivantes, remplit la taille approuvée et cherche une correspondance vérifiée supplémentaire avant d’annoncer d’autres résultats. La continuation reprend après le dernier produit affiché ; les résultats supplémentaires déjà récupérés ne sont donc pas ignorés silencieusement. Une dernière page plus courte n’est valide qu’après épuisement de la recherche restante chez le fournisseur.

Les recherches par mots-clés utilisent le classement par pertinence de Shopify ; la navigation sans mot-clé utilise le classement par prix. Chaque continuation reste liée à la recherche et au classement d’origine. La navigation suivant/précédent ne demande pas au modèle de relancer la recherche ni de filtrer les cartes. La taille de page est celle du modèle d’affichage approuvé, pas un nombre total de résultats. L’assistant doit préserver les termes demandés par le visiteur ; un mot-clé supplémentaire inattendu peut restreindre les résultats, même lorsque la pagination fonctionne correctement.

Ce traitement est borné, pas un parcours illimité du catalogue : au maximum huit requêtes fournisseur, un délai partagé de 15 secondes (ou l’échéance antérieure de l’opération parente) et des limites de taille cumulée des réponses. Si ces limites, un stock nécessaire inconnu, une couverture incomplète des variantes ou le plafond de recherche Shopify empêchent un résultat fiable, l’opération signale une recherche incomplète, pas « aucun résultat ». Affinez la recherche ou corrigez les données manquantes avant de réessayer. Shopify limite lui-même une recherche à 1 000 résultats ; cela ne prouve pas qu’un catalogue plus grand s’arrête là. Le nombre affiché n’est pas automatiquement le total des correspondances du catalogue.

Si le visiteur ne demande pas de restriction de disponibilité, l’adaptateur combine les partitions de recherche des produits disponibles et indisponibles, sans ajouter à sa place un filtre de possibilité de commande. Un stock minimum explicite reste une condition typée distincte ; un badge « Available to order » ne suffit pas à la satisfaire.

3. Préparer la référence du backend​

Demandez à l’opérateur du backend de provisionner le jeton Storefront de manière sécurisée dans un paramètre d’exécution chiffré appartenant à l’app, et d’autoriser l’environnement déployé à y accéder. Le profil accepte son nom, par exemple /APPNAME/external-tools/storefront-token, et non son contenu. APPNAME doit être le préfixe réel de l’application déployée. Un paramètre non chiffré est rejeté.

Ne placez jamais de valeur de jeton dans le JSON du profil, des en-têtes fixes, des fichiers versionnés, captures, tickets de support ou chats. Le navigateur et le modèle n’en ont pas besoin. La rotation relève de la procédure de gestion des secrets de l’opérateur ; vérifiez ensuite une lecture via le déploiement prévu sans afficher le jeton.

L’éditeur WordPress Storefront actuel impose l’authentification par X-Shopify-Storefront-Access-Token. Le backend prend aussi en charge Shopify-Storefront-Private-Token, mais cet éditeur ne propose pas de sélecteur de type de jeton. Ne collez pas de jeton privé dans la configuration publique. Une intégration privée gérée par l’opérateur exige également une IP visiteur fiable issue du contexte de requête du backend ; une IP fictive ou un argument d’outil fourni par le navigateur ne convient pas. Shopify explique les en-têtes distincts dans sa référence d’authentification Storefront.

4. Ajouter les outils typés dans WordPress​

Ouvrez SmartCloud → Answers → paramètres détaillés → Conversation profile → Tools. Dans External REST read tools, ajoutez un outil et choisissez Shopify Storefront (read only) comme adaptateur. Répétez pour chaque opération nécessaire :

Exemple d’ID d’outil	Storefront read operation	Fonction suggérée
shopify-products	Search products	Rechercher avec des conditions prises en charge de prix, disponibilité, quantité et options
shopify-product	Get one product	Lire un ID produit Shopify exact précédemment vérifié et ses variantes renvoyées
shopify-capabilities	Read shop capabilities	Lire les capacités générales de la boutique sans promettre une éligibilité au checkout

Ces IDs sont des exemples, pas des noms imposés. Utilisez des IDs distincts et des fonctions claires. Des opérations différentes peuvent partager le même endpoint marchand ; ne dupliquez pas la même opération sur cet endpoint.

Pour chaque outil :

1. Saisissez le Shopify shop domain d’origine et sélectionnez l’opération.
2. Saisissez le Storefront token SSM parameter name fourni par l’opérateur.
3. Vérifiez le Derived Storefront endpoint, en lecture seule : https://your-store.myshopify.com/api/2026-10/graphql.json. L’adaptateur fixe l’API à 2026-10 ; ce champ ne permet pas de modifier librement l’endpoint ou la version de l’API.
4. Dans Market and language, choisissez éventuellement le code pays et une langue publiée dans Shopify. À vide, les valeurs par défaut de la boutique s’appliquent. Une langue ne convertit pas la devise ; prix et devises renvoyés restent des faits sources. Gardez des réglages cohérents de marché et d’identifiants entre les trois outils.
5. Laissez Offer separately confirmed shipping quotes désactivé jusqu’à la vérification du consentement et des droits décrite ci-dessous.
6. Activez les outils vérifiés et choisissez Save profile. Ouvrir ou modifier un outil ne change que le brouillon. Configurez la mission de l’assistant pour utiliser ces outils pour les faits actuels, sans traiter les textes produits de la base de connaissances comme un stock en temps réel.

Aucun corps GraphQL personnalisé, mappage libre de paramètres de requête ou schéma de réponse généré par le modèle n’est nécessaire. L’adaptateur typé fournit son contrat d’entrée et de sortie approuvé.

5. Configurer les cartes vérifiées et les libellés​

Dans Display templates, activez les affichages structurés et ajoutez un modèle lié à la source de lecture Storefront approuvée. Choisissez disposition et taille de page. Vérifiez les mappages de titre, description, image, prix, quantité et navigation à l’aide d’un exemple vérifié issu de cette source. Les arguments d’aperçu sont les entrées d’une véritable lecture approuvée, pas un emplacement pour coller une réponse produit inventée. Utilisez une recherche connue ou un ID produit vérifié selon l’opération de la source sélectionnée.

Appliquez le modèle au brouillon, puis enregistrez le profil de conversation. Le backend construit les cartes à partir d’enregistrements vérifiés. L’assistant peut fournir une courte introduction ou comparaison étayée, mais ne doit pas régénérer ni modifier les prix, devises, stocks, IDs ou faits de variante dans les cartes.

Configurez les libellés des cartes et de pagination dans le catalogue de traduction partagé. Ils suivent la langue de l’interface du chatbot/du site ; la réponse peut suivre celle de la question. En l’absence de traduction, le libellé source rédigé est conservé. Aucun passage du modèle ne traduit tous les champs, noms de produit ou enregistrements sauvegardés.

Les formats explicites HTML/Markdown des contenus WordPress structurés répliqués constituent une fonction distincte, pas une permission d’afficher du HTML Shopify arbitraire. Après vérification des mappages de format et synchronisation complète, le HTML déclaré devient par défaut du texte brut lisible. Un modèle de contenu structuré peut activer séparément Allow safe rich-text formatting, qui requiert une display-policy version 4 et un format wire version 3 compatibles. Ce formatage restreint n’active ni HTML brut, ni liens, ni images dans une propriété textuelle. Les champs simples ou non marqués restent du texte brut.

6. Activer les estimations de livraison confirmées séparément​

Avant activation, approuvez les deux droits de panier, vérifiez la configuration de livraison du marchand et relisez l’avis de confidentialité du site. Expliquez que les coordonnées de livraison sont transmises au marchand configuré et passent par un traitement privé du backend, et que Shopify peut conserver le panier selon les politiques du marchand. Ne prétendez pas qu’il est automatiquement supprimé à la fermeture du chat.

Activez Offer separately confirmed shipping quotes sur les outils de catalogue dont les variantes peuvent servir aux devis, notamment Search products et Get one product. Enregistrez le profil. Ce réglage n’installe pas d’app et n’accorde aucun droit Shopify. L’activer seulement sur une lecture de capacités ne fournit pas de variantes produit.

Le parcours prévu est le suivant :

1. Le visiteur demande un devis pour un produit, une variante exacte et une quantité.
2. L’assistant lit les données actuelles et identifie la variante. En cas d’ambiguïté, il demande une précision plutôt que de deviner.
3. Le formulaire Check shipping quote montre les articles vérifiés et demande les coordonnées de livraison. Sa préparation ne crée pas de panier et ne calcule aucun frais.
4. Seul l’envoi explicite du formulaire autorise la création du panier temporaire et la consultation des tarifs. Aucune option n’est choisie, aucune commande n’est passée et aucun paiement n’a lieu.
5. Le résultat présente les estimations reçues, un état en attente/indisponible ou un échec. Une estimation en attente pour un panier connu peut être actualisée sans créer un autre panier. Si l’issue de la création est incertaine, le backend ne répète pas cette mutation à l’aveugle.

Utilisez le formulaire, pas le chat ordinaire, pour les coordonnées de livraison. Les valeurs structurées n’entrent ni dans les prompts du modèle, ni dans l’historique visible, ni dans le stockage des conversations du navigateur. Les références privées du panier restent côté serveur. Les propositions expirent et sont liées à la conversation et au profil vérifié ; lancez une nouvelle demande après expiration ou modification du profil.

Les estimations Shopify dépendent du panier et de la destination concrets. Cette intégration ne promet pas de date d’arrivée et ne détermine pas les moyens de paiement utilisables dans un checkout particulier. Les marques de carte et portefeuilles généralement acceptés ne prouvent pas leur disponibilité pour un achat précis. Les options et montants peuvent changer au checkout ; n’ajoutez pas l’estimation d’une option au total affiché du panier pour en faire un montant final à payer. Consultez la Cart API et la création de panier de Shopify.

7. Vérifier l’expérience complète​

Testez avec vos propres enregistrements Shopify connus, pas avec un stock supposé :

• Recherchez un produit connu, puis lisez sa variante exacte. Comparez titre, option, montant, devise et quantité avec le même marché/canal dans Shopify.
• Combinez plafond de prix, quantité minimale et option de variante. Une seule variante doit tout satisfaire ; testez aussi un produit dont des variantes différentes satisfont chacune des conditions individuelles différentes.
• Vérifiez la navigation suivant/précédent, les correspondances dispersées, un produit réellement absent et les résultats explicitement incomplets dans le modèle Deployment Access v1.0.130. Incluez des recherches par mots-clés combinant disponibilité et quantité minimale. Ne déduisez jamais d’une page une absence dans tout le catalogue et lancez une nouvelle recherche après une mise à jour du backend.
• Demandez un devis de livraison. Le formulaire visible doit précéder toute création de panier, et son abandon ne doit pas en créer. Ne testez l’envoi qu’avec une destination de test délibérément approuvée, puis testez l’actualisation d’un résultat en attente.
• Testez des droits manquants, une quantité inconnue et des destinations non desservies. Ils ne doivent pas devenir du stock inventé, une livraison gratuite ou des garanties.
• Posez une question dans une autre langue sans changer celle du site. Vérifiez séparément la langue de réponse, les libellés traduits par catalogue et les faits produits issus de la source.

La démo peut être testée directement dans WordPress après franchissement de sa protection d’accès. Un frontend statique n’est pas requis. Pour un site exporté séparément, republiez les ressources frontend après mise à jour du plugin ; les réponses sauvegardées et anciens exports ne sont pas réécrits rétroactivement.

Dépannage​

Symptôme	Vérification
L’assistant utilise des données génériques ou dit ne pas pouvoir vérifier la livraison	Vérifiez que les outils typés sont actifs dans le profil enregistré, que leurs fonctions sont distinctes et que le consentement au devis est actif sur la source fournissant la variante vérifiée. UCP seul ne suffit pas. Consultez l’activité des outils ; une réponse du modèle ne prouve pas un appel d’outil.
Un jeton fonctionne ailleurs, mais pas ici	Vérifiez la boutique exacte, le propriétaire/type du paramètre d’exécution, les droits installés et le type de jeton. Les jetons Admin et Storefront privés ne sont pas interchangeables avec le jeton Storefront public configuré par l’UI.
Un produit manque	Vérifiez publication par canal, disponibilité sur le marché, termes et filtres Search & Discovery actifs. Comparez la même source et le même marché, pas seulement la page Online Store.
La quantité disponible est inconnue	Vérifiez le droit de lecture du stock et le champ renvoyé. Un stock absent reste inconnu ; la disponibilité ne prouve pas dix unités en stock.
Deux résultats sur une page de trois alors qu’il reste des pages sources	Cela peut arriver avec la validation par page du modèle Deployment Access v1.0.129. Mettez à jour la pile Deployment Access vers le modèle v1.0.130 ou ultérieur et lancez une nouvelle recherche ; une simple mise à jour du plugin n’active pas le comportement complet des pages logiques du backend.
Next results échoue après une mise à jour	Lancez une nouvelle recherche au lieu de réutiliser une continuation expirée ou issue d’un ancien protocole. Si une nouvelle requête échoue encore, recueillez son ID de corrélation et l’état du backend sans données sensibles ; ne masquez pas un cycle de curseur du fournisseur par un résultat vide.
La recherche est explicitement incomplète	Affinez-la ou corrigez les données nécessaires manquantes. Le parcours borné n’a pas pu établir une page complète ou l’épuisement des résultats ; cela ne signifie pas « aucun résultat ».
Un devis reste en attente ou indisponible	Vérifiez droits de panier, tarifs/destinations du marchand et état du backend sans données sensibles. Actualisez uniquement le panier connu en attente. Ne recréez pas des paniers après une issue incertaine.
Les libellés des cartes et la réponse n’ont pas la même langue	C’est attendu lorsque langue de l’UI et langue de la question diffèrent. Ajoutez les libellés rédigés au catalogue partagé ; sans traduction, le libellé source reste affiché.
La modification semble enregistrée localement, mais l’ancien comportement persiste	Appliquez les brouillons imbriqués, enregistrez le profil, vérifiez backend/site et republiez les ressources statiques si nécessaire. Démarrez une nouvelle conversation de test.

Pour le support, recueillez l’identifiant de déploiement/version, l’ID et l’opération de l’outil, la révision du profil, l’heure, l’ID de corrélation de la requête et une catégorie d’échec sans données sensibles. Ne transmettez ni identifiants secrets, ni IDs privés de panier, ni adresses de livraison dans les journaux ou captures de dépannage.