Documentation complète

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

Table des matières

0. Obtenir une licence

Étape 1 : Installer l'application Doli2Shop

Accédez à doli2shop.ptitetete.org/shopify-app/ et installez l'application dans votre boutique Shopify.

Étape 2 : Choisir votre abonnement

  • Annuel (recommandé) : 250€ HT/an - Économisez 50€
  • Mensuel : 25€ HT/mois - Sans engagement
Déjà client DoliStore ?
Choisissez "J'ai déjà une licence" et entrez votre numéro de série (SI-XXXX-XXXX-XXXX) pour continuer avec votre licence existante jusqu'à son expiration.

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 18.0 à 22.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. Installation de l'application Doli2Shop dans Shopify

Nouveau ! Application officielle Shopify - Doli2Shop utilise maintenant une application partenaire officielle, plus simple et plus sécurisée que les anciennes applications privées.

Pourquoi une application Shopify ?

L'utilisation d'une application partenaire officielle Shopify offre plusieurs avantages majeurs :

  • 🔐 Sécurité OAuth 2.0 : Authentification sécurisée conforme aux standards Shopify, sans partage de clés API sensibles
  • ✅ Conformité Shopify : Application vérifiée et approuvée par Shopify, respectant toutes leurs exigences de sécurité
  • 🚀 Installation simplifiée : En quelques clics depuis l'App Store Shopify, sans configuration technique complexe
  • 🔄 Mises à jour automatiques : Les permissions et fonctionnalités sont automatiquement maintenues à jour
  • 📊 Accès API complet : Toutes les permissions nécessaires sont pré-configurées (produits, commandes, clients, stocks)

Tutoriel vidéo d'installation

Regardez cette vidéo pour voir le processus d'installation complet étape par étape :

Regarder le tutoriel d'installation

Étapes d'installation

Étape 1 : Accéder à l'App Store Shopify

  1. Connectez-vous à votre administration Shopify
  2. Dans le menu de gauche, cliquez sur "Apps"
  3. Cliquez sur "Shopify App Store" ou recherchez directement dans le store
  4. Ou accédez directement via le lien : Doli2Shop sur le Shopify App Store

Étape 2 : Trouver et installer Doli2Shop

  1. Recherchez "Doli2Shop - ERP Integration" dans l'App Store
  2. Ou utilisez le lien direct fourni par le support
  3. Cliquez sur "Ajouter l'application"
  4. Acceptez les permissions demandées (produits, commandes, clients, stocks)

Étape 3 : Configuration dans l'application

  1. Une fois l'app installée, suivez l'assistant de configuration
  2. Entrez l'URL de votre Dolibarr (ex: https://votredomaine.com/dolibarr)
  3. L'application génère automatiquement vos identifiants API
  4. Notez précieusement les informations affichées :
    • Access Token (commence par shpat_...)
    • API Key
    • API Secret

Étape 4 : Reporter les informations dans Dolibarr

  1. Retournez dans Dolibarr → ShopifyIntegration → Configuration
  2. Collez les informations obtenues dans les champs correspondants
  3. Cliquez sur "Enregistrer"
Important : L'Access Token n'est affiché qu'une seule fois lors de l'installation. Si vous le perdez, vous devrez désinstaller et réinstaller l'application pour en obtenir un nouveau.

Permissions automatiquement configurées

L'application Doli2Shop configure automatiquement toutes les permissions nécessaires :

Scope Permission Utilisation
read_products / write_products Lecture/Écriture Synchronisation des produits Dolibarr ↔ Shopify
read_orders / write_orders Lecture/Écriture Import des commandes Shopify vers Dolibarr
read_customers / write_customers Lecture/Écriture Création automatique des clients
read_inventory / write_inventory Lecture/Écriture Synchronisation des stocks en temps réel
read_locations Lecture Gestion des emplacements de stock
read_fulfillments / write_fulfillments Lecture/Écriture Synchronisation des expéditions

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"

🚨 Permissions Shopify manquantes - CRITIQUE

Symptôme : Les commandes ne se synchronisent plus depuis plusieurs jours, le CRON retourne une erreur (-1)
Cause : Permissions WRITE manquantes dans votre application Shopify
Diagnostic rapide :
  1. Allez dans Menu ShopifyIntegration → Configuration → Diagnostic système
  2. Regardez la section "Shopify API Permissions"
  3. Si vous voyez des lignes avec status: "error" → Permissions manquantes !

📝 Permissions requises (9 minimums)

