Store Platforms

Intégration WooCommerce–ERP : architecture et erreurs à éviter

Découvrez quoi synchroniser entre WooCommerce et votre ERP, qui possède chaque donnée et comment éviter doublons, ruptures de stock et erreurs HPOS.

Photo de profil de Long Nguyen

Long Nguyen

Développeur fullstack · Ingénieur IA · Chercheur

• • 5 min de lecture •

Ce qu’une intégration WooCommerce–ERP synchronise réellement

L’intégration entre WooCommerce et un ERP automatise l’échange des commandes, des stocks, des données produits, des prix, des clients et des documents financiers entre une boutique WooCommerce et un ERP. Personne n’a ainsi besoin de ressaisir une commande ou de corriger manuellement un niveau de stock. Le plus utile est de la concevoir comme un ensemble de flux de données distincts, chacun ayant son propre sens de circulation, son système propriétaire et son déclencheur, plutôt que comme une seule grande synchronisation.

Donnée Sens habituel Système de référence Déclencheur courant
Commandes WooCommerce → ERP WooCommerce jusqu’à l’acceptation par l’ERP, puis l’ERP Commande payée ou passée au statut « en cours »
Statut de commande et suivi ERP → WooCommerce ERP (préparation et expédition) Expédition validée dans l’ERP
Niveaux de stock ERP → WooCommerce ERP Mouvement de stock, avec contrôle planifié
Données maîtres produit (SKU, coût, poids, variantes) ERP → WooCommerce ERP Création ou modification du produit
Contenu produit (descriptions, images, textes SEO) Reste dans WooCommerce WooCommerce Non synchronisé
Prix ERP → WooCommerce ERP pour le tarif catalogue, WooCommerce pour les remises promotionnelles Planifié ou déclenché par une modification du tarif
Clients WooCommerce → ERP ERP pour le client de facturation, WooCommerce pour le compte de connexion Première commande
Remboursements et avoirs Dans les deux sens ERP pour la comptabilité Création d’un remboursement
Factures et documents ERP → WooCommerce ERP Comptabilisation de la facture

Deux lignes méritent une mise en garde. Le contenu produit doit normalement rester dans WooCommerce : un ERP contient des données de gestion et de comptabilité, pas des textes commerciaux. Y faire transiter les descriptions ne ferait que ralentir chaque modification. Les clients constituent la ligne la plus délicate, car WooCommerce gère un compte de connexion, l’ERP un client de facturation, et une même personne peut correspondre à deux, aucune ou trois fiches en doublon.

Définissez le propriétaire de chaque champ avant d’écrire du code

Presque toutes les intégrations qui échouent en production échouent pour la même raison : deux systèmes pensent être propriétaires d’un même champ. Documentez la règle de propriété pour chaque ligne du tableau ci-dessus, puis empêchez le système non propriétaire de l’écraser.

  • Le SKU est la clé de correspondance. Faites correspondre les produits sur leur SKU (dans Odoo, la référence interne), jamais sur le nom du produit ni sur l’identifiant numérique du produit WooCommerce. Conservez l’identifiant de l’autre système comme référence secondaire pour accélérer les recherches.
  • Référencez chaque commande dans les deux sens. Inscrivez le numéro de commande WooCommerce comme référence externe dans l’ERP, puis reportez le numéro du document ERP dans la commande WooCommerce. Cette simple habitude assure l’idempotence (ignorer ce qui a déjà été importé) et permet au support de retrouver une demande client en une seule recherche.
  • Le stock se trouve sur les variations. Pour les produits variables, le SKU et le stock sont associés à la variation. Reliez donc les variantes de l’ERP aux identifiants de variation WooCommerce, et non au produit parent.
  • Choisissez le point de transfert de responsabilité. WooCommerce reste propriétaire de la commande jusqu’à la confirmation du paiement et son acceptation par l’ERP. Ensuite, l’ERP gère la préparation et WooCommerce ne fait qu’afficher le statut. Les modifications postérieures au transfert (changement d’adresse, annulation, remboursement partiel) nécessitent une règle explicite, car c’est à ce moment que les deux copies commencent à diverger.

