Intégration Magento : produits, commandes et groupes de clients

Connectez votre boutique Magento (Magento Open Source ou Adobe Commerce 2.4) à Personyze, et gardez Personyze à jour avec elle : vos produits dans le catalogue où puisent les recommandations, vos commandes comme historique d’achats dans le profil de chaque acheteur, et les données Magento de vos clients dans leur profil visiteur.

Ce que cela fait

Trois synchronisations, chacune activée séparément :

• Produits vers votre catalogue. Chaque produit activé et visible dans votre catalogue ou dans la recherche, toutes les 6 heures : nom, description, image principale, prix et prix spécial, marque, catégories, et stock avec le nombre d’unités. Les recommandations, les widgets produits et le ciblage basé sur le catalogue les utilisent immédiatement. Un produit qui quitte votre boutique passe en rupture de stock dans le catalogue.
• Commandes vers l’historique d’achats. Les produits de chaque commande deviennent des achats dans le profil visiteur de l’acheteur, rapprochés par son e-mail — un profil est créé pour un acheteur que Personyze n’a pas encore vu, commandes sans compte comprises — à la date et au montant de la commande elle-même. Le premier passage lit une année de commandes ; ensuite, les nouvelles commandes arrivent toutes les 15 minutes.
• Clients vers les profils visiteurs. Le nom de chaque client, son groupe de clients et sa date d’inscription, dans son profil, rapprochés par e-mail, toutes les heures. Ils apparaissent comme attributs de visiteur que vous pouvez cibler : Magento customer group, Magento customer since et Magento customer ID. Par exemple : affichez des prix professionnels aux visiteurs dont le Magento customer group est Wholesale.

Ce qu’il vous faut

• Magento Open Source ou Adobe Commerce 2.4 (ou Mage-OS).
• Un utilisateur admin Magento autorisé à créer des Integrations (System → Extensions → Integrations).
• Votre boutique sur une adresse https publique. Personyze se connecte à l’API de votre boutique depuis Internet.

Étape 1 : créer l’Integration dans Magento

1. Dans votre admin Magento, allez dans System → Extensions → Integrations → Add New Integration.
2. Donnez-lui un nom (par exemple « Personyze ») et saisissez votre mot de passe administrateur pour confirmer.
3. Ouvrez l’onglet API, réglez Resource Access sur Custom, et cochez :
   • Catalog → Inventory — produits, catégories et stock. Cochez Inventory lui-même, pas seulement Products en dessous : c’est par lui que le stock est lu.
   • Sales → Operations → Orders → Actions → View — les commandes.
   • Customers — les clients et les groupes de clients.
   • Stores → Settings → All Stores — les adresses et la devise de votre boutique.
   • Stores → Attributes → Product — les noms de marque.

   Personyze ne fait que lire ; il ne modifie jamais rien dans votre boutique.

4. Cliquez sur Save. Dans la liste Integrations, cliquez sur Activate à côté de l’Integration, puis sur Allow.
5. Magento affiche quatre valeurs : Consumer Key, Consumer Secret, Access Token et Access Token Secret. Vous saisirez les quatre dans Personyze à l’étape 2 — gardez cette fenêtre ouverte jusque-là, et gardez ces valeurs en lieu sûr.

Étape 2 : la connecter dans Personyze

1. Dans Personyze, allez dans Paramètres → Intégrations et ouvrez Magento (sous Plateforme et développeurs).
2. Saisissez :
   • Adresse de la boutique — l’adresse que visitent les acheteurs, par exemple https://shop.example.com/. Une boutique dans un sous-dossier, comme https://www.example.com/shop/, fonctionne aussi. Pas l’adresse de l’admin.
   • Les quatre valeurs de l’étape 1 : Consumer Key, Consumer Secret, Access Token et Access Token Secret.
3. Cliquez sur Connecter.

Personyze vérifie les quatre valeurs auprès de votre boutique avant de les enregistrer — des valeurs qui ne fonctionnent pas ne sont jamais stockées — et détermine lesquelles des trois synchronisations l’Integration peut lire. Les trois valeurs secrètes sont conservées chiffrées et ne sont plus jamais affichées : dès lors, leurs champs indiquent « (inchangé) ». Le panneau affiche alors Connecté à suivi de votre boutique.

