Documentation complète

Guide détaillé d'installation et de configuration du module Shopify Integration

Table des matières

1. Introduction

Ce guide vous explique étape par étape comment configurer l'intégration Shopify pour Dolibarr. Nous détaillons exactement où trouver chaque valeur nécessaire à la configuration.

Ce que vous allez apprendre : D'où viennent toutes les valeurs de configuration et comment les obtenir précisément.

Nouveautés v2.0.24

Cette version apporte des améliorations majeures pour une intégration plus fluide et automatisée.

Nouvelles fonctionnalités

Import automatique des commandes historiques

Le système CRON peut maintenant importer automatiquement vos commandes historiques lors de la première synchronisation, créant automatiquement les clients associés.

Auto-activation intelligente des CRONs

Les tâches CRON s'activent automatiquement dès que les configurations produits et commandes sont complètes, et se désactivent si la configuration devient incomplète pour éviter les erreurs API.

Corrections critiques

Problèmes résolus :
  • Synchronisation manuelle : Correction du cas où l'interface affichait les produits mais ne pouvait pas les synchroniser
  • Gestion des services : Les services sont maintenant correctement identifiés et synchronisés comme tels (requiresShipping: false)
  • Paramètres unifiés : Gestion cohérente des paramètres entre les interfaces de recherche et de synchronisation
  • SKUs avec zéros : Préservation correcte des zéros de tête dans les références produits

Améliorations de sécurité

Installation sécurisée : Les tâches CRON sont désormais désactivées par défaut à l'installation pour éviter les appels API prématurés. Elles s'activent automatiquement une fois la configuration terminée.

2. Prérequis système

Dolibarr & Serveur

Composant Version requise Vérification
PHP 7.2.5 à 8.3.16 Menu Dolibarr → Accueil → Informations système
Dolibarr 19.0 à 21.x Menu Dolibarr → Accueil → Version
Extension cURL Activée Menu Dolibarr → Accueil → Informations système → Extensions PHP
Extension JSON Activée Menu Dolibarr → Accueil → Informations système → Extensions PHP

Shopify

3. Installation du module

Étape 1 : Achat et téléchargement

  1. Achetez le module sur Dolistore
  2. Téléchargez le fichier ZIP depuis votre compte Dolistore
  3. Ne dézippez pas le fichier

Étape 2 : Installation dans Dolibarr

  1. Connectez-vous à Dolibarr en tant qu'administrateur
  2. Allez dans Accueil → Configuration → Modules/Applications
  3. Cliquez sur "Déployer/Installer module/application externe"
  4. Sélectionnez votre fichier ZIP téléchargé
  5. Cliquez sur "Envoyer fichier"
  6. Activez le module dans la liste des modules disponibles
Important : Activez ces modules Dolibarr requis avant de continuer :
  • Produits/Services
  • Tiers (Clients/Fournisseurs)
  • Commandes clients
  • Factures clients
  • Stocks
  • Expéditions

4. Création de l'application Shopify

Étape cruciale : Vous devez créer une application privée dans Shopify pour obtenir les clés d'accès.

Étape 1 : Accéder aux applications

  1. Connectez-vous à votre administration Shopify
  2. Dans le menu de gauche, cliquez sur "Apps"
  3. Cliquez sur "Développer des apps" (ou "App and sales channel settings")
  4. Si c'est votre première app, cliquez sur "Permettre le développement d'applications personnalisées"

Étape 2 : Créer l'application

  1. Cliquez sur "Créer une app"
  2. Nom de l'app : Dolibarr Integration
  3. Email du développeur : votre email
  4. Cliquez sur "Créer l'app"

Étape 3 : Configurer les permissions

Cliquez sur "Configurer les scopes Admin API" et activez ces permissions :

Scope Permission Justification
read_products Lecture Lire les produits Shopify
write_products Écriture Créer/modifier les produits
read_orders Lecture Lire les commandes
write_orders Écriture Modifier les commandes
read_customers Lecture Lire les données clients
write_customers Écriture Créer des clients
read_inventory Lecture Lire les stocks
write_inventory Écriture Mettre à jour les stocks
read_locations Lecture Lire les emplacements

Cliquez sur "Enregistrer" après avoir sélectionné tous les scopes.

Étape 4 : Installer l'application

  1. Cliquez sur "Installer l'app"
  2. Confirmez l'installation
  3. L'app est maintenant installée et vous pouvez récupérer les tokens

5. Configuration Shopify - Où trouver chaque valeur

Maintenant que votre application est créée, voici exactement où récupérer chaque valeur :

