Skip to content

Synchro catalogue PrestaShop ​

Le module Humind pour PrestaShop synchronise votre catalogue avec Humind, envoie vos commandes et vos pages CMS, et ajoute les widgets Humind à votre boutique. Installez-le, connectez-le à votre compte Humind en un clic, et vos produits, variantes, prix, stocks et catégories arrivent seuls dans Humind.

Cette page couvre le module et le catalogue. Pour les widgets, voir Installer sur PrestaShop.

Prérequis ​

  • PrestaShop 1.7.8 ou plus récent, 8.x et 9.x : le module refuse de s'installer sur une version plus ancienne. PHP 7.1 ou plus récent avec l'extension curl.
  • Une boutique servie en HTTPS sur un domaine public, pour la connexion en un clic et les widgets.
  • Un compte Humind. Vous pouvez le créer pendant la connexion.
  • Une boutique et une devise (voir Limites).

Installer le module ​

  1. Téléchargez le module : humind-latest.zip.
  2. Dans le back-office PrestaShop, ouvrez Modules > Gestionnaire de modules, cliquez sur Installer un module et choisissez le zip.
  3. Cliquez sur Configurer sur le module Humind. Un employé doit avoir le droit de configurer ce module pour ouvrir sa page.

Installer le module ne change rien sur votre boutique tant que vous ne l'avez pas connecté.

Si un catalogue a déjà été envoyé par l'API ​

Ce que le module écrit est tenu à part de ce qu'une clé d'API a écrit avant. Une company qui a un catalogue plus ancien aurait les deux : produits et pages en double, et collections refusées parce que leur handle est déjà utilisé. Demandez à Humind de retirer l'ancien catalogue avant de connecter le module.

Se connecter à Humind ​

Le module propose deux façons de s'autoriser auprès de votre compte Humind. La connexion en un clic est celle que nous recommandons.

Connexion en un clic ​

  1. Sur la page de configuration du module, cliquez sur Se connecter à Humind.
  2. Votre navigateur ouvre Humind. Connectez-vous, ou créez votre compte si vous n'en avez pas encore : votre adresse e-mail est préremplie et la company prend le nom de votre boutique. Votre adresse reste à confirmer par e-mail, et la connexion reprend ensuite, même quelques jours plus tard.
  3. Humind affiche la boutique qui demande la connexion. Choisissez la company Humind à laquelle la lier, ou créez-en une nouvelle, et confirmez.
  4. Humind vous renvoie sur la page de configuration du module, qui indique Connecté à suivi du nom de votre company, puis affiche le panneau Votre connexion à Humind.

C'est tout. En coulisse, Humind :

  • crée pour cette boutique une clé d'API live nommée PrestaShop module, avec les scopes dont le module a besoin, et la remet une seule fois au module. Vous ne la voyez ni ne la copiez jamais, et le module ne la réaffiche plus ;
  • autorise le domaine de votre boutique, pour que les widgets puissent s'y charger ;
  • démarre la première synchro complète et la synchronisation incrémentale, et appelle lui-même les URL de cron et de synchronisation complète du module : le cron chaque minute, la synchronisation complète chaque nuit. Vous n'avez rien à planifier et aucune option à cocher.

À savoir :

  • Le code de la connexion est à usage unique et expire au bout de 10 minutes. S'il expire, cliquez de nouveau sur Se connecter à Humind.
  • L'adresse de la boutique doit être publique et en HTTPS. Une boutique sur localhost ou sur une adresse privée ne peut pas être connectée ainsi.
  • La clé apparaît dans Paramètres → Développeur → Identifiants de votre dashboard comme n'importe quelle autre clé, ce qui permet de voir sa dernière utilisation.
  • Seul un administrateur de la company Humind peut lier une boutique.
  • Une boutique appartient à une seule company Humind à la fois, et une company ne lie qu'une boutique. Pour déplacer une boutique, déconnectez-la de la première company.
  • Une company qui détient les commandes ou le catalogue d'une boutique qu'elle a connectée ne peut pas en connecter une autre : contactez Humind si c'est la même boutique à une nouvelle adresse.
  • Une company déjà connectée à Shopify ne peut pas lier une boutique PrestaShop.
  • L'adresse de la boutique ne peut pas porter de port.

