Module Shopify Sync

Shopify Sync est un module complémentaire pour Dolibarr ERP/CRM qui assure une synchronisation bidirectionnelle quasi temps réel entre Shopify et Dolibarr : commandes, clients, remboursements, produits et variantes, stock et expéditions. Le module dialogue directement avec l'API GraphQL Admin de Shopify : sans SaaS intermédiaire, sans abonnement supplémentaire.

Éditeur	arcchester
Version	1.8.1
Licence	GPL v3
Compatibilité Dolibarr	18.0 à 24.x (validé sur 18.0.5, 20.0.4 et 24.0.0)
PHP	7.4 minimum (extension cURL), validé jusqu'à 8.2
Dépendances	Aucune (cURL pur : pas de Composer, pas de SDK)
Version d'API Shopify	2026-01 par défaut, configurable ; appels vérifiés sur 2025-07, 2025-10, 2026-01, 2026-04, 2026-07 et unstable
Distribution	Fiche sur le Dolistore

La fréquence effective dépend des tâches planifiées, de l’hébergement et des limites de l’API Shopify. Une boutique Shopify est configurée par entité Dolibarr.

Fonctionnalités

Commandes Shopify → Dolibarr : client (ou client invité), commande à la date de la vente, lignes reliées aux fiches produits, remises, frais de port, contact de livraison si l'adresse diffère ; facture dès que la commande est payée, même après son import.
Prix TTC ou HT : le module lit le réglage « taxes incluses » de la boutique, les montants importés correspondent à ce que le client a payé.
Annulations Shopify répercutées sur la commande Dolibarr.
Remboursements → avoirs Dolibarr : partiel (montant réellement rendu) ou total (avoir miroir ligne à ligne).
Expéditions Dolibarr → Shopify : articles et quantités expédiés, numéro de suivi et transporteur ; expéditions partielles gérées. En option, l'inverse : une étiquette imprimée dans Shopify crée et valide l'expédition Dolibarr.
Produits dans les deux sens, avec une source de vérité configurable (produits, prix, stock).
Catalogue existant : rattachement par SKU des variantes Shopify aux fiches Dolibarr existantes, sans produit parent ni module Variants.
Produits à variantes (module Variants) : les attributs Dolibarr deviennent des options Shopify, une variante par combinaison. Limites de la boutique lues à l'exécution (2 048 variantes, 3 options).
Stock multi-emplacements : table « entrepôts Dolibarr = emplacement Shopify », ou un emplacement unique alimenté par les entrepôts choisis.
Metafields : attributs supplémentaires et champs standards (poids, dimensions, volume) publiés vers Shopify, avec conversion de type et d'unité.
Catégories, images, poids : collections et tags Shopify, menu de navigation, images des fiches, poids d'expédition (options).
Webhooks signés HMAC pour le quasi temps réel, doublés d'une réconciliation planifiée qui rattrape commandes, paiements, annulations et remboursements manqués.
File d'attente asynchrone : limites de débit de l'API absorbées, nouvelles tentatives sûres, aucun job traité deux fois.
Anti-boucle par empreinte d'état, et résolution de conflits configurable.
Tableau de bord : file d'attente, échecs, journal ; traiter la file maintenant, relancer les échecs, rattraper les commandes des N derniers jours.
Encart « État Shopify » sur les fiches produit et commande, avec bouton « Synchroniser ».
Bouton « Tester la connexion » : contrôles de configuration, droits, emplacements, webhooks et tâches planifiées, chacun avec le correctif suggéré.
Diagnostic opérationnel : état de connexion et du planificateur, suivi par flux, causes et conseils, historique, relances ciblées et export de diagnostic sans secrets (depuis la 1.6.0).
Assistant de configuration initiale : six étapes pour relier Shopify, choisir le catalogue, vérifier les SKU, associer les entrepôts et préparer un premier lot avec aperçu (depuis la 1.7.0).
Sélection du catalogue : plusieurs branches autorisées, exclusions prioritaires et aperçu complet sans synchroniser (1.8.0, facultatif).
Validation des produits : condition par champ booléen, contrôlée avant mise en file et au traitement (1.8.0, facultatif).
Ordre des photos : reprise des positions Dolibarr et réordonnancement des médias existants, sans renvoyer les images inchangées (1.8.0, facultatif).
Interface du module en français et en anglais.

Ce qui est synchronisé, flux par flux

Chaque flux s'active ou se coupe indépendamment dans la configuration (carte « Flux synchronisés »).

Commandes (Shopify → Dolibarr)