Connecteur, middleware ou intégration sur mesure : comment choisir

Il existe trois façons de relier les deux systèmes, et aucune n’est adaptée à tous les projets.

Approche Adaptée lorsque Montre ses limites lorsque Responsable de la maintenance
Connecteur prêt à l’emploi (extension ou module fourni par l’ERP) Le processus standard de la commande à l’encaissement, un seul entrepôt et des SKU propres Vous avez besoin de tarifs propres à chaque client, de packs, d’expéditions fractionnées ou d’un champ non pris en charge L’éditeur du connecteur, mais vous assumez le risque lors des mises à jour de WooCommerce ou de l’ERP
Middleware ou iPaaS (outil de workflows hébergé entre les deux systèmes) Plusieurs systèmes doivent être reliés, des utilisateurs non techniques modifient les flux et le volume reste modéré La facturation se fait souvent à la tâche, donc le coût suit le volume de commandes ; une logique conditionnelle complexe devient illisible dans les diagrammes de flux Vous entretenez les flux ; l’éditeur entretient la plateforme
Service d’intégration sur mesure Les règles sont inhabituelles, le volume en période de pointe est élevé, plusieurs canaux alimentent un même ERP ou des journaux conformes aux exigences d’audit sont nécessaires Personne ne peut maintenir le code ou les besoins restent flous Vous ou votre développeur : code, supervision et mises à niveau

Notre règle générale : commencez par un connecteur si votre éditeur d’ERP prend en charge WooCommerce et que votre processus de la commande à l’encaissement est standard. Passez au sur-mesure dès qu’une règle métier dépend d’une personne, par exemple des tarifs spécifiques à certains clients, des kits vendus comme un seul SKU, des expéditions fractionnées ou un traitement fiscal que le connecteur ne sait pas exprimer. Le véritable coût d’un connecteur est rarement sa licence ; c’est plutôt le contournement que vous devrez construire autour de la règle manquante.

Si vous optez pour le sur-mesure, l’essentiel du travail se situe dans la partie peu spectaculaire : import idempotent des commandes, correspondance des champs, nouvelles tentatives et supervision. Netalith développe ce type d’intégration avec l’API REST de WooCommerce et les API des ERP ; consultez l’intégration d’API WooCommerce et de plateformes e-commerce pour découvrir comment ce travail est cadré.

Les fondations techniques : API REST, webhooks et rapprochement

WooCommerce expose les commandes, produits, clients et coupons via son API REST (version wc/v3) et peut vous informer des modifications au moyen de webhooks. Une intégration solide utilise les deux, mais pour des tâches différentes.

  • Authentification. Générez une paire de clés dans WooCommerce › Réglages › Avancé › API REST, choisissez l’utilisateur associé à la clé et envoyez la clé client et le secret comme identifiant et mot de passe de l’authentification basique. HTTPS est recommandé. Utilisez un utilisateur dédié à l’intégration afin de séparer ses droits et sa piste d’audit de ceux de toute personne physique.
  • Pagination. Les requêtes de liste renvoient 10 éléments par défaut. Lisez l’en-tête de réponse X-WP-TotalPages et bouclez jusqu’à la dernière page ; sinon votre import ne verra silencieusement que la première. Vous pouvez augmenter per_page jusqu’à 100 dans WordPress.
  • Lectures incrémentales. Filtrez avec modified_after au lieu de tout relire et enregistrez la date de dernière modification la plus récente réellement traitée, plutôt que l’heure de démarrage du traitement.
  • Webhooks. Les événements couvrent la création, la modification et la suppression des commandes, produits, coupons et clients. Attribuez un secret à chaque webhook : WooCommerce l’utilise pour signer la charge utile (dans l’en-tête X-WC-Webhook-Signature), afin que votre récepteur puisse vérifier que la requête provient bien de votre boutique.