Quand un pare-feu bloque Humind ​

Pendant la connexion, Humind lit une courte preuve sur votre boutique pour confirmer que vous la contrôlez. Si un pare-feu ou un service de sécurité comme Cloudflare bloque cet appel, la connexion réussit quand même et la synchronisation fonctionne, mais le domaine n'est pas autorisé automatiquement. Le module affiche alors un avertissement avec un lien Autoriser mon domaine vers la bonne page de votre dashboard. Humind y a déjà ouvert la demande pour votre domaine : sur la page des domaines autorisés, ajoutez l'enregistrement DNS TXT affiché et vérifiez le domaine (la demande reste ouverte 24 heures, et un changement DNS peut mettre du temps à se propager). Tant que le domaine n'est pas autorisé, les widgets ne se chargeront pas.

Le même service peut bloquer les appels que Humind fait à l'URL de cron. Voir le cron.

Saisir une clé d'API à la main ​

Si vous préférez gérer la clé vous-même, ou si votre boutique ne peut pas être jointe par la connexion en un clic :

  1. Dans votre dashboard, ouvrez Paramètres → Développeur → Identifiants et créez une clé. Voir Authentification pour les étapes. Donnez-lui les scopes catalog:read, catalog:write, imports:write, knowledge:write, orders:write et customers:identity. Le suivi de commande dans le chat et les clients connectés demandent quand même la connexion en un clic (voir plus bas).
  2. Collez la clé dans le champ Clé API des Options avancées et cliquez sur Enregistrer. La clé est stockée dans la configuration PrestaShop et n'est plus jamais affichée, et Changements du catalogue s'active. Pour la remplacer plus tard, utilisez Remplacer la clé API dans les Options avancées ; laissez le champ vide pour conserver la clé enregistrée. Remplacer une clé connectée en un clic la révoque.
  3. Renseignez éventuellement Identifiant d'entreprise (l'identifiant de 24 caractères affiché sur la même page du dashboard). Il permet aux widgets d'identifier votre company là où le domaine de la boutique ne le peut pas, par exemple sur une fenêtre de test localhost. La page doit toujours être sur un domaine autorisé, ou sur localhost tant qu'un test localhost est autorisé.
  4. Autorisez vous-même le domaine de votre boutique sur la page de liste blanche des URL. Humind vous demande de prouver que vous contrôlez le domaine, avec un enregistrement DNS TXT.
  5. Cliquez une fois sur Tout resynchroniser pour le premier catalogue, et planifiez vous-même l'URL de cron (voir le cron).

Déconnecter ​

Le bouton Déconnecter des Options avancées révoque la clé côté Humind (quand c'est la connexion qui l'a créée) et la retire de PrestaShop. Une clé saisie à la main est seulement oubliée par le module : révoquez-la dans votre dashboard si vous n'en avez plus besoin. La déconnexion renouvelle aussi le jeton du flux : qui avait gardé l'adresse du flux ne lit plus le catalogue. Désinstaller le module fait la même chose que Déconnecter. Vos produits restent dans Humind. Reconnectez-vous à tout moment avec Se connecter à Humind : la première synchro complète repart toute seule.

