Guide d'installation
Du paquet à une boutique Shopify connectée, licenciée et synchronisée : prérequis, connexion, licence, réglages, tâches planifiées
Télécharger le PDFCe guide vous mène de zéro à une boutique Shopify connectée à Dolibarr, avec une licence active et les synchronisations réglées. Il correspond à Doli2Shop 2.6.3 et aux versions suivantes. Comptez une heure, dont dix minutes chez Shopify. Les captures montrent une boutique de démonstration fictive : les noms, domaines et numéros que vous verrez chez vous seront les vôtres.
Les étapes, dans l'ordre :
- les prérequis ;
- l'installation du paquet et l'activation du module ;
- la connexion de la boutique Shopify ;
- la licence ;
- l'assistant de configuration ;
- le sens de la synchronisation ;
- le stock (réel ou virtuel) et l'emplacement Shopify ;
- les tâches planifiées ;
- les vérifications finales ;
- ce qui se passe quand la licence se termine.
1. Prérequis
| Élément | Exigence |
|---|---|
| Dolibarr | version 18 à 24 |
| PHP | 7.4 au minimum. Le plafond dépend de votre Dolibarr : PHP 8.1 au plus avec Dolibarr 18, PHP 8.5 au plus avec Dolibarr 23 et 24 |
| Base de données | MySQL 5.7 ou plus récent, ou MariaDB 10.3 ou plus récent |
| Adresse de Dolibarr | en HTTPS (obligatoire : Shopify refuse de renvoyer la connexion vers une adresse en HTTP) |
| Compte Dolibarr | un compte administrateur : les écrans du module lui sont réservés |
| Shopify | une boutique, et un compte qui a le droit d'y installer une application |
| Planificateur | le module Dolibarr « Travaux planifiés » actif, et son déclencheur système en place (voir la section 8) |
Doli2Shop s'appuie sur les modules Dolibarr Produits, Tiers, Commandes clients, Stock et Catégories : Dolibarr les active avec lui s'ils ne le sont pas déjà.
2. Installer le paquet et activer le module
Vous avez reçu un fichier .zip (e-mail de confirmation
DoliStore). Deux façons de l'installer.
Depuis Dolibarr. Allez dans Accueil → Configuration
→ Modules/Applications, ouvrez l'onglet
Déployer/Installer un module externe et déposez le
fichier .zip. Si Dolibarr refuse (installation depuis
l'application verrouillée, ou dossier custom non déclaré),
passez à la seconde façon.
À la main. Décompressez l'archive dans le dossier
htdocs/custom/ de votre serveur : vous devez obtenir
htdocs/custom/doli2shop/. Le fichier
conf/conf.php de Dolibarr doit déclarer ce dossier :
$dolibarr_main_url_root_alt='/custom';
$dolibarr_main_document_root_alt='/chemin/vers/htdocs/custom';
Puis activez le module :
- Retournez dans Accueil → Configuration → Modules/Applications.
- Tapez
doli2shopdans le champ de recherche. - Sur la vignette du module, basculez l'interrupteur sur « actif ».
- Cliquez sur l'icône en forme d'engrenage de la vignette pour ouvrir la configuration.
Le module n'a pas d'entrée dans le menu de gauche de Dolibarr : l'engrenage de cette liste est toujours votre porte d'entrée. Vous arrivez sur une barre d'onglets ; le premier est Assistant.
3. Connecter la boutique Shopify
Vous pouvez connecter la boutique de deux façons, qui mènent au même résultat : depuis l'onglet Assistant (étape 1), ou depuis l'onglet Boutiques.
Avant la connexion, l'étape 1 affiche Non connecté et le bouton Connecter ma boutique Shopify. Depuis l'onglet Boutiques, le bouton équivalent s'appelle Connecter une boutique (via Shopify).
- Cliquez sur le bouton. Si votre Dolibarr n'est pas en HTTPS, le
module refuse et le dit : corrigez l'adresse
(
$dolibarr_main_url_rootdansconf/conf.php) avant de recommencer. - Vous quittez Dolibarr pour une page de doli2shop.ptitetete.org qui annonce quatre étapes. Cliquez sur « Installer Doli2Shop ».
- Chez Shopify : connectez-vous à votre compte, choisissez la boutique si vous en avez plusieurs, relisez les permissions demandées et approuvez-les. Shopify affiche ces permissions lui-même ; vérifiez que l'adresse du navigateur est bien celle de Shopify avant d'approuver. L'application est aussi présentée sur https://apps.shopify.com/doli2shop.
- Shopify vous renvoie automatiquement vers Dolibarr. Le module enregistre les identifiants de la boutique, repère son emplacement de stock et enregistre les webhooks (les notifications que Shopify envoie à Dolibarr). Un message « Connexion à votre-boutique.myshopify.com réussie ! » confirme l'opération.
Pour vérifier : dans l'onglet Boutiques, la boutique est listée avec son domaine Shopify ; dans l'assistant, l'étape 1 affiche Connecté à suivi du domaine, avec la date de connexion et l'identifiant de l'emplacement. Pour reconnecter une boutique (jeton expiré, changement de droits), utilisez le bouton de reconnexion de la même ligne ou de l'étape 1 : la configuration déjà faite est conservée.
4. Activer la licence
La licence se gère boutique par boutique.
- Dans l'onglet Boutiques, cliquez sur Modifier sur la ligne de la boutique, puis sur le sous-onglet Licence.
- Sous Activer une licence DoliStore, saisissez votre
numéro de série, au format
SI-YYYY-XXXX-XXXX(celui de l'e-mail de confirmation DoliStore ; les lettres sont mises en majuscules automatiquement), puis cliquez sur Activer cette licence. Le module a besoin du domaine Shopify de la boutique : une boutique qui n'est pas encore connectée (section 3) ne peut pas recevoir de licence. - Le message « Licence DoliStore activée avec succès » confirme l'activation et Statut licence passe à Licence valide.
- À tout moment, Vérifier maintenant interroge le serveur de licences et met à jour le statut et la date de dernière vérification.
À savoir :
- Essai. Un essai est un numéro de série
SI-…à durée courte, délivré par le mainteneur : il s'active exactement comme une licence normale, et se termine comme elle (section 10). - Boutique par défaut. La première boutique connectée est la boutique par défaut. Tant que le serveur de licences n'annonce pas de date d'arrêt, elle n'est pas bloquée : l'écran Santé l'affiche comme Exemptée (boutique par défaut) et ce sous-onglet porte la mention jamais bloquée. Cette mention est à lire avec la section 10 : une fois la date d'arrêt annoncée par le serveur dépassée, la boutique par défaut s'arrête comme les autres.
- Version Community. La version Community, gratuite et publiée sous licence libre, ne contient aucun système de licence : elle fonctionne sans clé, l'écran Santé affiche Version Community (gratuite) et le support technique est réservé aux adhérents.
- Serveur de licences injoignable. Le module affiche Impossible de vérifier votre licence pour le moment et réessaie de lui-même. Pour la boutique par défaut, la synchronisation continue tant que la dernière vérification réussie date de moins de 14 jours (délai par défaut) ; passé ce délai, elle s'arrête jusqu'au retour du serveur. Une boutique secondaire, elle, n'est synchronisée que lorsque sa licence a pu être vérifiée : une panne prolongée du serveur la met en pause, elle reprend seule ensuite.
- Jamais vérifiée. Une boutique par défaut dont la licence n'a jamais pu être vérifiée avec succès n'est pas bloquée, même si le serveur reste injoignable.
5. L'assistant de configuration
L'onglet Assistant compte six étapes. Il se souvient de l'étape où vous en étiez, et un bouton permet de recommencer depuis le début.
| Étape | Titre | Ce que vous y réglez |
|---|---|---|
| 1 | Connexion Shopify | la connexion décrite à la section 3 |
| 2 | Configuration Dolibarr | Entrepot par defaut et Utilisateur CRON / Webhook (obligatoires), puis Catégorie clients Shopify et Mapping type de tiers B2B/B2C |
| 3 | Commandes | le préfixe des commandes, le délai de livraison, Origine de la commande, Conditions de règlement, le compte bancaire pour les paiements et les traitements automatiques (bons d'expédition, factures, paiements) |
| 4 | Expédition | Correspondance des méthodes d'expédition, par boutique |
| 5 | Paiement | Correspondance des méthodes de paiement, par boutique |
| 6 | Activation | le contrôle final, l'activation des webhooks et celle des tâches planifiées |
Points d'attention :
- À l'étape 2, l'entrepôt est indispensable : sans entrepôt par défaut, le stock n'est pas décrémenté quand une commande Shopify arrive, et rien ne vous le signale. Ces réglages sont communs à toutes les boutiques ; ils ne se modifient que depuis la boutique par défaut.
- Aux étapes 4 et 5, les correspondances sont propres à chaque boutique. Si vous en avez plusieurs, choisissez d'abord la boutique dans le sélecteur Configurer la boutique, puis réglez ses correspondances.
- À l'étape 6, le module contrôle la connexion, l'entrepôt et l'utilisateur, et affiche Webhooks enregistres et CRONs actifs. Les boutons Activer les webhooks et Activer les CRONs corrigent un compteur incomplet ; Terminer la configuration referme l'assistant en signalant ce qui manque encore.
6. Le sens de la synchronisation
L'onglet Sens de synchronisation décide, type de données par type de données, qui écrit chez qui.
Les cinq premières lignes (Synchronisation produits, Synchronisation commandes, Synchronisation paiements, Synchronisation expéditions et Synchronisation stocks) se règlent par un sens : Shopify vers Dolibarr, Dolibarr vers Shopify ou Bidirectionnel. Aucune synchronisation n'est proposée d'office que pour les produits ; pour les commandes, les paiements, les expéditions et les stocks, elle n'apparaît que si ce réglage est déjà enregistré. La sixième ligne, Stratégie de résolution des conflits, n'est pas un sens : elle propose cinq stratégies pour départager les deux côtés quand une même donnée a changé des deux côtés (priorité à Shopify, à Dolibarr, à la modification la plus récente, à la plus ancienne, ou résolution manuelle).
Ce qu'il faut savoir avant d'enregistrer :
- Les stocks : tant que rien n'a été enregistré sur cet écran, le sens affiché et appliqué est Dolibarr vers Shopify. Dolibarr est la référence du stock (réapprovisionnements, production, inventaire) et Shopify n'y écrit pas.
- Les produits : il n'y a pas de sens présélectionné. La liste affiche Sélectionner la direction de synchronisation : choisissez un sens, puis enregistrez. Tant que vous n'en choisissez pas, il n'est pas enregistré.
- Commandes, paiements, expéditions : seul le sens Shopify vers Dolibarr fonctionne. Le sens Dolibarr vers Shopify n'est pas encore implémenté pour ces trois types : un réglage qui l'inclut est enregistré mais reste sans effet, et l'écran l'annonce par un avertissement. Pour les expéditions, le sens affiché par défaut est Bidirectionnel : choisissez Shopify vers Dolibarr.
- Les paiements et les expéditions dépendent des commandes : ne coupez pas la synchronisation des commandes si vous voulez les autres.
Cliquez sur Enregistrer en bas de l'écran pour valider les six lignes.
7. Stock réel ou virtuel, emplacement Shopify
Ces réglages sont propres à chaque boutique : choisissez d'abord la boutique concernée dans le sélecteur de boutique affiché en haut de l'écran.
Réel ou virtuel. Dans l'onglet Synchronisation des produits, la case Synchroniser les stocks active l'envoi du stock vers Shopify. La case Utiliser le stock virtuel pour Shopify, qui n'est cochable que si la première l'est, envoie à Shopify le stock virtuel (stock réel, moins les commandes clients, plus les commandes fournisseurs) au lieu du stock réel. Le stock virtuel est recommandé : il évite de vendre ce qui est déjà promis.
Emplacement. Shopify gère le stock par emplacement. Le module repère l'emplacement au moment de la connexion (section 3). Pour le vérifier ou le changer : onglet Boutiques, Modifier sur la ligne de la boutique, sous-onglet Expédition, champ Identifiant emplacement Shopify. L'identifiant se lit dans l'administration de Shopify, dans les réglages des emplacements.
8. Les tâches planifiées
Doli2Shop travaille surtout par tâches planifiées de Dolibarr. Elles
se trouvent dans Accueil → Outils d'administration → Travaux
planifiés ; filtrez sur le module doli2shop.
Dolibarr n'exécute ces tâches que si son planificateur est lui-même
déclenché régulièrement (une ligne de crontab sur le
serveur). La commande à y mettre est affichée dans la configuration du
module « Travaux planifiés » (engrenage de sa vignette, dans la liste
des modules). Sans ce déclencheur, rien ne tourne, même si les tâches
sont « programmées ».
Actives dès l'installation :
| Tâche | Rôle |
|---|---|
Doli2ShopWebhookProcess |
traite les webhooks reçus de Shopify |
Doli2ShopOrdersCatchup |
rattrape les commandes qu'un webhook aurait manquées |
Doli2ShopFulfillmentCatchup |
rattrape les expéditions manquées |
Doli2ShopStockPushQueueProcess |
envoie à Shopify les changements de stock |
Doli2ShopTokenRefresh |
renouvelle le jeton de connexion avant son échéance |
Doli2ShopWebhookHealthCheck |
contrôle les webhooks et les réenregistre au besoin |
Doli2ShopHeartbeat |
remontée quotidienne des métriques du module |
Tâches de produits. Doli2ShopProductsExport et
Doli2ShopProductsImport sont inactives à l'installation.
Depuis la version 2.6.3, enregistrer le sens des produits (section 6)
positionne ces deux tâches selon le sens choisi, pour les boutiques
connectées et licenciées. Cela ne se produit que lorsque l'état attendu
change, et une tâche que vous avez mise en pause volontairement n'est
jamais réactivée. Après l'enregistrement, vérifiez leur état dans la
liste des travaux planifiés : la capture montre une boutique de
démonstration connectée et licenciée, où elles sont déjà
programmées.
À activer à la main selon vos besoins (inactives à l'installation) :
| Tâche | À activer si |
|---|---|
Doli2ShopOrdersHistoricalImport |
vous importez l'historique des commandes d'une boutique déjà en service |
Doli2ShopHistoricalCleanup |
vous avez lancé cet import historique (nettoyage après coup) |
Doli2ShopAlertCheck |
vous voulez des alertes par e-mail en cas d'erreurs répétées |
9. Vérifier l'installation
L'onglet Santé & diagnostic rassemble les contrôles. Il comporte notamment Synthèse par boutique (connexion, webhooks actifs, statut de licence de chaque boutique), Vérifications système, État du module, Connectivité API Shopify et Tâches planifiées. Une pastille de couleur sur l'onglet signale une dégradation.
Passez-le en revue après l'installation : connexion Shopify réussie, webhooks actifs, tâches actives, aucun droit manquant. En cas de doute, la procédure « Envoyer au support le journal et les exports JSON » (https://doli2shop.ptitetete.org/fr/documentation/support-export) vous dit quoi nous transmettre.
Pour relier le module à un Dolibarr déjà peuplé (produits, tiers et commandes existants), suivez la « Procédure de mise en production » (https://doli2shop.ptitetete.org/fr/documentation/go-live) avant d'activer les synchronisations.
10. Quand la licence se termine
Ce qui suit décrit la boutique par défaut. Une boutique secondaire n'a pas de période de grâce : elle n'est synchronisée que tant que sa licence est valide, et sa synchronisation s'arrête dès qu'elle ne l'est plus.
- Licence expirée : mode dégradé. Le module affiche Votre licence a expiré !. La synchronisation continue de fonctionner, mais le support et les téléchargements sont désactivés.
- Soixante jours de grâce. Après l'expiration, la synchronisation continue encore 60 jours. Le module affiche alors Synchronisation bientôt interrompue et, quand le serveur de licences fournit la date, le jour où tout s'arrêtera. Sans cette date, aucun jour d'arrêt n'est affiché.
- Arrêt. La date passée, Synchronisation arrêtée (licence) s'affiche : toute la synchronisation avec Shopify s'arrête, y compris la remontée des commandes. Vos commandes Shopify n'arrivent plus dans Dolibarr tant que la licence n'est pas renouvelée.
Renouvelez votre licence avant l'arrêt : la synchronisation reprend dès que la nouvelle licence est activée (section 4). Si aucune licence n'a jamais été liée à une boutique, le module l'indique par Aucune licence n'est liée à cette boutique.