La règle qui pose le plus souvent problème figure dans la documentation des webhooks de WooCommerce : un webhook est automatiquement désactivé après plus de cinq échecs de livraison consécutifs, et toute réponse qui n’est pas un code 2xx, 301 ou 302 est considérée comme un échec. Si votre récepteur est indisponible pendant un déploiement ou renvoie des erreurs parce que sa base de données est saturée, quelques échecs consécutifs suffisent à désactiver le webhook. Les commandes continuent d’arriver dans WooCommerce, plus rien ne parvient à l’ERP et personne n’est prévenu.

Concevez l’intégration autour de quatre habitudes :

  1. Gardez le récepteur simple. Il vérifie la signature, écrit la charge utile dans une file d’attente et renvoie un code 200. Tout le traitement ERP s’effectue dans un worker, afin qu’un ERP lent ne provoque pas d’échec de livraison.
  2. Exécutez une tâche de rapprochement. Toutes les quelques minutes, récupérez les commandes modifiées depuis la dernière exécution et importez celles que le webhook a manquées. Comme l’import est idempotent, le chevauchement ne pose pas de problème.
  3. Surveillez l’état des webhooks. Lisez l’état de chaque webhook via l’API REST et déclenchez une alerte dès qu’il est différent de active.
  4. Consultez le journal des livraisons. WooCommerce › État › Journaux, filtré sur la source webhooks-delivery, indique la réponse de votre endpoint.

Considérez le webhook comme un signal indiquant qu’une modification a eu lieu, et la tâche de rapprochement comme la garantie d’exhaustivité.

Synchroniser les stocks sans vendre plus que disponible

La survente est le premier problème visible pour l’entreprise et résulte presque toujours d’un défaut de conception plutôt que d’un bug. Quatre règles permettent d’en éviter la plupart.

  1. Publiez le stock disponible à la vente, pas le stock physique. WooCommerce conserve une quantité par produit ou variation ; l’ERP en gère plusieurs (stock physique, réservé, en cours de réception, par entrepôt). Décidez quelle combinaison doit être affichée dans la boutique, retranchez une marge de sécurité pour les produits qui partent vite et calculez-la dans l’intégration plutôt que dans la boutique.
  2. Envoyez des quantités absolues, jamais des écarts. Un écart tel que « 2 vendus », appliqué deux fois après une nouvelle tentative, fausse définitivement le stock ; une valeur absolue telle que « 12 disponibles », appliquée deux fois, reste sans conséquence.
  3. Respectez l’ordre des opérations. WooCommerce diminue lui-même le stock à l’arrivée des commandes : pendant un court instant, il peut donc être en avance sur l’ERP. Une mise à jour absolue calculée avant l’arrivée d’une commande dans l’ERP peut faire réapparaître un stock déjà vendu. Importez et réservez les commandes avant de publier le stock, ou retranchez les commandes encore en attente d’import.
  4. Regroupez et limitez le débit. Utilisez les endpoints par lots plutôt qu’une requête par SKU, gardez des lots assez petits pour s’exécuter dans la limite de temps PHP du serveur et n’envoyez que les produits dont la quantité a réellement changé.

HPOS : pourquoi les intégrations doivent cesser de lire directement les tables de commandes

Depuis WooCommerce 8.2, High-Performance Order Storage est activé par défaut pour les nouvelles boutiques. Les commandes résident dans des tables dédiées (wp_wc_orders, wp_wc_order_addresses, wp_wc_order_operational_data et wp_wc_orders_meta), et non plus dans wp_posts et wp_postmeta. Pour une intégration ERP, cela entraîne trois changements.

  • Ne consultez pas les commandes directement dans la base de données. Un script ou un connecteur qui lit les lignes shop_order dans wp_posts ne lit au mieux que la copie de secours : la documentation HPOS de WooCommerce décrit les tables posts comme des tables de sauvegarde, qui ne reçoivent des données que lorsque la synchronisation est activée. Passez par l’API REST ou, en PHP, par wc_get_order et wc_get_orders, qui fonctionnent quel que soit le mode de stockage.
  • Vérifiez la compatibilité des extensions. Une extension qui ne déclare pas sa prise en charge de HPOS désactive l’option HPOS dans Réglages › Avancé › Fonctionnalités. Le retour documenté consiste à repasser au stockage dans les tables posts avec le mode de compatibilité activé, mais il ne s’agit que d’une solution provisoire. Demandez à l’éditeur du connecteur une version compatible HPOS plutôt que de maintenir la boutique sur l’ancien stockage.
  • Écrivez les métadonnées de commande via l’objet commande. Les champs personnalisés enregistrés par votre intégration, comme le numéro de document ERP, doivent être écrits avec les propres méthodes de métadonnées de la commande afin d’être placés dans la bonne table.

