Une intégration WooCommerce-ERP est fiable lorsque chaque donnée a une source maîtresse unique, que les événements peuvent être rejoués sans créer de doublons, que les erreurs atterrissent dans une file d'attente et qu'un rapprochement quotidien est en place. Connecter l'API ne suffit pas : il faut définir quand naît une commande, qui réserve le stock, comment sont gérés les paiements, les retours, les taxes et les factures, et ce qui se passe si l'un des systèmes tombe en panne.
Définir les systèmes maîtres
| Donnée | Système maître recommandé habituel |
|---|---|
| Produit/SKU | ERP ou PIM |
| Prix | ERP, PIM ou moteur de tarification |
| Stock disponible | ERP/WMS |
| Commande web | WooCommerce, à la création |
| Facture | ERP |
| Paiement | Passerelle avec rapprochement ERP |
| Client | Règle définie par B2C/B2B |
| Expédition | ERP/WMS ou plateforme logistique |
Deux systèmes ne devraient jamais être autorisés à modifier la même donnée sans une règle qui résout le conflit.
Identifiants
Utilisez des clés stables :
- SKU unique.
- ID de variation.
- ID client externe.
- Numéro de commande web.
- ID de transaction.
- Numéro de facture ERP.
- Lot de synchronisation.
Les noms ne sont pas des identifiants. Un changement de description ne doit pas créer un nouveau produit.
API et webhooks
WooCommerce fournit une API REST pour lire et écrire des produits, des commandes et d'autres ressources. Les webhooks notifient les événements à une URL.
Schéma recommandé :
- Le webhook signale l'événement.
- Le récepteur valide la signature et journalise l'événement.
- Une file d'attente découple le traitement.
- Un worker récupère le détail via l'API.
- Les données sont transformées et envoyées à l'ERP.
- Le résultat est confirmé.
- Le rapprochement détecte ce qui manque.
Ne vous fiez pas au seul webhook : il peut échouer ou être désactivé après des erreurs répétées. Un rapprochement périodique est obligatoire.
Sécurité
- Clés distinctes par intégration et par environnement.
- Moindre privilège.
- HTTPS.
- Secrets dans un coffre-fort, pas dans le code.
- Rotation.
- Restrictions IP ou contrôles supplémentaires si pertinent.
- Journaux sans secrets.
- Validation du contenu (payload).
- Protection contre le rejeu.
- WordPress et les extensions maintenus à jour.
La documentation officielle présente des clés avec permissions de lecture et d'écriture ; ne les accordez que si le flux l'exige.
Commandes et statuts
Faites correspondre chaque statut :
| WooCommerce | ERP | Action |
|---|---|---|
| pending | pending | ne pas réserver, ou règle spécifique |
| processing | confirmed | réserver/préparer |
| completed | shipped/closed | clôturer selon le processus |
| cancelled | cancelled | libérer |
| refunded | retour/avoir | flux financier |
| failed | failed | ne pas préparer |
La correspondance s'adapte à la passerelle et à la logistique. Ne facturez jamais sur un statut ambigu.
Idempotence
Chaque événement possède une clé composite — boutique, commande, type et version. S'il arrive deux fois, la seconde opération met à jour ou est ignorée ; elle ne crée jamais une autre commande.
Les nouvelles tentatives après un délai d'expiration vérifient d'abord si l'opération existe déjà.
Stock
Définissez :
- Stock physique.
- Réservé.
- Disponible à la vente.
- Stock de sécurité.
- Rupture avec réapprovisionnement (backorder).
- Entrepôts multiples.
- Kits et variations.
La boutique doit recevoir le chiffre disponible, pas nécessairement le physique. La fréquence dépend de la rotation et du risque de survente.
Rapprochez par SKU et alertez en cas d'écarts.
Tarification et promotions
Décidez où résident les prix, les coupons, les taxes et les arrondis. L'ERP reçoit un détail suffisant pour reproduire le total.
Les promotions complexes peuvent être enregistrées comme une remise traçable. Ne recalculez pas dans l'ERP d'une façon qui modifie ce qui a été facturé.
Taxes
Testez le B2C/B2B, les territoires, les exonérations, les taux, les frais de port et les remises. La localisation fiscale et les obligations de facturation doivent être validées.
WooCommerce calcule la vente ; l'ERP doit l'accepter ou la valider selon la conception, sans créer d'écarts silencieux.
Clients et confidentialité
Pour la commande en tant qu'invité, évitez de créer des doublons pour chaque variante d'une adresse email. Définissez une règle de correspondance et le moment de mise à jour des données.
L'intégration minimise les données, contrôle les rôles et les contrats, et applique des limites de conservation. Le marketing n'est pas déclenché automatiquement par un achat.
Factures
L'ERP numérote et émet généralement les factures. Le lien renvoie le numéro, le PDF ou le statut à WooCommerce ou à l'espace client. Les avoirs et les retours sont liés à l'original.
Une facture émise n'est jamais modifiée pour un changement de commande ; la procédure fiscale correcte s'applique à la place.
Paiements
La commande, la transaction et le règlement sont des objets distincts. Rapprochez :
- Montant de la commande.
- Débit.
- Frais.
- Remboursement.
- Rétrofacturation.
- Règlement bancaire.
Un webhook de commande ne prouve pas que l'argent a été réglé.
Expédition et retours
L'ERP/WMS envoie le transporteur, le suivi, les colis et le statut. Les retours génèrent une autorisation, une réception, une inspection, un avoir et une remise en stock selon l'état.
Le stock n'est pas remis à jour lors de la demande de retour ; il l'est une fois le retour reçu et validé.
Gestion des erreurs
La file d'erreurs affiche :
- Événement.
- Commande/SKU.
- Cause.
- Tentatives.
- Dernière réponse.
- Responsable.
- Action.
Les erreurs permanentes — par exemple un SKU inexistant — ne sont pas retentées indéfiniment. Corrigez la donnée et retraitez.
Observabilité
Métriques :
- Commandes synchronisées.
- Latence p95.
- Erreurs par cause.
- Tentatives.
- Écarts de stock.
- Commandes sans facture.
- Paiements sans commande.
- Webhooks inactifs.
- Doublons évités.
Les alertes doivent être actionnables.
Tests
- Commande invité et commande avec compte.
- Variations.
- Coupon.
- Taxes multiples.
- Paiement échoué.
- Remboursement partiel.
- Annulation.
- Stock concurrent.
- Webhook dupliqué.
- ERP indisponible.
- WooCommerce indisponible.
- Changement de SKU.
- Retour.
Plan de déploiement
Jours 1–30
Référentiels, statuts, taxes, architecture et sécurité.
Jours 31–60
API, webhooks, files d'attente, idempotence et tests.
Jours 61–90
Pilote, rapprochement, alertes et production.
Erreurs courantes
- Absence de source maîtresse.
- Utiliser les noms comme clés.
- Se fier uniquement aux webhooks.
- Retenter sans idempotence.
- Absence de file d'erreurs.
- Mettre à jour le stock physique.
- Recalculer les promotions.
- Facturer avant un paiement valide.
- Remettre en stock avant réception du retour.
- Absence de rapprochement quotidien.
Liste de contrôle
- Référentiels.
- Identifiants.
- Statuts.
- Idempotence.
- Stock disponible.
- Tarification et taxes.
- Clients et confidentialité.
- Factures et paiements.
- Erreurs et alertes.
- Rapprochement et retour arrière.
Questions fréquentes
API ou extension ?
Cela dépend du périmètre. Une extension peut accélérer les choses, mais elle doit démontrer sécurité, maintenance, idempotence et support.
Les webhooks suffisent-ils ?
Non. Ils doivent être complétés par du polling et un rapprochement.
Qui doit contrôler le stock ?
Généralement l'ERP/WMS. WooCommerce reçoit la disponibilité calculée.
Sources officielles consultées
- WooCommerce REST API.
- WooCommerce Webhooks.
- WooCommerce Developer REST API.
- WooCommerce : travailler avec les webhooks.
Summum Sistemas peut concevoir l'intégration, les files d'attente, le rapprochement et la supervision.