Pour modifier quelque chose plus tard, modifiez les champs et cliquez sur Vérifier et enregistrer. Pour la même boutique et la même Consumer Key, vous pouvez laisser les champs secrets vides pour conserver les valeurs enregistrées.

Personyze signe chaque requête avec les quatre valeurs de l’Integration (OAuth 1.0a), comme Magento l’attend d’une intégration. Vous n’avez pas besoin d’activer « Allow OAuth Access Tokens to be used as standalone Bearer tokens » dans les réglages OAuth de Magento.

Étape 3 : activer ce qui doit être synchronisé

Sous Ce qui est synchronisé, activez chaque synchronisation souhaitée : Produits vers votre catalogue, Commandes vers l’historique d’achats et Clients vers les profils visiteurs. Chaque ligne indique ce dont elle a besoin de l’Integration — Produits, Commandes ou Clients — en vert quand l’Integration peut le lire, et en rouge, avec « Non autorisé pour l’Integration », quand elle ne le peut pas (voir Dépannage).

Une synchronisation que vous activez indique « Démarre dans les 5 minutes ». Après un passage, chaque ligne dit ce qu’elle a fait, par exemple « 7 produits · 1 oct. », « 8 achats depuis le 1 oct. » ou « 3 profils · 1 oct. ». Synchroniser maintenant lance une synchronisation au prochain passage, dans les 5 minutes, sans attendre son calendrier.

Comment les données sont utilisées

Produits

Chaque produit est un élément du catalogue, identifié par son ID produit Magento. Son lien est formé de l’adresse de votre boutique, de la clé d’URL du produit et de votre suffixe d’URL produit (.html sauf si vous l’avez modifié).

• Prix : un prix spécial compte tant que la date du jour se situe entre ses dates de début et de fin, et seulement s’il est inférieur au prix — le prix est alors le prix normal et le prix spécial le prix soldé. Les règles de prix catalogue ne sont pas appliquées aux prix synchronisés.
• Les produits configurables (par exemple un T-shirt décliné en tailles) forment un seul élément du catalogue, avec le prix le plus bas de leurs variantes activées et le stock de leurs variantes additionné. Les variantes elles-mêmes (« Not Visible Individually ») ne sont pas synchronisées comme des produits distincts.
• Stock : un produit est en stock selon ce qu’en dit Magento ; le nombre d’unités n’est conservé que lorsque Magento gère le stock du produit.
• Marque : votre attribut brand ou manufacturer .
• Catégories : les noms des catégories du produit.
• Les produits désactivés, les produits non visibles individuellement et les produits sans clé d’URL ne sont pas synchronisés.
• Jusqu’à 50 000 produits sont synchronisés. Pour une boutique plus grande, les 50 000 premiers sont synchronisés, et la ligne Produits l’indique.

Achats

Les achats d’une commande sont ses produits (un produit configurable compte comme le produit, pas comme sa variante). Les quantités annulées ou remboursées sont exclues, et la remise de chaque ligne est déduite de son montant. Les commandes annulées, les commandes entièrement remboursées (closes) et les commandes sans adresse e-mail n’apportent aucun achat.

Flux de produits

Si votre compte importe aussi un flux de produits, un produit présent dans les deux peut apparaître deux fois dans le catalogue. Gardez une seule source par produit — la ligne Produits vous avertit quand le compte a un flux.

Déconnexion

Cliquez sur l’icône de corbeille à côté de « Connecté à … » dans le panneau. La synchronisation s’arrête ; les produits, achats et profils déjà synchronisés restent. L’Integration reste dans votre admin Magento — supprimez-la là-bas si vous n’en avez plus besoin.

Dépannage

« There is no Magento API at … » (aucune API Magento à cette adresse)

L’adresse n’est pas celle de la boutique elle-même. Saisissez l’adresse que visitent les acheteurs, comme https://shop.example.com/ — pas l’adresse de l’admin.