Exemple : envoyer des commandes WooCommerce à Odoo via JSON-2

Odoo constitue un bon exemple, car son API externe a récemment évolué. Avec Odoo 19 et les versions suivantes, la méthode prise en charge est l’API External JSON-2 : vous envoyez une requête POST contenant un corps JSON vers /json/2/<model>/<method>, avec une clé API comme jeton bearer. Cette API n’existe pas dans Odoo 16 à 18, où les intégrations utilisent encore XML-RPC ou JSON-RPC. Quatre caractéristiques de la documentation de référence de l’API External JSON-2 d’Odoo influencent la conception de l’intégration :

  • Arguments nommés uniquement. JSON-2 n’accepte pas d’arguments positionnels ; tout est placé dans le corps JSON, avec éventuellement ids et context.
  • Un appel, une transaction. Chaque appel est validé ou annulé indépendamment et plusieurs appels ne peuvent pas être enchaînés dans une seule transaction. Odoo recommande d’appeler une méthode unique qui réalise ensemble les opérations liées ; c’est pourquoi l’exemple ci-dessous crée la commande et ses lignes en un seul appel create.
  • Les droits dépendent de l’utilisateur API. Les droits d’accès et règles d’enregistrement de l’utilisateur associé à la clé s’appliquent. Pour les intégrations, Odoo recommande un utilisateur robot dédié avec le minimum de permissions plutôt que le compte d’une personne.
  • Les clés expirent. Odoo exige une durée lors de la création d’une clé et les clés longue durée ne peuvent pas dépasser trois mois. Planifiez leur renouvellement, sinon l’intégration commencera à renvoyer des erreurs 401 un jour choisi par personne.

Voici la structure d’un import de commande, sous forme d’exemple et non de code prêt pour la production :

import requests
from woocommerce import API

wc = API(url='https://shop.example.com', consumer_key=WC_KEY, consumer_secret=WC_SECRET, wp_api=True, version='wc/v3', timeout=30)
ODOO = 'https://erp.example.com/json/2'
HEADERS = {'Authorization': 'bearer ' + ODOO_API_KEY, 'X-Odoo-Database': 'mycompany'}