Événement Shopify	Effet dans Dolibarr
Commande créée	Tiers retrouvé par e-mail (sinon créé, avec l'adresse de facturation et le pays) ; commande datée du jour de la vente, référence client = numéro Shopify ; une ligne par article, reliée à la fiche par la variante ou le SKU ; remises ; ligne « Frais de port » ; contact de livraison si l'adresse diffère. La commande reste en brouillon (validation automatique en option).
Commande payée (tout de suite ou plus tard)	Facture créée depuis la commande et validée ; règlement enregistré en option (mode de paiement et compte bancaire au choix).
Commande annulée	Commande Dolibarr annulée, sauf si une expédition est déjà en cours.
Commande de test (passerelle de test Shopify)	Importée et signalée comme telle ; peut être ignorée par option.

Un tiers existant n'est jamais renommé par une commande : seuls les champs vides sont complétés.

Ventes sans client (caisse Shopify POS, commandes anonymes) : portées par un seul tiers, choisi dans la configuration, ou « Client comptoir (Shopify) » créé automatiquement. Le code client est attribué par la numérotation Dolibarr, y compris quand il est obligatoire.

Clients (dans les deux sens)

Shopify → Dolibarr : un client créé ou modifié met à jour son tiers (nom, e-mail, adresse, téléphone, pays, province). Une raison sociale Shopify devient le nom du tiers.
Dolibarr → Shopify : un tiers client créé ou modifié est publié (prénom, nom, e-mail, téléphone). Un tiers sans e-mail ni téléphone n'est pas publié (exigence Shopify).
Client supprimé sur Shopify : le lien est retiré, le tiers Dolibarr est conservé.

Produits (dans les deux sens)

Sens	Création	Modification
Dolibarr → Shopify (source de vérité produits = Dolibarr)	Produit Shopify avec titre, description, prix, SKU (= référence), code-barres, suivi de stock, statut actif si la fiche est en vente, sinon brouillon. Publication sur la Boutique en ligne en option.	Titre, description et metafields. Prix, SKU et code-barres seulement si l'option « Réaligner prix, SKU et code-barres » est cochée ; statut seulement si « Suivre en vente » est cochée.
Shopify → Dolibarr	Fiche Dolibarr (référence = SKU, libellé, prix, code-barres, statut) ; une fiche par variante pour un produit à plusieurs variantes. Si le SKU correspond à une référence existante, la fiche est rattachée sans être modifiée.	Libellé. Prix seulement si Shopify est source de vérité des prix ; statut et code-barres seulement si Shopify est source de vérité des produits.

Produit supprimé sur Shopify : liens retirés, fiche Dolibarr conservée, jamais recréée d'office (un export manuel peut la recréer si les flux, la source et les conditions de publication l’autorisent).
Fiche rattachée par SKU : utilisée pour les commandes et le stock ; son titre, sa description et son prix ne sont jamais réécrits.
Prix envoyé à Shopify : HT de la fiche par défaut (fonctionnement historique), ou TTC si la boutique est en TTC (option « selon la boutique »).

Catégories, images et champs produit (Dolibarr → Shopify, options)

Catégories : chaque catégorie produit devient une collection Shopify, un tag, ou les deux. Le produit rejoint et quitte les collections selon ses catégories ; une collection parente peut contenir les produits de ses sous-catégories ; une catégorie renommée ou supprimée entraîne sa collection.
Menu de navigation construit sur l'arborescence, jusqu'à 3 niveaux (limite Shopify), reconstruit seulement quand l'arborescence change. Droits read_online_store_navigation et write_online_store_navigation.
Images de l'onglet « Fichiers joints » envoyées dans les médias du produit : ajout, remplacement quand le fichier change, retrait quand il disparaît, sans doublon.
Metafields : un attribut supplémentaire ou un champ standard (@weight, @length, @width, @height, @surface, @volume) publié avec conversion de type et d'unité (texte riche, poids, dimension, volume, nombres, dates, listes). Une valeur vidée efface le metafield ; une valeur refusée par Shopify n'empêche pas les autres et le job apparaît en échec.
Poids d'expédition : le poids Dolibarr publié sur la variante Shopify, pour le calcul des frais de port.
Produit supprimé dans Dolibarr : passé en brouillon ou archivé sur Shopify, jamais supprimé.

Le module ne touche qu'à ce qu'il a créé : une collection, un tag ou une image ajoutés à la main sur Shopify ne sont jamais retirés.

Stock (sens selon la source de vérité)

Source de vérité Dolibarr : chaque mouvement de stock publie la quantité des entrepôts choisis sur l'emplacement Shopify correspondant (écriture « comparer puis écrire », conforme aux API 2026-04 et suivantes). Les niveaux Shopify sont ignorés : l'expédition Dolibarr sortira le stock vendu.
Source de vérité Shopify : un niveau modifié sur Shopify ajuste l'entrepôt Dolibarr associé à l'emplacement.
Quantité échangée : physique publiée par défaut ; « Physique » dans les deux sens, ou « Disponible » si Dolibarr décrémente le stock dès la validation de commande (le diagnostic le suggère).

Expéditions (Dolibarr → Shopify)

À la validation d'une expédition liée à une commande Shopify, la commande passe « expédiée » sur Shopify pour les articles et quantités réellement expédiés (expéditions partielles comprises).
Numéro de suivi et transporteur (d'après le mode d'expédition) transmis ; Shopify envoie au client son e-mail d'expédition (désactivable).
Une expédition n'est jamais déclarée deux fois ; les expéditions de commandes qui ne viennent pas de Shopify sont ignorées.
Le stock d'un article expédié est publié après la déclaration de l'expédition, pour que Shopify ne le décompte pas deux fois.

Étiquettes imprimées dans Shopify (Shopify → Dolibarr, option)

Pour les boutiques qui impriment leurs étiquettes dans Shopify (Chronopost, Colissimo, Shopify Shipping) tout en gardant Dolibarr seul maître du stock, par exemple un entrepôt partagé avec le B2B :

Chaque expédition Shopify crée et valide l'expédition Dolibarr de la commande (importée au passage si besoin), avec le numéro de suivi et le transporteur.
L'entrepôt est celui de l'emplacement Shopify expéditeur (table entrepôts = emplacement).
La validation sort le stock dans Dolibarr, qui le repousse vers Shopify : les sorties B2B ne sont jamais écrasées.
Jamais plus que le reste à expédier de chaque ligne ; étiquettes antérieures à l'activation ignorées ; étiquette annulée sur Shopify = expédition annulée et stock remis.
Prérequis : module Expéditions et « Décrémenter le stock réel à la validation des expéditions » dans le module Stocks (contrôlés par le diagnostic).

Remboursements (Shopify → Dolibarr)

Remboursement partiel : avoir limité au montant réellement remboursé, avec répartition par taux lorsque le détail des lignes remboursées est disponible. Vérifier les taux et les frais de port pour un remboursement récupéré sans détail par réconciliation.
Remboursement total : avoir reprenant chaque ligne de la facture.
L'avoir reste en brouillon par défaut (validation en option). Un remboursement arrivé avant sa commande ou sa facture est mis en attente ; si la facture reste absente, il passe dans les reprises puis devient visible en échec si le problème persiste.

Architecture

Webhook Shopify ─┐                          ┌─ Trigger Dolibarr
                 ▼                          ▼
            [ JobQueue ] ── cron process_queue ── [ SyncEngine ]
                 │                                     │
          [ MappingRepository ]                 [ Mappers × 6 ]
        (id ↔ id + hash anti-boucle)      (Order / Customer / Refund /
                                           Product / Inventory / Fulfillment)

Prérequis

Modules Dolibarr Produits, Commandes et Tiers actifs ; Stocks, Expéditions et Factures selon les flux utilisés.
Une application Shopify disposant des droits Admin API (products, orders, inventory, customers, fulfillments, locations ; read_publications et write_publications pour publier les nouveautés sur la Boutique en ligne ; read_online_store_navigation et write_online_store_navigation pour le menu). Selon son type, elle fournit un jeton shpat_… à coller, ou un client ID et un client secret avec lesquels le module obtient et renouvelle le jeton lui-même.
Pour le temps réel : un endpoint webhook HTTPS public. Voir ci-dessous le fonctionnement sans webhook.

Installation et mise à jour

Sauvegarder la base de données, les documents et la configuration du module.
Télécharger module_shopifysync-1.8.1.zip depuis la fiche DoliStore.
Dans Dolibarr : Accueil → Configuration → Modules/Applications → Déployer/installer un module externe, ou remplacer le dossier custom/shopifysync.
Installer le nouveau code avant de désactiver l’ancienne version. Les versions antérieures à la 1.7.3 pouvaient effacer leurs réglages à la désactivation.
Activer le module pour une première installation ; pour une mise à jour depuis une version antérieure à la 1.8.0, le désactiver puis le réactiver après le remplacement du code. Cette étape enregistre le hook de déplacement des photos et crée les tables manquantes des anciennes évolutions. Depuis la 1.7.3, identifiants, correspondances et flux désactivés sont conservés.
Vérifier la configuration, tester la connexion et contrôler l’inscription des webhooks ainsi que les tâches planifiées.
Tester les flux habituels sur un environnement de recette avant leur activation en production.

Compatibilité des réglages : le filtre de catégories, la condition de validation et la synchronisation de l’ordre des photos restent désactivés par défaut. Aucun export massif n’est lancé lors de leur enregistrement. La 1.8.0 n’ajoute pas de nouvelle table par rapport à une 1.7.3 complète. Des réglages déjà effacés par une ancienne version doivent être restaurés depuis une sauvegarde ou saisis à nouveau.

Configuration

Créer l'application Shopify et l'installer sur la boutique. ⚠️ Depuis le 1er janvier 2026, Shopify ne permet plus de créer une application personnalisée depuis l'admin (celles qui affichent un jeton shpat_… à copier) ; les installations existantes continuent de fonctionner sans rien changer, et une nouvelle installation passe par le Dev Dashboard.
Choisir le mode d'authentification dans la carte « Connexion » :
- Jeton permanent collé : mode par défaut et historique : coller le jeton shpat_… d'une application personnalisée créée avant 2026. Rien ne change pour les installations en service.
- Client ID et secret : pour une application et une boutique appartenant à la même organisation Shopify : saisir le client ID et le client secret de l'application du Dev Dashboard ; le module obtient un jeton valable 24 heures et le renouvelle seul.
- Autorisation Shopify : installation par le flux d'autorisation : déclarer comme redirect URL de l'application l'adresse affichée dans la configuration (…/custom/shopifysync/oauth/callback.php), puis cliquer sur « Se reconnecter ». Le module reçoit un jeton d'une heure et un jeton de rafraîchissement de 90 jours, tous deux renouvelés automatiquement.
Connexion : domaine de la boutique, jeton (ou client ID et secret), app secret, version d'API.
Stock : emplacement Shopify et entrepôts, ou table « entrepôts = emplacement » (une règle par ligne, ex. 23 = gid://shopify/Location/85613641922).
Choisir les flux et les sources de vérité, puis cliquer sur « Inscrire les webhooks ».
Catalogue déjà en place des deux côtés : « Rattacher les variantes par SKU ».
Historique à reprendre : tableau de bord → « Rattraper les commandes des N derniers jours ».
Activer les tâches planifiées Dolibarr : traitement de la file et réconciliation.

Depuis la 1.7.1, les champs de connexion s’affichent ou se masquent selon le mode choisi, sans effacer les identifiants déjà enregistrés. Enregistrer le nouveau mode avant d’utiliser la reconnexion. Le secret de signature des webhooks reste commun aux modes.

Références Shopify : authentification dans la même organisation, durées des jetons.

Jetons d'accès et échéances Shopify

Un jeton expirable est renouvelé avant son échéance (marge de deux minutes) et immédiatement si Shopify le refuse en cours de route : la requête est alors rejouée avec le jeton neuf. La réconciliation nocturne force en plus un renouvellement, car un jeton de rafraîchissement inutilisé pendant 90 jours expire : une boutique calme perdrait sa connexion sans prévenir. L'écran de diagnostic affiche le mode, l'échéance du jeton et alerte quand le rafraîchissement approche de sa fin.

Deux échéances Shopify à ne pas confondre :

1er janvier 2026 : plus aucune création d'application personnalisée depuis l'admin Shopify. Concerne les nouvelles installations, qui passent par le Dev Dashboard.
1er janvier 2027 : jetons expirables obligatoires pour les applications publiques de l'App Store. Les applications personnalisées et celles créées par le marchand ne sont pas visées : une installation existante n'a rien à faire.

L'URL de retour d'autorisation est protégée par trois contrôles avant tout enregistrement : signature HMAC de Shopify, jeton d'état à usage unique valable 15 minutes, et domaine de boutique identique à celui configuré.

Assistant de configuration initiale (depuis la 1.7.0)

L’onglet Assistant d’installation facilite la configuration du lien Shopify après l’installation du module. Il est facultatif et ne remplace pas le déploiement du ZIP.

Connexion : tester un jeton permanent ou des identifiants Client ID/secret ; une connexion OAuth déjà configurée peut être réutilisée. Une nouvelle autorisation OAuth se prépare dans la Configuration.
Catalogue : choisir l’import Shopify, l’export de produits simples Dolibarr ou le rattachement de deux catalogues existants par SKU.
Correspondances SKU : analyser les références absentes, doublons et ambiguïtés avant de créer des liens.
Entrepôts : associer un entrepôt à un emplacement Shopify, ou conserver les correspondances avancées existantes.
Facturation : vérifier les modules, options, moyen de paiement et compte bancaire, sans créer de facture ni de règlement.
Aperçu et démarrage : examiner les changements de réglages et sélectionner explicitement les opérations du premier lot (20 au maximum).

Les choix restent dans un brouillon privé pendant une heure. Aucun réglage actif n’est enregistré avant la confirmation. L’aperçu expire après 10 minutes et doit être recalculé si le catalogue ou les réglages changent. La confirmation crée les liens et les jobs ; la file habituelle effectue ensuite les échanges.

Catalogue déjà existant : le rattachement par SKU conserve la gestion des fiches dans les catalogues existants et désactive leur synchronisation. Les liens servent notamment aux commandes et aux stocks. Les photos et champs de ces produits restent gérés dans Shopify.

Limites : l’assistant analyse au plus 2 000 variantes Shopify et 2 000 fiches Dolibarr ; au-delà, utiliser les outils avancés. Les combinaisons Dolibarr complexes sont également orientées vers ces outils. Les traitements déjà en attente ou en cours doivent être terminés avant confirmation. Vérifier séparément les webhooks et tâches planifiées ; l’assistant ne suspend pas les automatismes existants.

Sélection des catégories à exporter (1.8.0)

Dans Configuration → Catalogue → Périmètre du catalogue, ouvrir Configurer et prévisualiser. Le filtre est désactivé par défaut.

Cocher Activer le filtre par catégories pour les exports vers Shopify.
Choisir au moins une branche avec Autoriser la branche. Plusieurs branches peuvent être sélectionnées.
Choisir, si nécessaire, des branches avec Exclure la branche.
Cliquer sur Prévisualiser sans synchroniser pour examiner les compteurs et motifs avant d’enregistrer.
Enregistrer lorsque le périmètre correspond au catalogue souhaité.

Chaque sélection inclut la catégorie choisie et ses descendants actuels et futurs. Une exclusion est toujours prioritaire, même si le produit appartient aussi à une branche autorisée. Un produit sans branche autorisée voit son export suspendu.

Exemple : autoriser « Maison » et « Jardin », puis exclure « Usage interne ». Les sous-catégories de Maison et Jardin sont incluses. Un produit classé à la fois dans Maison et Usage interne reste exclu. Il n’est pas nécessaire de sélectionner les catégories internes situées hors des branches autorisées pour les écarter.

Variantes : les catégories du parent déterminent l’inclusion ; une catégorie exclue sur le parent ou sur un enfant suspend l’export du groupe entier.

L’aperçu utilise les valeurs du formulaire sans enregistrer ni contacter Shopify. Il compte toutes les fiches de l’entité et présente 20 exemples par page, les causes de suspension et les fiches déjà reliées concernées. Les variantes sont comptées comme fiches : le total « Filtres satisfaits » ne garantit pas autant de créations Shopify, car les règles de SKU, variantes, sources et flux restent applicables. Cet aperçu complet est distinct de l’assistant limité à 2 000 fiches.

Condition de validation des produits (1.8.0)

Créer, si nécessaire, un attribut supplémentaire de produit de type booléen, par exemple « Prêt pour la boutique », dans la configuration des produits Dolibarr.
Dans Configuration → Catalogue → Exporter uniquement les produits validés, sélectionner ce champ et enregistrer. Par défaut, Aucun filtre de validation est sélectionné.
Cocher le champ sur les produits à exporter. Une case vide ou décochée suspend l’export du catalogue. Pour un produit à variantes, le parent et tous ses enfants doivent être validés.
Si un filtre de catégories est également actif, les deux conditions doivent être satisfaites.

La règle est vérifiée avant la mise en file, dans les exports manuels et de nouveau lors du traitement des jobs déjà présents. Un produit devenu non éligible pendant l’attente n’est pas exporté. Un champ supprimé, devenu non booléen ou illisible bloque l’export avec une erreur ; le filtre n’est pas ignoré silencieusement.

Effet des filtres sur les produits existants

Enregistrer les filtres ne lance aucun export massif et ne supprime ni ne dépublie les produits Shopify. Sortir un produit du périmètre ou décocher sa validation suspend ses prochaines mises à jour du catalogue ; le retirer de la vente est une action distincte.

Commandes, stocks et expéditions conservent leurs propres réglages. Le filtre concerne les exports du catalogue vers Shopify.
Pour reprendre un produit précédemment écarté, corriger sa catégorie ou sa validation, puis modifier sa fiche ou utiliser Synchroniser. Changer seulement les branches de configuration ou déplacer une branche entière ne lance pas un export massif.
Avec le filtre actif, les collections, tags et le menu configuré utilisent les branches sélectionnées à la place de la racine historique. Les collections existantes ne sont pas automatiquement supprimées et les produits suspendus conservent leurs associations déjà publiées.
Le menu configuré est reconstruit lors d’un prochain traitement catalogue qui le déclenche. La prévisualisation et l’enregistrement ne le modifient pas immédiatement.
Une catégorie sélectionnée supprimée ou inaccessible, ou une boucle dans la hiérarchie, bloque l’export jusqu’à correction. Désactiver le filtre rétablit les règles historiques, dont la racine de catégories conservée.
Les produits rattachés par SKU conservent leur catalogue géré dans Shopify.

Publication des produits et statut des variantes (1.8.1)

Disponible à partir de la version 1.8.1. Installer le ZIP 1.8.1 avant d’utiliser les fonctions ci-dessous.

La 1.8.1 corrige la publication des nouveaux produits à variantes sur la Boutique en ligne lorsque l’option « Publier sur la Boutique en ligne » est activée. Un produit déjà créé mais non publié peut être réparé avec le bouton Synchroniser, sans création d’un second produit Shopify. Les mises à jour ordinaires ne republient pas un produit volontairement retiré après une publication réussie.

L’option Suivre le statut en vente des variantes est désactivée par défaut. Elle permet de retirer de la Boutique en ligne un enfant Dolibarr hors vente, puis de le republier lorsqu’il est remis en vente. Les identifiants, quantités et autres variantes sont conservés.

Prérequis et activation :

Installer le ZIP 1.8.1 et effectuer la recette sur une boutique de test.
Utiliser un catalogue piloté par Dolibarr avec le module Variants. Les produits rattachés à un catalogue existant par SKU restent gérés dans Shopify.
Sélectionner l’API Shopify 2026-07 ou suivante et disposer des droits read_publications et write_publications. Renouveler l’autorisation Shopify si ces droits manquent.
Activer « Suivre le statut en vente des variantes ». Le parent doit être actif et publié sur la Boutique en ligne ; activer également « Publier sur la Boutique en ligne » pour les nouvelles créations si nécessaire.
Garder le champ de validation (« Ready for webshop », par exemple) coché sur le parent et tous ses enfants. Pour retirer un seul enfant, changer son statut en vente / hors vente, sans décocher cette validation.
Traiter la file puis vérifier la visibilité et l’achat de chaque variante dans Shopify. Remettre l’enfant en vente, relancer la synchronisation et vérifier sa republication.

Règles à connaître :

Les filtres de catégories et de validation restent prioritaires et s’appliquent au groupe entier, y compris au traitement de la file.
Pour une variante déjà présente, seule sa publication sur la Boutique en ligne est modifiée. Ses autres canaux restent inchangés.
Une nouvelle variante déjà hors vente est créée non publiée sur tous les canaux pour éviter une exposition temporaire. Sa remise en vente par cette option publie uniquement sur la Boutique en ligne.
Enregistrer l’option ne déclenche pas d’export massif. La désactiver ne republie pas automatiquement les variantes précédemment retirées.
Les correspondances de tout le groupe sont vérifiées avant la première dépublication. Une variante Shopify inconnue, un SKU ambigu ou une lecture incomplète bloque l’export avec un motif visible.
Un refus de publication est journalisé et peut être relancé, y compris après une création interrompue. Le diagnostic d’accès au canal ne remplace pas un essai réel de publication et ne prouve pas à lui seul le droit d’écriture.
Tous les enfants peuvent être hors vente sans perdre leurs valeurs d’attributs.

Mise à jour : la 1.8.1 n’ajoute aucune table. Depuis une installation 1.8.0 complète, remplacer le code suffit ; conserver la procédure de réactivation après remplacement du code pour une ancienne installation qui doit encore enregistrer les hooks de la 1.8.0. Sauvegarder et tester avant toute mise en production.

Validation : 2 013 contrôles locaux réussis sur Dolibarr 18, 20 et 24, avec mutations de publication simulées. La recette sur une boutique Shopify réelle reste à confirmer avant utilisation en production.

Photos : ajout, suppression et ordre

Envoi des images : activer le flux produits, choisir Dolibarr comme source du catalogue et activer l’envoi des images. Depuis la 1.7.3, ajouter une photo seule dans Fichiers joints suffit à mettre le produit en file, sans modifier un autre champ et sans activer de lien public. Les fichiers sont téléversés directement. Les remplacements de contenu sont détectés et les retraits concernent les médias gérés par le module. Un dépôt direct sur le disque, hors des événements Dolibarr, nécessite un nouvel export du produit.

Ordre des photos (1.8.0) :

Après installation du nouveau code, réactiver le module pour enregistrer le hook de déplacement des fichiers.
Activer explicitement Configuration → Catalogue → Synchroniser l’ordre des photos. Cette option est désactivée par défaut et nécessite l’envoi des images actif.
Réordonner les photos par glisser-déposer dans les fichiers joints du produit, puis laisser la file se traiter.
Vérifier la galerie et l’image principale dans Shopify.

Les médias synchronisés sont placés en tête de galerie selon les positions Dolibarr ; la première photo devient l’image principale. Les fichiers non indexés suivent, triés par nom. Les médias ajoutés directement dans Shopify sont conservés après ceux du module, dans leur ordre relatif. Un simple déplacement ne renvoie pas les fichiers inchangés. Le réordonnancement Shopify étant asynchrone, sa fin est vérifiée lors d’un passage suivant de la file.

Si une photo ne se synchronise pas : vérifier la source du catalogue, le flux produits, l’option images, les filtres éventuels et le traitement de la file. Le journal indique les images trouvées, envoyées et retirées. Un stockage de documents indisponible produit une erreur au lieu de retirer les médias. Les photos des produits rattachés par SKU restent gérées dans Shopify.

Diagnostic et support (depuis la 1.6.0)

Le tableau de bord affiche l’état de la connexion, du planificateur et du dernier rattrapage. Par flux et sens, il présente la dernière opération terminée, les traitements en attente ou en cours, les échecs, conflits et l’ancienneté de la file. Une dernière opération terminée peut être un doublon ou un événement ignoré : consulter son détail pour savoir si une écriture a eu lieu.

Ouvrir un blocage pour lire sa cause et l’action conseillée : identifiants, autorisations, facture attendue, écart de montant ou traitement interrompu.
Corriger la cause puis relancer les échecs ou conflits sélectionnés, jusqu’à 50 à la fois. Les traitements en cours ne sont pas remis en attente.
Utiliser Vérifier la connexion pour actualiser le contrôle ; la page ne contacte pas Shopify à chaque affichage. Les contrôles anciens deviennent non vérifiés et une tâche en retard empêche un état global sain.
Télécharger l’export de diagnostic pour le support. Il contient les versions, statuts, compteurs et codes structurés, sans jetons, secrets, domaine de boutique, données clients, références, journaux bruts ni contenu des commandes. Il est téléchargé localement et n’est jamais envoyé automatiquement.

L’historique détaillé débute à l’installation de cette fonctionnalité. L’export couvre une période de 1 à 30 jours, avec au plus 500 événements et une indication si les résultats sont tronqués. Les jobs et événements anciens peuvent avoir été purgés selon leur conservation.

Options (désactivées par défaut)

Option	Effet
Valider la commande	La commande importée reçoit sa référence définitive (et sort le stock si Dolibarr décrémente à la validation).
Valider l'avoir	L'avoir créé par un remboursement est validé aussitôt.
Réaligner prix, SKU et code-barres	Chaque modification Dolibarr réécrit ces champs sur un produit Shopify déjà publié.
Suivre « en vente »	Un produit retiré de la vente dans Dolibarr passe en brouillon sur Shopify.
Suivre le statut en vente des variantes (1.8.1)	Retirer ou republier un enfant sur la Boutique en ligne sans supprimer sa variante, changer ses quantités ni retirer ses frères et sœurs ; API 2026-07 minimum et droits de publication requis.
Prix envoyé selon la boutique	Prix TTC envoyés si la boutique affiche ses prix taxes incluses.
Catégories Dolibarr	Collections Shopify, tags, ou les deux, avec menu de navigation optionnel.
Images du produit	Fichiers joints envoyés dans les médias Shopify.
Synchroniser l’ordre des photos (1.8.0)	Positions Dolibarr reprises sur les médias existants sans renvoyer les fichiers inchangés.
Filtre de catégories (1.8.0)	Plusieurs branches autorisées et exclusions prioritaires ; aperçu avant enregistrement.
Exporter uniquement les produits validés (1.8.0)	Condition par champ booléen, vérifiée avant mise en file et au traitement.
Poids d'expédition	Poids Dolibarr publié sur la variante Shopify.
Produit supprimé dans Dolibarr	Brouillon ou archivage sur Shopify.
Étiquettes imprimées dans Shopify	Chaque expédition Shopify crée et valide l'expédition Dolibarr, stock sorti par Dolibarr.
Ignorer les commandes de test	Les commandes passées avec la passerelle de test Shopify ne sont pas importées.
Publier sur la Boutique en ligne	Un produit créé par le module est rendu visible sur la boutique.

Autres réglages : service Dolibarr des frais de port, taux de TVA par défaut, quantité Shopify échangée, notification d'expédition au client (active par défaut), règlement et compte bancaire des commandes payées.

Tâches planifiées sous Dolibarr 24

Les deux tâches du module sont de type command (exécution en ligne de commande). Depuis Dolibarr 24, une tâche CLI est comptée en erreur si la variable $dolibarr_cron_allow_cli n'est pas activée : en version 20 le cas était seulement journalisé. Ajoutez donc dans conf/conf.php :

$dolibarr_cron_allow_cli = 1;

Sans cela, les tâches « ShopifySync » s'affichent en rouge dans Outils → Tâches planifiées alors même que le module fonctionne. Sans tâche planifiée active, le bouton « Traiter la file maintenant » du tableau de bord exécute la file à la demande.

Fonctionnement sans endpoint webhook

Le module reste utilisable derrière un hébergement fermé aux connexions entrantes : la réconciliation planifiée, qui n'effectue que des appels sortants, rattrape les commandes, les paiements, les annulations et les remboursements. La fenêtre d'analyse (2 jours par défaut) se règle par la constante SHOPIFYSYNC_RECONCILE_WINDOW_DAYS. L'import étant idempotent, le recouvrement entre deux passages ne crée pas de doublon. Les jobs terminés sont purgés après 30 jours et le journal après 90 jours.

Historique des versions

Version	Apports principaux
1.8.1	Publication des nouveaux produits à variantes ; réparation manuelle des produits déjà créés ; suivi facultatif du statut en vente de chaque enfant, désactivé par défaut ; conservation des identifiants et quantités ; vérification du groupe avant dépublication ; erreurs rejouables ; contrôle de l’API et des autorisations ; aucune nouvelle table.
1.8.0	Sélection de plusieurs branches de catégories, exclusions prioritaires, aperçu complet paginé et validation facultative par champ booléen ; contrôles avant mise en file et au traitement ; collections, tags et menu alignés sur le périmètre ; ordre des photos Dolibarr repris sur les médias existants sans renvoi des fichiers inchangés et suivi asynchrone ; nouvelles options désactivées par défaut, sans export massif ni dépublication automatique.
1.7.3	Envoi des images depuis les dossiers réels et historiques, déclenchement par ajout ou retrait d’une photo seule, détection des remplacements par leur contenu, protection si le stockage est indisponible ; conservation des réglages et des flux désactivés lors d’une désactivation/réactivation après installation du correctif.
1.7.2	Chargement de Dolibarr dans l’assistant conforme au validateur de paquet pour les installations en racine et dans custom, sans changement de synchronisation.
1.7.1	Champs de connexion affichés selon le mode d’authentification dans la Configuration et l’assistant ; identifiants masqués conservés ; reconnexion après enregistrement du mode.
1.7.0	Assistant facultatif de configuration du lien Shopify en six étapes : connexion, catalogue, SKU, entrepôts, facturation et aperçu ; brouillon privé, confirmation explicite d’un premier lot de 20 opérations maximum, contrôle des ambiguïtés et des modifications concurrentes ; analyse limitée à 2 000 fiches de chaque côté.
1.6.0	Diagnostic de connexion et des tâches planifiées, suivi par flux et sens, causes compréhensibles, historique filtrable, relances ciblées et export de diagnostic sans secrets ; remboursements sans facture source visibles dans les reprises puis en échec si le blocage persiste.
1.5.0	Jetons d'accès qui expirent pris en charge : mode « client ID et secret » (jeton de 24 h renouvelé par le module) et mode « autorisation Shopify » (jeton d'une heure + rafraîchissement de 90 jours), renouvellement avant échéance et à la volée sur un refus, renouvellement préventif chaque nuit, bouton « Se reconnecter », URL de retour protégée par signature, état à usage unique et contrôle du domaine ; le mode « jeton permanent collé » reste le défaut et ne change pas
1.4.3	Correctifs : contrôle strict des montants appliqué aussi au rejeu, règlement retenté quand son enregistrement avait échoué, remboursement en échec distingué d'une attente de facture (job en échec au lieu d'un classement silencieux), frais de port remboursés portés à leur propre taux de TVA, renommage vers un tag déjà saisi à la main qui n'est plus adopté par le module
1.4.2	Correctifs du contre-audit : frais de port refusés rendus à la commande et reposés au rejeu, quantité modifiée sur Shopify détectée, validation de commande et de facture rejouées à la reprise, option de contrôle strict des montants, remboursements limités aux transactions réellement abouties et répartis par taux de TVA, ligne d'avoir refusée non enregistrée comme traitée, tags jamais adoptés et renommage limité aux produits suivis, renommage échoué réellement retenté au rejeu
1.4.1	Correctifs : unité forcée des metafields réellement convertie (2 kg publiés en 2000 g) ; un tag Shopify saisi à la main n'est plus retiré ; suppression de collection refusée signalée au lieu d'être déclarée réussie ; erreurs de renommage de tag remontées ; remboursement de montant nul ne crée plus d'avoir intégral ; commande dont une ligne a été refusée ni validée ni facturée, puis complétée au rejeu ; modification faite pendant un export conservée ; webhook non acquitté quand le job n'a pas pu être enregistré
1.4.0	Catégories Dolibarr en collections Shopify, tags et menu de navigation ; images des fiches envoyées dans les médias ; champs standards (poids, dimensions, volume) publiables en metafields avec conversion d'unité ; poids d'expédition ; metafields fiables (case décochée, valeur vidée, valeur refusée signalée sans bloquer les autres) ; produit supprimé dans Dolibarr passé en brouillon ou archivé
1.3.1	Code client obligatoire géré (clients créés avec le code de la numérotation Dolibarr) ; ventes sans client (caisse Shopify POS) portées par un tiers unique configurable ; motif des refus journalisé ; étiquettes d'un emplacement non géré ignorées
1.3.0	Étiquettes imprimées dans Shopify (option) : expédition Dolibarr créée et validée sur l'entrepôt de l'emplacement expéditeur, stock sorti par Dolibarr qui reste seul maître, suivi et transporteur repris, annulation gérée, rattrapage par la réconciliation
1.2.0	Prix TTC, frais de port, date de vente, contact de livraison et clients invités à l'import ; annulations Shopify ; expéditions partielles avec transporteur ; prix, SKU et code-barres posés à la création des produits ; import d'un produit par variante ; suppressions Shopify gérées ; réconciliation des paiements, annulations et remboursements ; actions du tableau de bord ; options de validation et de réalignement (désactivées par défaut, aucun changement de comportement à la mise à jour) ; validé sur Dolibarr 18, 20 et 24
1.1.2	Bouton « Synchroniser » des fiches commande ; facture créée quand le paiement arrive après l'import
1.1.1	Export de stock compatible avec les API Shopify 2026-04 et suivantes ; sonde de compatibilité multi-versions
1.1.0	Tableau de bord et écrans redessinés, encart « État Shopify » sur les fiches ; rattachement par SKU d'un catalogue existant ; stock multi-emplacements
1.0.2	Produits à variantes (options Shopify, 1 SKU par combinaison, pagination jusqu'à 2 048 variantes, refus au-delà de 3 attributs) ; stock multi-entrepôts ; metafields ; règlement automatique des commandes payées ; adresse de facturation complète ; bouton « Tester la connexion » ; remises Shopify à l'import ; réconciliation par horodatage absolu et rattrapage des remboursements
1.0.1	Gestion des erreurs GraphQL renvoyées en chaîne ; version d'API portée à 2026-01 ; `inventoryActivate` avant écriture de stock ; correction critique de la création des lignes de commande
1.0.0	Version initiale : commandes, clients, remboursements, produits, stock, expéditions, webhooks signés, file d'attente, tableau de bord

Support

Contact : support@arcchester.com
Autres modules du même éditeur : recherche « arcchester » sur le Dolistore