Une intégration WooCommerce–ERP est fiable lorsque chaque donnée dispose d'une source maîtresse, que les événements peuvent être rejoués sans créer de doublons, que les erreurs sont mises en file d'attente et qu'il existe une réconciliation quotidienne. Connecter l'API ne suffit pas : il faut définir quand naît une commande, qui réserve le stock, comment sont traités les paiements, les retours, les taxes et les factures, et ce qui se passe si l'un des systèmes est indisponible.
Définir les systèmes maîtres
| Donnée | Maître habituellement recommandé |
|---|---|
| Produit/SKU | ERP ou PIM |
| Prix | ERP, PIM ou moteur commercial |
| Stock disponible | ERP/WMS |
| Commande web | WooCommerce, à sa création |
| Facture | ERP |
| Paiement | Passerelle avec réconciliation ERP |
| Client | Règle définie selon B2C/B2B |
| Expédition | ERP/WMS ou plateforme logistique |
Deux systèmes ne doivent jamais être autorisés à modifier la même donnée sans une règle qui tranche 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 propose une API REST pour lire et écrire produits, commandes et 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 enregistre l'événement.
- Une file d'attente découple le traitement.
- Un worker interroge le détail via l'API.
- Les données sont transformées puis envoyées à l'ERP.
- Le résultat est confirmé.
- La réconciliation détecte les absences.
Ne vous fiez pas au seul webhook : il peut échouer ou être désactivé après des erreurs répétées. La réconciliation 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 nécessaire.
- Journaux sans secrets.
- Validation du payload.
- Protection contre le rejeu.
- WordPress et extensions à jour.
La documentation officielle montre des clés avec droits de lecture et d'écriture ; elles ne doivent être accordées que si le flux l'exige.
Commandes et statuts
On associe chaque statut :
| WooCommerce | ERP | Action |
|---|---|---|
| pending | en attente | ne pas réserver ou règle spécifique |
| processing | confirmé | réserver/préparer |
| completed | expédié/clôturé | clôturer selon le processus |
| cancelled | annulé | libérer |
| refunded | retour/avoir | flux financier |
| failed | échec | ne pas préparer |
Le mappage s'adapte à la passerelle et à la logistique. On ne facture 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épassé vérifient d'abord si l'opération existe déjà.
Stock
Définir :
- Stock physique.
- Réservé.
- Disponible à la vente.
- Stock de sécurité.
- Rupture différée (backorder).
- Plusieurs entrepôts.
- Kits et variations.
La boutique doit recevoir le disponible, pas nécessairement le physique. La fréquence dépend de la rotation et du risque de survente.
On réalise une réconciliation par SKU et des alertes en cas d'écarts.
Prix et promotions
Décider où vivent tarifs, coupons, taxes et arrondis. L'ERP reçoit un détail suffisant pour reconstituer le total.
Les promotions complexes peuvent être enregistrées comme une remise traçable. On ne recalcule pas dans l'ERP d'une façon qui change le montant facturé.
Taxes
On teste B2C/B2B, territoires, exonérations, taux, frais de port et remises. La localisation fiscale et les obligations de facturation doivent être validées.
WooCommerce calcule la vente ; l'ERP doit accepter ou valider selon la conception, sans générer d'écarts silencieux.
Clients et confidentialité
Pour la vente en tant qu'invité, on évite de créer des doublons pour chaque variante d'un e-mail. On définit une règle de correspondance et le moment de mettre à jour les données.
L'intégration minimise les données, contrôle les rôles et les contrats et applique une durée de conservation. Le marketing ne se déclenche pas automatiquement à l'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 retours sont rattachés à l'original.
Une facture émise n'est jamais modifiée pour un changement de commande ; on applique le circuit fiscal correct.
Paiements
La commande, la transaction et le règlement sont des objets distincts. On réconcilie :
- Montant de la commande.
- Encaissement.
- Commission.
- Remboursement.
- Rétrofacturation (chargeback).
- Règlement bancaire.
Un webhook de commande ne prouve pas que l'argent est réglé.
Expéditions et retours
L'ERP/WMS envoie transporteur, suivi, colis et statut. Les retours génèrent autorisation, réception, inspection, avoir et remise en stock selon l'état.
On ne remet pas le stock à jour lors de la demande de retour ; cela se fait à la réception et après validation.
Gestion des erreurs
La file d'erreurs affiche :
- Événement.
- Commande/SKU.
- Cause.
- Tentatives.
- Dernière réponse.
- Propriétaire.
- Action.
Les erreurs permanentes — par exemple un SKU inexistant — ne sont pas retentées indéfiniment. On corrige la donnée puis on retraite.
Observabilité
Indicateurs :
- 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 client.
- Variations.
- Coupon.
- Plusieurs taxes.
- Paiement échoué.
- Remboursement partiel.
- Annulation.
- Stock concurrent.
- Webhook dupliqué.
- ERP indisponible.
- WooCommerce indisponible.
- Changement de SKU.
- Retour.
Plan de déploiement
Jours 1 à 30
Maîtres, statuts, taxes, architecture et sécurité.
Jours 31 à 60
API, webhooks, files d'attente, idempotence et tests.
Jours 61 à 90
Pilote, réconciliation, alertes et production.
Erreurs fréquentes
- Absence de source maîtresse.
- Utiliser les noms comme clé.
- Ne se fier qu'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 réconciliation quotidienne.
Checklist
- Maîtres.
- Identifiants.
- Statuts.
- Idempotence.
- Stock disponible.
- Prix et taxes.
- Clients et confidentialité.
- Factures et paiements.
- Erreurs et alertes.
- Réconciliation et annulation.
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 une interrogation et une réconciliation.
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, la réconciliation et le monitoring.