def odoo(model, method, **body):
    r = requests.post(f'{ODOO}/{model}/{method}', headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()

def orders_since(since):
    page = 1
    while True:
        resp = wc.get('orders', params={'status': 'processing', 'modified_after': since, 'per_page': 100, 'page': page})
        resp.raise_for_status()
        yield from resp.json()
        if page >= int(resp.headers['X-WP-TotalPages']):
            return
        page += 1

def import_order(o):
    ref = 'WC-' + str(o['id'])
    if odoo('sale.order', 'search', domain=[['client_order_ref', '=', ref]], limit=1):
        return  # already imported
    email = o['billing']['email']
    found = odoo('res.partner', 'search', domain=[['email', '=', email]], limit=1)
    name = o['billing']['first_name'] + ' ' + o['billing']['last_name']
    partner = found[0] if found else odoo('res.partner', 'create', vals_list=[{'name': name, 'email': email}])[0]
    lines = []
    for item in o['line_items']:
        product = odoo('product.product', 'search', domain=[['default_code', '=', item['sku']]], limit=1)
        if not product:
            raise LookupError('Unmapped SKU: ' + item['sku'])
        lines.append([0, 0, {'product_id': product[0], 'product_uom_qty': item['quantity'], 'price_unit': float(item['price'])}])
    order_id = odoo('sale.order', 'create', vals_list=[{'partner_id': partner, 'client_order_ref': ref, 'order_line': lines}])[0]
    odoo('sale.order', 'action_confirm', ids=[order_id])

Ce schéma laisse de côté les éléments qui concentrent le véritable travail : taxes, remises, lignes d’expédition, enregistrement du paiement, remboursements, nouvelles tentatives et voie de traitement des SKU non associés. Il comporte également une faille annoncée par la règle « une transaction ». La vérification des doublons et la création s’effectuent dans des transactions distinctes : deux workers pourraient donc importer simultanément la même commande. Utilisez un seul worker par flux de commandes ou imposez l’unicité de la référence client dans la base de données au moyen d’un petit module personnalisé.

Un point mérite une attention particulière. Les anciennes versions de la documentation Odoo avaient annoncé la suppression des endpoints XML-RPC et JSON-RPC dans une future version. La documentation 19.0 actuelle prévoit désormais leur suppression dans une version ultérieure, tandis que la référence RPC externe d’Odoo mentionne également une échéance spécifique pour les bases hébergées Odoo Online. JSON-2 est présenté comme leur remplacement. Odoo ayant déjà modifié ce calendrier, consultez la page en ligne avant de prévoir un budget de migration. Notez également que, dans les offres hébergées d’Odoo, l’accès à l’API externe est disponible uniquement avec les formules Custom, et non avec One App Free ou Standard.

Les erreurs qui se répètent en production

Symptôme Cause habituelle Correctif
Les commandes n’arrivent plus dans l’ERP alors que la boutique semble fonctionner Webhook désactivé automatiquement après plus de cinq échecs de livraison consécutifs Récepteur qui accuse rapidement réception avec une file d’attente ; alerte sur l’état du webhook ; tâche de rapprochement
Seules les 10 commandes les plus récentes sont importées Pagination ignorée ; les listes renvoient 10 éléments par page par défaut Boucler sur X-WP-TotalPages ; demander un per_page allant jusqu’à 100
Des commandes sont créées en double dans l’ERP Webhook rejoué ou tâche de rapprochement exécutée en parallèle sans idempotence Vérification de la référence externe, complétée par une contrainte d’unicité dans la base de données de l’ERP
Le stock dérive de quelques unités chaque semaine Envoi d’écarts ou quantité absolue calculée avant l’import d’une nouvelle commande Publier le stock absolu disponible à la vente ; importer et réserver les commandes avant de publier le stock
Les totaux diffèrent de quelques centimes entre la boutique et l’ERP Taxes et arrondis calculés séparément dans les deux systèmes (WooCommerce renvoie les montants sous forme de chaînes avec deux décimales) Décider quel système est propriétaire de la taxe ; importer les totaux WooCommerce comme référence ou reproduire sa règle d’arrondi ; rapprocher chaque commande
L’intégration renvoie soudainement une erreur 401 Clé API ERP expirée ou clé ou utilisateur WooCommerce révoqué Calendrier de renouvellement des clés ; utilisateurs robot dédiés ; alerte sur toute erreur 401
Les rapports de commandes deviennent vides après l’activation de HPOS Requête SQL directe sur wp_posts Utiliser l’API REST ou wc_get_orders
Un mauvais SKU bloque toute la file d’attente Nouvelles tentatives infinies sur un produit non associé File des messages non distribuables avec alerte ; poursuivre le traitement des autres commandes

Sept questions à résoudre avant de développer ou d’acheter

  1. Quel système possède chaque champ du tableau des flux, et qui tranche en cas de conflit ?
  2. Quelle est la stratégie SKU, notamment pour les variations et les packs ?
  3. À quel statut de commande l’ERP prend-il le relais, et que deviennent ensuite les modifications, annulations et remboursements ?
  4. Quel volume de commandes prévoyez-vous en période de pointe (soldes ou campagne), et non lors d’une journée moyenne ?
  5. Quelles règles fiscales, tarifaires et d’entrepôt n’existent que dans la tête d’une personne ?
  6. Qui est alerté lorsque l’intégration s’arrête et dans quel délai doit-il être informé ?
  7. La version de votre ERP et son API resteront-elles prises en charge pendant toute la durée du projet (par exemple, Odoo 19 ou version ultérieure pour JSON-2) ?

Si vous pouvez répondre à la plupart de ces questions, vous pouvez cadrer une intégration. Si ce n’est pas le cas, les résoudre constitue le premier livrable utile. Décrivez votre boutique WooCommerce, votre ERP et votre workflow dans le formulaire de devis gratuit de Netalith, qui couvre l’ensemble de nos services, ne coûte rien et ne nécessite aucun compte.

FAQ

Questions fréquentes

Qu’est-ce qu’une intégration WooCommerce–ERP ?

Il s’agit de l’échange automatisé des commandes, des niveaux de stock, des données produits, des prix, des clients et des documents financiers entre une boutique WooCommerce et un ERP, afin d’éviter toute ressaisie manuelle des commandes et des stocks. En pratique, cela correspond à plusieurs flux de données distincts, chacun ayant son propre sens de circulation, son propriétaire et son déclencheur.

Quelles données synchroniser entre WooCommerce et un ERP ?

Les commandes vont généralement de WooCommerce vers l’ERP. Les niveaux de stock, les données maîtres produit, les prix, le suivi des expéditions et les factures repartent de l’ERP vers WooCommerce. Le contenu produit, comme les descriptions, les images et les textes SEO, reste habituellement dans WooCommerce. Définissez le propriétaire de chaque champ avant de construire l’intégration.

Faut-il utiliser une extension, un middleware ou une intégration sur mesure ?

Choisissez un connecteur prêt à l’emploi pour un processus standard de la commande à l’encaissement, avec un seul entrepôt et des SKU propres. Envisagez un middleware si plusieurs systèmes sont concernés et si des utilisateurs non techniques doivent modifier les flux. Optez pour une intégration sur mesure en présence de tarifs inhabituels, de packs, d’expéditions fractionnées, d’un volume élevé en période de pointe ou d’un besoin de journaux conformes aux exigences d’audit.

WooCommerce et l’ERP doivent-ils se synchroniser en temps réel ou selon un calendrier ?

Utilisez les deux approches. Les webhooks fournissent des mises à jour quasi instantanées, mais WooCommerce désactive un webhook après plus de cinq échecs de livraison consécutifs. Une tâche planifiée de rapprochement, qui récupère les commandes récemment modifiées, est donc indispensable pour garantir qu’aucune donnée ne soit perdue.

HPOS a-t-il une incidence sur mon intégration ERP ?

Oui, dès qu’une intégration lit directement les commandes dans la base de données. Depuis WooCommerce 8.2, HPOS est activé par défaut pour les nouvelles boutiques et les commandes résident dans des tables dédiées plutôt que dans wp_posts. Les intégrations doivent utiliser l’API REST ou les fonctions de commande WooCommerce comme wc_get_order, et non interroger directement les tables.

WooCommerce peut-il s’intégrer à Odoo et XML-RPC peut-il encore être utilisé sans risque ?

Oui. Les commandes peuvent être lues via l’API REST de WooCommerce et écrites dans Odoo via son API externe. Avec Odoo 19 et les versions suivantes, utilisez l’API JSON-2 ; XML-RPC et JSON-RPC sont déconseillés et leur suppression est prévue dans de futures versions selon la documentation actuelle. Odoo 16 à 18 utilisent encore les endpoints RPC : consultez la documentation en ligne correspondant à votre version.

Restez informé avec Netalith

Recevez des ressources de développement, des mises à jour produit et des offres spéciales directement dans votre boîte mail.