Vous pouvez aussi déconnecter la boutique depuis la carte d'intégration de votre dashboard Humind. Le module ne l'apprend pas tout de suite : il continue d'afficher la connexion, puis avertit que Humind n'accepte plus sa clé ou, une fois que Humind cesse d'appeler le cron, que vos changements n'arrivent plus à Humind. Cliquez sur Déconnecter dans le module pour le remettre à zéro (son message sur la clé qui n'a pas pu être révoquée est alors attendu).

La première synchro complète ​

Après une connexion en un clic, la première synchro complète démarre toute seule. Le module exporte tous les produits de la boutique en NDJSON, les envoie à Humind et démarre l'import asynchrone. Les produits désactivés sont envoyés aussi, avec le statut archived, pour que Humind les connaisse sans les recommander. L'export avance par tranches : là où un hébergeur arrête les scripts longs, le prochain appel du cron le reprend.

La page du module affiche Import en cours, puis Produits envoyés et Dernière mise à jour, et vous pouvez quitter la page entre-temps. Le détail est dans votre dashboard, sous Paramètres > Catalogue > Import catalogue.

Avec une clé saisie à la main, cliquez une fois sur Tout resynchroniser. Le même bouton est là dès que quelque chose ne semble pas à jour : le catalogue, les collections et les pages sont tous renvoyés.

Une synchro complète relit tout le catalogue, et Humind accepte au plus 6 imports par heure et par company. Le cron porte les changements du quotidien, et Humind relance lui-même une synchro complète chaque nuit une fois la boutique connectée en un clic.

Produits disparus de la boutique ​

Une synchro complète archive dans Humind les produits que la boutique n'a plus, sauf si un produit n'a pas pu être exporté. Le premier import sert seulement de référence. Quand une synchro trouve moins de 80 % des produits de la précédente, rien n'est archivé et la page du module pose la question : Les archiver confirme, et la synchro de nuit ne le fait jamais à votre place.

Garder le catalogue à jour (cron) ​

Les changements entrent dans une file d'attente dans PrestaShop tant que Changements du catalogue est actif (Options avancées > Ce qui est envoyé ; la connexion en un clic l'active) : produits créés, modifiés ou supprimés, stock, déclinaisons, images, marques, caractéristiques, remises et promotions qui commencent ou se terminent. Les hooks écrivent seulement dans la file : enregistrer un produit dans le back-office reste rapide quel que soit l'état du réseau. L'Adresse de mise à jour automatique (l'URL de cron) affichée dans Options avancées > Mises à jour automatiques vide cette file.

  • Connecté en un clic : Humind appelle l'URL de cron chaque minute. Il n'y a rien à faire.
  • Clé d'API saisie à la main : appelez l'URL chaque minute vous-même, par exemple avec un cron serveur :
bash
* * * * * curl -fsS "URL_DE_CRON_DU_MODULE" > /dev/null

Remplacez URL_DE_CRON_DU_MODULE par l'URL exacte affichée sur la page du module, qui contient déjà votre jeton secret. Gardez-la confidentielle, comme l'URL de synchronisation complète.

Son comportement :

  • Chaque appel traite au plus 100 produits en file, envoyés à Humind par lots de 20, et 20 commandes.
  • Un produit en échec passe en fin de file et est retenté à un appel suivant. Les échecs sont consignés dans le journal PrestaShop (Paramètres avancés > Logs). Un produit qui fait tomber PHP cesse de retenir les autres : il revient au bout d'une heure, ou quand il est de nouveau enregistré.
  • Les produits supprimés dans PrestaShop sont archivés dans Humind par le cron.
  • Le cron envoie d'abord les commandes en file, puis les produits, les catégories dès qu'une catégorie ou un produit change (voir Collections), et les pages CMS.
  • Une règle de prix sur tout le catalogue n'a pas de produit à mettre en file : elle arrive dans Humind avec la synchro complète suivante.

Si le cron n'est pas appelé, rien n'est perdu : les changements attendent dans la file jusqu'au prochain appel.

Surveiller le cron ​

Dans les Options avancées, la page du module affiche Dernier passage, l'heure du dernier appel du cron, et le nombre de produits et de commandes en attente. Si le cron n'est pas passé depuis plus de 5 minutes, un avertissement apparaît en haut de la page : les changements n'arrivent plus à Humind. Avec une clé saisie à la main, planifiez l'URL de cron. Connecté en un clic, c'est le plus souvent un pare-feu ou un service de sécurité qui ne laisse passer que les navigateurs et bloque les appels de Humind : autorisez le robot HumindBot (son user-agent contient HumindBot), ou ajoutez au crontab de votre serveur la ligne affichée sous Ligne pour les tâches planifiées de votre serveur, prête à copier. En attendant, vos changements partent quand un employé qui peut configurer le module utilise le back-office. Après 10 appels en échec d'affilée, votre dashboard Humind signale aussi la boutique comme injoignable, ou indique qu'un pare-feu bloque Humind.

Ce qui est synchronisé ​

Produits ​

Un produit sans nom dans la langue par défaut (la ligne vide que PrestaShop crée quand vous cliquez sur « Ajouter un produit ») est laissé de côté jusqu'à son enregistrement avec un nom.

Champ HumindSource dans PrestaShop
ID externe du produitID produit PrestaShop
TitreNom du produit
DescriptionLa description courte et la description longue réunies, en texte brut, avec le contenu d'un pack
Description HTMLDescription longue (HTML), sinon la courte
Slug d'URL et URL produitURL simplifiée et URL de la page produit
CatégoriesNoms des catégories (la racine et l'accueil sont ignorés)
ImagesImages du produit, la couverture en premier
MarqueFabricant
TraductionsLes mêmes champs dans chaque autre langue active
Statutarchived pour un produit désactivé ou qu'un visiteur ne peut pas atteindre (réservé à un groupe de clients), unlisted quand sa visibilité est « nulle part », active sinon
Metafields prestashop.<caractéristique>Caractéristiques produit (par exemple Matière ou Dimensions), traduites par langue. Une caractéristique à plusieurs valeurs devient une liste
Metafields prestashop.*Tags, textes de disponibilité et de livraison, état, poids, dimensions d'expédition et prix unitaire, contenu d'un pack (pack_contents), et price_hidden sur un produit dont la boutique masque le prix
Produits complémentairesAccessoires (25 au plus par produit)

Variantes ​

Champ HumindSource dans PrestaShop
ID externe de la varianteproduct-{id} pour un produit sans déclinaison, combination-{id} sinon
SKURéférence de la déclinaison, sinon référence du produit
PrixLe prix que voit un visiteur de la boutique : pays par défaut et devise par défaut de la boutique, remises appliquées, TTC sauf si le groupe Visiteur affiche les prix hors taxes
Prix barréLe prix normal, quand une remise s'applique
DeviseLa devise par défaut de la boutique
StockQuantité disponible, jamais en dessous de 0 (un stock négatif dû aux précommandes est envoyé à 0). Un pack a le stock de ses articles
DisponibilitéDisponible quand le stock est supérieur à 0 ou que les commandes en rupture sont autorisées
Options et titre de la varianteAttributs de la déclinaison (par exemple Couleur : Bleu, Taille : M), traduits par langue
ImageLa première image rattachée à la déclinaison, sur sa propre variante
Metafields prestashop.gtin et prestashop.mpnEAN-13 et MPN (la valeur de la déclinaison, sinon celle du produit)
Ajout au panierL'action native d'ajout au panier de PrestaShop, pour que le widget ajoute au vrai panier (voir Ajout au panier). Ce que PrestaShop refuse en un clic passe par la fiche produit : prix masqué, mode catalogue, produit non commandable en ligne, quantité minimale supérieure à 1, personnalisation obligatoire

Langues ​

Seules les langues actives de la boutique sont envoyées ; une langue désactivée est laissée de côté. Les traductions sont indexées par code de base, comme les widgets les demandent : gb et us deviennent en, tw et cn deviennent zh, qc devient fr, br devient pt, mx, ag, cb, pe et ve deviennent es, dh devient de. Les autres codes à deux lettres sont envoyés tels quels. Quand deux langues partagent un code, la langue par défaut l'emporte, puis la langue sans variante régionale.

À la connexion et à chaque synchronisation complète, le module envoie aussi la liste des langues. La première liste d'une boutique connectée : une company qui a au plus une langue la prend ; une company qui en a deux ou plus les garde, avec sa langue principale, et les langues manquantes sont ajoutées. Ensuite, seule une langue nouvelle dans la boutique est ajoutée : la langue principale ne change jamais, rien n'est retiré, et une langue que vous avez retirée de Humind ne revient pas. Une reconnexion n'est pas une première connexion. Avec une clé API collée à la main, la liste est ignorée. Les questions de départ et les questions produit sont traduites dans les langues ajoutées, une seule fois. Une langue retirée de la boutique reste dans Humind.

Sur une boutique connectée avant de vendre quoi que ce soit dans Humind, quand l'adresse saisie à l'inscription n'est pas celle de la boutique, la première synchronisation complète remplace aussi la description de la boutique et les questions de départ lues sur cet autre site par une description et des questions tirées de votre catalogue, dans la langue par défaut de la boutique. Vides, elles sont aussi écrites depuis le catalogue. Une description ou des questions que vous avez modifiées ne sont pas touchées, pas plus que des questions désactivées, liées à une entrée de connaissance ou déjà traduites.

Collections ​

Les catégories PrestaShop deviennent des collections Humind, avec l'ID externe category-{id}. Chaque collection porte :

  • son titre, préfixé par la catégorie parente quand deux catégories portent le même nom,
  • sa description et l'URL de sa page,
  • les produits qu'elle contient,
  • ses traductions dans chaque langue active.

Les catégories techniques racine et accueil ne sont pas envoyées. Une catégorie désactivée, ou qu'un visiteur ne peut pas atteindre, est archivée. Une catégorie supprimée est archivée par le cron.

Une collection ne contient que les produits que Humind connaît déjà au moment où il la reçoit. La synchro complète démarre un import asynchrone : le module attend donc la fin de l'import et le cron envoie ensuite les collections. Tant qu'il manque des produits, il les renvoie 15 minutes plus tard. Le cron envoie aussi les collections dès qu'une catégorie ou un produit change, au plus une fois toutes les 15 minutes. Voir Lier les produits par external_id.

Tout resynchroniser les renvoie avec le catalogue. Les collections ont besoin du cron : avec une clé d'API saisie à la main et sans cron, elles ne sont pas envoyées.

Commandes, clients connectés et pages CMS ​

Au-delà du catalogue, le module couvre trois choses de plus. Commandes et Pages CMS sont des interrupteurs dans Options avancées > Ce qui est envoyé, actifs par défaut. Les clients connectés n'ont pas d'interrupteur propre : ils suivent le widget de chat.

  • Commandes. Quand une commande est validée, y compris par un webhook de paiement, le module lit le cookie humind_attribution que le widget de chat pose sur votre domaine et met la commande en file. Les changements de statut sont aussi mis en file. Le cron les envoie à Humind : la commande, puis son statut, son libellé, son numéro de suivi et son URL de suivi. Humind mesure les ventes auxquelles l'assistant a contribué, et signale les lignes de commande ajoutées au panier depuis le chat. Chaque commande envoyée porte l'identifiant et l'email du client, les lignes et les totaux, dans la devise de la boutique. Les commandes passées avant la connexion ne sont pas envoyées en masse : l'une d'elles est envoyée en entier la première fois que son statut change. Rien n'est envoyé pendant le paiement lui-même, donc le client n'attend jamais Humind. Si Humind refuse les commandes (par exemple une clé saisie à la main sans le scope orders:write), elles restent dans la file et la page du module affiche l'erreur jusqu'à ce que la clé soit corrigée. Le côté visiteur, le suivi de commande dans le chat, est décrit dans Suivi de commande.
  • Clients connectés. Le widget de chat appelle la page identity du module sur votre boutique (index.php?fc=module&module=humind&controller=identity, ou /module/humind/identity avec les URL simplifiées). Pour un client connecté, le module obtient auprès de Humind un jeton d'identité de courte durée, de serveur à serveur, et le remet au widget, pour que le client suive ses propres commandes dans le chat sans rien saisir. Un visiteur anonyme reçoit une réponse vide, et l'email du client ne transite jamais par le navigateur : le jeton ne porte que son identifiant PrestaShop et expire au bout de 30 minutes. Le suivi de commande dans le chat et les clients connectés demandent la connexion en un clic : elle seule enregistre votre company comme une company PrestaShop. Avec une clé saisie à la main, les commandes sont quand même envoyées et attribuées, mais le chat ne les suit pas.
  • Pages CMS. Vos pages CMS (livraison, retours, à propos...) deviennent des entrées webpage de la base de connaissances Humind, dans le dossier PrestaShop > Pages, avec leur HTML et leurs traductions, pour que l'assistant puisse répondre à partir d'elles. Elles sont envoyées par le cron dès qu'une page change, et avec Tout resynchroniser. Les pages désactivées ou supprimées sont archivées.

Le module appelle pour vous l'API Commandes de Humind, avec le scope orders:write.

Flux produit ​

Le module expose aussi un flux CSV protégé par jeton, une ligne par variante, pour les marchands qui préfèrent que Humind vienne lire le catalogue à intervalle régulier plutôt que la synchronisation par API. Copiez l'Adresse du flux depuis les Options avancées dans votre dashboard, sous Paramètres > Catalogue > Import catalogue > Flux produit, testez-la et vérifiez la correspondance des champs. Voir URL de flux produit. Renouveler le jeton du flux émet une nouvelle URL si l'ancienne est exposée ; mettez-la ensuite à jour dans Humind.

Limites ​

  • Une boutique. Le module connecte uniquement la boutique courante, et affiche un avertissement quand plusieurs boutiques sont activées : choisissez la boutique dans le sélecteur en haut du back-office avant de connecter, de déconnecter ou d'enregistrer une clé, car une connexion appartient à une seule boutique. Le multiboutique PrestaShop est hors périmètre.
  • Le prix du pays par défaut. Humind garde un seul prix par variante : celui qu'obtient un visiteur dans le pays par défaut de la boutique, avec la taxe de ce pays. Les prix des autres pays ou des groupes de clients ne sont pas synchronisés.
  • Une devise. Les prix sont envoyés dans la devise par défaut de la boutique. Les autres devises et les conversions ne sont pas synchronisées.
  • Stock par entrepôt. Le module envoie la quantité disponible de la boutique. Le stock par entrepôt de la gestion avancée des stocks PrestaShop n'est pas synchronisé.
  • 250 déclinaisons au plus par produit. Humind en reçoit 250, celles en vente d'abord, et la page du module le signale.
  • Compteur du panier du thème. Après un ajout depuis le chat, le widget émet l'événement PrestaShop updateCart. Un thème dont le compteur du panier n'écoute pas cet événement affiche l'ancien nombre jusqu'au prochain chargement de page. Le produit est bien dans le panier.

Dépannage ​

  • La connexion échoue. Vérifiez que l'adresse de la boutique est publique et en HTTPS, puis cliquez de nouveau sur Se connecter à Humind. Le code d'une connexion dure 10 minutes et ne sert qu'une fois. Si la boutique est déjà connectée à une autre company, déconnectez-la d'abord là-bas.
  • Il n'y a pas de bouton Se connecter à Humind. La boutique a déjà une clé, saisie à la main. Pour passer à la connexion en un clic, cliquez sur Déconnecter dans les Options avancées, puis sur Se connecter à Humind.
  • Le module indique que Humind n'a pas pu confirmer votre domaine. Un pare-feu ou un service de sécurité bloque l'appel de preuve, ou le domaine est relié à une autre entreprise Humind. La synchronisation fonctionne ; terminez la demande de domaine que Humind a ouverte pour vous sur la page des domaines autorisés (enregistrement DNS TXT).
  • Un produit apparaît en double, ou une synchro échoue sur une collection dont le handle est déjà utilisé. Un catalogue plus ancien envoyé par l'API est encore dans Humind. Voir plus haut.
  • Un prix diffère du prix Humind. Humind reçoit le prix du pays par défaut, remises appliquées, dans la devise par défaut de la boutique. Vérifiez les règles de taxe, le groupe Visiteur et les prix spécifiques dans PrestaShop.
  • Les changements dans PrestaShop n'arrivent pas dans Humind. Vérifiez Dernier passage et l'interrupteur Changements du catalogue dans les Options avancées. Si le cron n'est pas passé depuis plus de 5 minutes, autorisez le robot HumindBot dans votre pare-feu ou ajoutez la ligne de crontab affichée par le module. Les produits en échec sont listés dans le journal PrestaShop.
  • Le module indique que la dernière synchro complète s'est arrêtée avant la fin. C'est sans doute une limite de temps ou de mémoire de votre serveur. Essayez Tout resynchroniser ; si elle s'arrête encore, votre hébergeur peut relever ces limites.
  • Les commandes n'arrivent pas. La page du module affiche le refus de Humind quand la clé n'a pas un scope. Cliquez sur Déconnecter, puis sur Se connecter à Humind, ou utilisez Remplacer la clé API avec une clé qui porte le scope manquant. Si vous avez saisi la clé à la main, désactivez Commandes et Pages CMS quand la clé n'a pas leurs scopes.
  • Le widget ne s'affiche pas. Voir Vérifier.

Suite ​

Released under the proprietary Humind license.