Champ Dolibarr Où trouver la valeur dans Shopify Format exact Exemple
Nom d'hôte boutique Shopify * URL de votre boutique (barre d'adresse) monshop.myshopify.com
(SANS https://)		 boutique-test.myshopify.com
Jeton d'accès Shopify * Apps → Développer des apps → [Votre app] → Jetons d'accès API → "Admin API access token" shpat_xxxxxxxxxxxxxxxxxxxxxxxx shpat_1a2b3c4d5e6f7g8h9i0j
Clé API Shopify * Apps → Développer des apps → [Votre app] → Identifiants de l'API → "API key" Chaîne alphanumérique abc123def456ghi789
Clé secrète API Shopify * Apps → Développer des apps → [Votre app] → Identifiants de l'API → "API secret key" Chaîne alphanumérique secrète shpss_xyz789abc123def456
ID de localisation Shopify * Paramètres → Emplacements → Copiez l'ID de votre emplacement principal Nombre entier 123456789
Vendeur Shopify Nom de votre marque/entreprise (optionnel) Texte libre Ma Boutique
Attention aux formats :
  • Nom d'hôte : SANS "https://" au début
  • Jeton d'accès : Commence généralement par "shpat_"
  • Clé secrète : Commence généralement par "shpss_"
  • ID localisation : Nombre uniquement, pas de texte

Comment récupérer l'ID de localisation

  1. Dans Shopify Admin, allez dans Paramètres → Emplacements
  2. Cliquez sur votre emplacement principal (généralement celui avec votre adresse)
  3. L'ID se trouve dans l'URL : .../locations/123456789
  4. Copiez uniquement les chiffres : 123456789

6. Configuration Dolibarr - Paramètres automatiques et manuels

Champ Comment obtenir la valeur Remarques
Clé API Dolibarr * Généré automatiquement par le module Si vous n'en avez pas : Menu → Utilisateurs & Groupes → [Votre utilisateur] → Onglet API → Générer
URL hôte Dolibarr * Détecté automatiquement Ex: https://votredomaine.com/dolibarr
Catégorie produits Dolibarr * Menu → Produits/Services → Catégories → Sélectionnez votre catégorie Seuls les produits de cette catégorie seront synchronisés

Paramètres de synchronisation

Paramètre Valeur recommandée Explication
Maximum commandes par sync 10 Limite le nombre de commandes traitées à chaque fois
Produits par cycle cron 10 Nombre de produits mis à jour par cycle automatique

7. Configuration synchronisation des produits

Options de synchronisation disponibles

Option Description Recommandation
Synchroniser les prix Envoie les prix Dolibarr vers Shopify Activé - Essentiel pour e-commerce
Niveau de prix (si multiprix) Quel niveau de prix Dolibarr utiliser Niveau 1 généralement
Synchroniser descriptions Envoie les descriptions produits Activé - Important pour SEO
Synchroniser images Envoie les images produits Activé - Indispensable
Synchroniser stocks Met à jour les quantités en stock Activé - Évite la survente
Utiliser stock virtuel Stock réel - commandes + commandes fournisseur Activé - Plus précis
Astuce : Activez toutes les options pour une synchronisation complète. Vous pourrez les désactiver individuellement plus tard si besoin.

8. Configuration synchronisation des commandes

Paramètres requis

Champ Où le configurer dans Dolibarr Exemple
Préfixe commandes Texte libre (ex: SHOP-) SHOP-
Origine commande Menu → Configuration → Dictionnaires → Origine des propositions commerciales/commandes Internet
Conditions de paiement Menu → Configuration → Dictionnaires → Conditions de règlement Paiement à réception
Méthode expédition par défaut Menu → Configuration → Dictionnaires → Moyens de transport Colissimo
Produit pour frais de port Menu → Produits/Services → Créer un service "Frais de port" Service avec ref PORT001
Entrepôt par défaut Menu → Stocks → Entrepôts/magasins Votre entrepôt principal
Compte bancaire Menu → Banque → Comptes financiers Votre compte principal

Créer le produit "Frais de port"

  1. Menu → Produits/Services → Nouveau produit/service
  2. Type : Service
  3. Référence : FRAIS-PORT
  4. Libellé : Frais de port
  5. Prix : 0 (sera calculé automatiquement)
  6. Cliquez sur Créer

8.1 Import historique des commandes v2.0.24

Nouvelle fonctionnalité v2.0.24 : Import historique avec pagination intelligente pour traiter des milliers de commandes sans limitation !

L'import historique permet d'importer automatiquement toutes vos commandes Shopify antérieures lors de la première installation du module.

Configuration

Champ Description Exemple
Activer l'import historique Case à cocher pour déclencher l'import au prochain CRON ☑️ Activé
Date de début Date à partir de laquelle importer (optionnel) 01/01/2024
Date de fin Date jusqu'à laquelle importer (optionnel) 31/12/2024
Import terminé Indique si l'import est complété ✅ Terminé le 02/08/2025

🚀 Fonctionnement de la pagination intelligente v2.0.24

  1. Traitement par lots : Le système traite 10-50 commandes par page selon votre configuration
  2. Pagination automatique : Continue automatiquement sur toutes les pages disponibles
  3. Reprise automatique : En cas d'interruption, reprend là où il s'était arrêté
  4. Désactivation automatique : Se désactive automatiquement une fois terminé
Sans limitation : Peut traiter des milliers de commandes en tranches successives de 1000 commandes maximum par session CRON.
À savoir :
  • L'import se lance automatiquement au prochain CRON après activation
  • Les commandes existantes sont automatiquement ignorées
  • Pour les gros catalogues, surveillez les logs Dolibarr
  • La pagination permet de traiter n'importe quel volume sans échec

9. Configuration des tâches automatiques (Cron)

Important : Les tâches cron sont désactivées par défaut pour la sécurité. Vous devez les activer manuellement.

Tâches à configurer

Tâche Fréquence recommandée Description
Synchronisation produits Toutes les heures Met à jour les produits et stocks
Import commandes Toutes les 15 minutes Récupère les nouvelles commandes Shopify

Activation des tâches cron

  1. Menu → Outils → Tâches programmées
  2. Recherchez les tâches "ShopifyIntegration"
  3. Pour chaque tâche :
    • Cliquez sur Modifier
    • Activez "Statut : Activé"
    • Configurez la fréquence
    • Cliquez sur Modifier
Test : Vous pouvez tester une tâche en cliquant sur le bouton "Exécuter maintenant" à côté de chaque tâche.

10. Mise à jour du module

Comment mettre à jour le module Shopify Integration vers une nouvelle version depuis le DoliStore.

Important : La procédure de désactivation/réactivation est obligatoire pour que les scripts de mise à jour SQL s'exécutent correctement.

Procédure de mise à jour

1. Télécharger la nouvelle version

  1. Rendez-vous sur le DoliStore
  2. Connectez-vous avec votre compte
  3. Téléchargez la dernière version du module (fichier ZIP)
  4. Conservez le fichier ZIP sur votre ordinateur

2. Désactiver le module actuel

  1. Dans Dolibarr : Menu → Configuration → Modules/Applications
  2. Recherchez "Shopify Integration"
  3. Cliquez sur "Désactiver" (bouton rouge)
  4. Confirmez la désactivation

3. Installer la nouvelle version

  1. Restez dans Menu → Configuration → Modules/Applications
  2. Cliquez sur "Déployer/Installer un module externe"
  3. Cliquez sur "Parcourir" et sélectionnez le fichier ZIP téléchargé
  4. Cliquez sur "Envoyer le fichier"
  5. Suivez les instructions d'installation

4. Réactiver le module

  1. Une fois l'installation terminée, recherchez "Shopify Integration"
  2. Cliquez sur "Activer" (bouton vert)
  3. Vérifiez que le numéro de version affiché correspond à la nouvelle version
  4. Les scripts SQL de mise à jour s'exécutent automatiquement lors de la réactivation
Vérification :
  • Le numéro de version affiché dans la liste des modules doit correspondre à la nouvelle version
  • Consultez les logs Dolibarr pour vous assurer que les scripts SQL se sont exécutés sans erreur
  • Testez les fonctionnalités principales (synchronisation manuelle, configuration)

Méthode alternative : Via l'onglet DoliStore

Alternative rapide : Vous pouvez aussi essayer l'onglet "Modules disponibles depuis DoliStore" qui permet parfois la mise à jour automatique directe, mais la méthode ci-dessus reste plus fiable.
En cas de problème : Restaurez la sauvegarde de l'ancien dossier et contactez le support. Ne jamais laisser le module dans un état partiellement mis à jour.

11. Résolution de problèmes courants

Erreurs de connexion Shopify

Erreur : "Connection failed" ou "Access denied"
Cause : Mauvaises informations d'API
Solution :
  • Vérifiez le nom d'hôte (sans https://)
  • Régénérez le jeton d'accès Shopify
  • Vérifiez que l'app est bien installée
  • Contrôlez tous les scopes nécessaires

Produits non synchronisés

Erreur : "Aucun produit synchronisé"
Cause : Problème de catégorie ou statut
Solution :
  • Vérifiez que vos produits sont dans la bonne catégorie
  • Statut produit = "En vente"
  • Produit pas archivé

Commandes non importées

Erreur : "No orders found"
Cause : Configuration incomplète
Solution :
  • Complétez tous les champs obligatoires de l'onglet "Commandes"
  • Vérifiez que le compte bancaire existe
  • Créez le produit "Frais de port"

Où trouver les logs

Menu → Outils → Dolibarr Log Recherchez : "ShopifyIntegration"

Support technique

Si vous n'arrivez pas à résoudre votre problème :

🎉 Félicitations !

Votre intégration Shopify-Dolibarr est maintenant configurée. Vous pouvez tester la synchronisation via l'interface de synchronisation manuelle.

Retour à l'accueil Évaluer le module