Permission Type Obligatoire Fonction
read_products READ ✅ OUI Lire les produits
write_products WRITE ✅ OUI Créer/modifier produits
read_inventory READ ✅ OUI Lire les stocks
write_inventory WRITE ✅ OUI Mettre à jour stocks
read_orders READ ✅ OUI Lire les commandes
write_orders WRITE ✅ OUI Modifier commandes
read_customers READ ✅ OUI Lire les clients
write_customers WRITE ✅ OUI Créer des clients
read_locations READ ✅ OUI Lire emplacements
write_publications WRITE ⚠️ Recommandé Publier produits sur canaux vente
write_files WRITE ⚠️ Recommandé Synchroniser images

🔧 Procédure de correction étape par étape

  1. Accéder à votre application Shopify :
    • Admin Shopify → Settings → Apps and sales channels
    • Cliquez sur "Develop apps"
    • Sélectionnez votre application Dolibarr
  2. Modifier les permissions :
    • Onglet "Configuration"
    • Section "Admin API access scopes" → Cliquez "Edit"
  3. Cocher TOUTES les permissions manquantes (voir tableau ci-dessus)
  4. Enregistrer et réinstaller :
    • Cliquez "Save"
    • ⚠️ IMPORTANT : Cliquez "Reinstall app" pour activer les nouveaux scopes
  5. Récupérer le nouveau token :
    • Onglet "API credentials"
    • Section "Admin API access token"
    • Cliquez "Reveal token once" et copiez-le
    • ⚠️ Vous ne pourrez plus le voir après !
  6. Mettre à jour Dolibarr :
    • Menu ShopifyIntegration → Configuration → Setup
    • Champ "Jeton d'accès Shopify" → Collez le nouveau token
    • Cliquez "Enregistrer"
  7. Vérifier la correction :
    • Menu ShopifyIntegration → Configuration → Diagnostic système
    • Toutes les permissions doivent afficher status: "ok"
    • Testez une synchronisation manuelle des commandes
⚠️ Erreur fréquente : Avoir uniquement les permissions READ ne suffit PAS ! Le module a absolument besoin des permissions WRITE pour fonctionner correctement (créer produits, mettre à jour stocks, ajouter notes aux commandes, etc.).
Documentation complète : Pour plus de détails, consultez le guide technique complet dans /docs/troubleshooting/SHOPIFY_PERMISSIONS.md de votre installation.

Problèmes d'endpoints API Dolibarr

Erreur : "Endpoint non trouvé (404)" ou "Bad Request (400)"
Causes possibles :
  • Module API/Web Services désactivé : Menu → Configuration → Modules → Rechercher "API" → Activer
  • Version Dolibarr trop ancienne : Certains endpoints nécessitent Dolibarr 14+
  • Permissions utilisateur insuffisantes : L'utilisateur API doit avoir les droits complets
  • Fichier de test manquant : Pour documents/download, c'est normal si aucun logo d'entreprise n'existe

Configuration des permissions utilisateur API

  1. Menu → Configuration → Utilisateurs & Groupes
  2. Cliquez sur votre utilisateur API
  3. Onglet "Permissions"
  4. Accordez ces permissions minimales :
    • ✅ API : Accès complet aux API
    • ✅ Documents : Lire les documents
    • ✅ Produits/Services : Lire les produits
    • ✅ Tiers : Lire/créer les clients
    • ✅ Commandes : Lire/créer les commandes
  5. Cliquez sur "Sauvegarder"
Note importante : L'erreur 404 sur "documents/download" est normale si aucun logo d'entreprise n'existe. Cela n'affecte pas la synchronisation Shopify.

Explorer et tester l'API Dolibarr

Dolibarr fournit un explorateur API intégré pour tester et documenter tous les endpoints disponibles :

  1. URL de l'explorateur : https://votredomaine.com/dolibarr/api/index.php/explorer
  2. Documentation Swagger : https://votredomaine.com/dolibarr/api/index.php/explorer/swagger.json?DOLAPIKEY=votre_cle_api
  3. Remplacez votredomaine.com/dolibarr par votre vraie URL Dolibarr
  4. Remplacez votre_cle_api par votre clé API utilisateur

Cet outil vous permet de :

  • ✅ Tester tous les endpoints API en direct
  • ✅ Voir la documentation complète de chaque endpoint
  • ✅ Vérifier les paramètres requis et optionnels
  • ✅ Diagnostiquer les problèmes d'API directement
Paramètres API critiques selon documentation Swagger :
  • GET /documents : Paramètre modulepart obligatoire (ex: product, company, user)
  • GET /documents/download : Paramètre modulepart obligatoire + original_file optionnel
  • GET /status : Endpoint de base (non documenté dans Swagger mais fonctionnel)

Note : Les erreurs 400 (Bad Request) indiquent généralement des paramètres manquants ou invalides.

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