« Magento did not accept these keys. » (Magento n’a pas accepté ces clés)

Vérifiez que l’Integration est Active dans Magento, et saisissez de nouveau les quatre valeurs depuis les détails de l’Integration. Si vous avez cliqué sur Reauthorize dans Magento, il a émis un nouvel Access Token et un nouvel Access Token Secret — saisissez ceux-là.

« The integration may read nothing Personyze syncs. » (l’Integration ne peut rien lire de ce que Personyze synchronise)

L’Integration n’a aucune des ressources de l’étape 1. Dans Magento, modifiez-la → API, cochez-les, Save, puis Reauthorize et Allow, et saisissez les nouvelles valeurs dans Personyze.

Une ligne de synchronisation est rouge et indique « Non autorisé pour l’Integration »

Dans Magento, modifiez l’Integration → API, cochez la ressource que nomme la ligne (voir l’étape 1), Save, puis Reauthorize et Allow. Saisissez le nouvel Access Token et le nouvel Access Token Secret dans Personyze et cliquez sur Vérifier et enregistrer.

« Personyze cannot connect to … » (Personyze ne peut pas se connecter)

Personyze atteint votre boutique par Internet, en https uniquement. Une boutique sur un réseau privé ou en simple http ne peut pas être connectée.

« The signature is invalid » (la signature n’est pas valide), alors que les quatre valeurs sont correctes

Magento vérifie la signature de chaque requête par rapport à l’adresse à laquelle il pense avoir été appelé. Si votre boutique se trouve derrière un proxy, un répartiteur de charge ou un CDN qui termine le https et transmet du simple http à Magento, il faut indiquer à Magento que la requête était en https — via son en-tête d’offloader, généralement X-Forwarded-Proto: https, défini par le proxy. Une boutique dont les pages sécurisées fonctionnent normalement l’a déjà. À la connexion, cela apparaît sous la forme « Magento did not accept these keys. » ; pendant une synchronisation, ce sont les mots de Magento lui-même — « The signature is invalid » — qui apparaissent dans la raison affichée par le panneau.

« The store redirected to … » (la boutique a redirigé vers une autre adresse)

L’adresse que vous avez saisie renvoie les visiteurs vers une autre (par exemple de example.com à www.example.com). Saisissez l’adresse vers laquelle elle redirige.

Le panneau affiche le refus de Magento au lieu de « Connecté à »

Magento a refusé les clés pendant une synchronisation — l’Integration a été désactivée, supprimée ou réautorisée. Personyze cesse immédiatement d’utiliser la connexion au lieu de réessayer, et le panneau affiche la raison donnée par Magento là où figurait « Connecté à ». Saisissez les quatre valeurs actuelles de l’Integration et cliquez sur Connecter. Une boutique reconnectée conserve ses synchronisations telles qu’elles étaient.

Tous les produits apparaissent en stock, sans nombre d’unités

L’Integration ne peut pas lire le stock : cochez Catalog → Inventory lui-même (étape 1), réautorisez-la, et saisissez les nouvelles valeurs dans Personyze.

Les prix diffèrent de ceux de la vitrine

Les règles de prix catalogue ne sont pas appliquées aux prix synchronisés ; les prix spéciaux, si.

Le pare-feu de la boutique bloque la connexion

Si votre boutique se trouve derrière un pare-feu qui bloque les requêtes automatisées, autorisez les requêtes portant le user agent Personyze/1.0 (+https://www.personyze.com).

Voir aussi

• Intégrations — toutes les autres connexions.
• Intégration Shopify (connexion par API) — les trois mêmes synchronisations pour une boutique Shopify.
• Installer Personyze — le code de suivi dont votre vitrine a besoin.
• Recommandations — par où commencer — les widgets construits sur le catalogue et les achats synchronisés.
• Configurer le flux de produits/contenu — l’autre façon de remplir le catalogue.
• Règles de ciblage — le ciblage sur le groupe de clients Magento.
• Dépannage : une intégration a cessé de se synchroniser