La commande apparaît dans WooCommerce, le client a reçu son message de confirmation, mais l’ERP ne l’a jamais importée. L’export planifié répond pourtant correctement. Après l’activation de HPOS, il peut encore interroger une copie ancienne dans les tables WordPress, ou attendre une métadonnée que le connecteur écrit désormais au mauvais endroit. Un traitement techniquement réussi peut ainsi ne plus voir les nouvelles ventes.
Le risque est de croire qu’une base contenant encore les anciennes commandes reste la source utilisée par la boutique. HPOS sépare le stockage actif et sa copie de compatibilité. Le diagnostic commence par retrouver le chemin de lecture et d’écriture de votre connecteur, avant de forcer une synchronisation ou de rejouer toutes les commandes vers l’ERP.
Ce dossier cible les extensions WordPress, exports SQL et traitements spécifiques qui accèdent aux commandes. Un middleware consommant correctement l’API REST WooCommerce n’a pas, par principe, à réécrire ses appels pour HPOS. Notre prestation d’intégration API et notre accompagnement WooCommerce vers votre système de gestion permettent de qualifier lequel de ces chemins porte réellement les écarts.
Pour qui : une intégration ERP qui dépend du stockage des commandes
Identifier les consommateurs réellement concernés
Retrouvez le plugin qui prépare les fichiers, le script comptable connecté à MySQL, la tâche planifiée et le composant qui marque une commande comme exportée. Une API REST située en façade peut masquer une extension interne qui lit directement les tables. À l’inverse, la présence de WooCommerce dans un flux ne prouve pas que le middleware connaisse son stockage physique.
Les symptômes utiles sont sélectifs : commandes récentes absentes, totaux différents entre export et administration, ancien statut toujours transmis, accusé ERP introuvable après un import confirmé. Faites rapprocher ces symptômes par identifiant de commande et boutique source. Le délai de préparation et les recherches manuelles du service client permettent de mesurer le coût concret de cet écart, sans le confondre avec une panne complète du checkout.
Distinguer migration technique et éligibilité métier
Une commande visible n’est pas nécessairement autorisée à partir vers la préparation. Votre contrat peut attendre une validation, un paiement ou une information B2B. HPOS ne définit pas ces décisions. Vérifiez d’abord que le connecteur lit la bonne version, puis appliquez la règle métier habituelle ; ne modifiez pas les statuts admis simplement pour faire remonter davantage de lignes.
Le périmètre doit également nommer remboursements, commandes d’abonnement et types personnalisés. Le lecteur minimal présenté plus loin accepte uniquement un objet de commande standard. Il refuse un autre type au lieu de l’exporter comme une vente. Les extensions qui ajoutent leurs propres objets ou métadonnées demandent une recette spécifique avec leur mainteneur.
Plan d’action : prouver quelle copie votre connecteur utilise
Ouvrir un dossier d’écart avec les bonnes entrées
Le contrat de diagnostic prend en entrée la boutique, l’identifiant interne de commande, la version de WooCommerce et le composant d’export. Sa sortie attendue compare le stockage actif, la représentation lue et la destination ERP. La journalisation conserve le chemin de traitement et le motif d’exclusion ; elle n’a pas besoin de recopier les adresses clients, les clés REST ou les données de paiement.
Retenez une commande créée avant la bascule, une créée après et une commande récemment modifiée. Pour chacune, comparez statut, montant, devise et référence d’import. Ajoutez une commande traitée correctement comme témoin. Une différence de nombre de commandes ne suffit pas à diagnostiquer le stockage ; les mêmes nombres peuvent couvrir des identifiants différents ou un filtre métier qui a changé.
Refuser le replay tant que l’effet ERP reste incertain
Si WooCommerce ne voit plus son accusé alors que l’ERP a créé la vente, une réémission libre peut produire un doublon. Le seuil d’arrêt du runbook est ici cette incertitude sur la destination. Isolez la commande, recherchez sa référence dans l’ERP avec la même identité source et corrigez ensuite la preuve locale. Un marqueur absent dans une copie WordPress ne démontre pas un import absent.
Cette règle concerne aussi les imports relancés après un timeout. Préservez le payload déjà envoyé et la corrélation plutôt que de reconstruire une « nouvelle » commande. Le responsable du raccordement décide si le dossier doit être relu, rapproché ou réellement transmis. Le repli peut maintenir certains exports en attente sans interrompre les autres fonctions de la boutique.
- D’abord confirmer le stockage actif et le chemin d’accès de l’export.
- Puis comparer les identifiants et valeurs des commandes concernées.
- Bloquer les réémissions dont l’effet ERP n’est pas rapproché.
- Autoriser une reprise ciblée après correction du lecteur et de son accusé.
Comprendre la source active et les tables de compatibilité HPOS
La présence de données ne donne pas leur autorité
WooCommerce distingue les tables faisant autorité et celles recevant leur copie. Lorsque HPOS est actif, les tables dédiées portent le fonctionnement courant ; les tables de posts peuvent servir de stockage de secours synchronisé. Dans l’autre configuration, les rôles s’inversent. Vérifiez le paramétrage réel : HPOS activé par défaut sur les nouvelles installations depuis WooCommerce 8.2 ne décrit pas automatiquement une boutique plus ancienne.
Un ancien export peut continuer à trouver des lignes plausibles, surtout si les commandes historiques ont été copiées. Cette réussite partielle retarde le diagnostic. Comparez une valeur qui a changé et une identité qui n’existait pas avant la bascule. Vous pourrez distinguer une copie en retard d’un filtre supprimant certaines commandes, au lieu de prendre un échantillon ancien pour une preuve de fonctionnement actuel.
La synchronisation ne valide pas un accès direct
Le mode de compatibilité facilite la transition, mais il ne transforme pas un accès direct à posts/postmeta en interface durable de commande. La recette officielle avertit qu’une lecture peut être obsolète et qu’une écriture directe peut ne pas être consommée par le stockage actif. Le connecteur doit qualifier ses deux sens d’accès, y compris les petites écritures de métadonnées qui semblent indépendantes de la commande.
En réalité, relancer la copie peut masquer temporairement le mauvais lecteur. S’il reste dépendant de cette copie, l’écart reviendra lors d’un autre changement de configuration ou d’une synchronisation différée. Déterminez si ce mode est un dispositif de transition documenté, avec sa sortie, ou une dépendance involontaire devenue indispensable à l’ERP.
Auditer le code WordPress sans condamner tous les accès aux métadonnées
Chercher les appels qui manipulent effectivement une commande
Dans le plugin d’intégration et les scripts associés, recherchez notamment get_post_meta, update_post_meta, get_posts, WP_Query, shop_order et les requêtes SQL sur les tables de posts. Suivez ensuite l’identifiant utilisé. Le même appel WordPress peut concerner un produit, une page ou une commande ; le résultat textuel d’une recherche impose une revue, pas une déclaration automatique d’incompatibilité.
Documentez chaque chemin confirmé : sélection des commandes à exporter, lecture du détail, recherche de la référence ERP, écriture de l’accusé et écran de contrôle. Un correctif limité au détail de commande peut laisser la sélection du lot sur l’ancienne table. L’export saura alors lire correctement une commande lorsqu’on lui donne son identifiant, tout en ne la sélectionnant jamais dans son traitement planifié.
Inclure les consommateurs externes à WordPress
Les scripts d’un prestataire comptable, un entrepôt de données ou un export lancé sur une réplique peuvent échapper à l’audit du plugin. Recensez leurs utilisateurs techniques et les tables réellement interrogées. Un changement du plugin WooCommerce ne corrige pas ces consommateurs. Pour un accès externe, examinez une lecture par API ou une projection d’export explicitement maintenue, avec son délai de fraîcheur.
Une extraction SQL spécifique peut rester nécessaire dans certains contextes, mais elle devient alors un contrat à maintenir et à tester pour le stockage ciblé. Ne remplacez pas simplement le nom d’une table : propriétés, métadonnées et relations ne se répartissent pas forcément de la même manière. L’équipe qui porte cet export doit aussi porter ses tests de compatibilité et son adaptation aux évolutions du schéma.
Lire la commande avec les objets WooCommerce plutôt qu’avec sa copie physique
Préparer un lecteur minimal qui refuse les objets inattendus
Les API CRUD WooCommerce sélectionnent le stockage actif. Le lecteur suivant utilise wc_get_order puis les accesseurs de l’objet. Il suppose WordPress et WooCommerce chargés, une boutique source qualifiée et un appel depuis un contexte applicatif autorisé. Il s’agit d’un fragment d’adaptateur, sans route publique, contrôle d’accès complet ni export des lignes de commande.
function erp_order_snapshot(string $sourceShop, int $orderId): array
{
if (trim($sourceShop) === '' || $orderId <= 0) {
throw new InvalidArgumentException('Missing source identity');
}
$order = wc_get_order($orderId);
if (!($order instanceof WC_Order) || $order->get_type() !== 'shop_order') {
throw new RuntimeException('Standard order required');
}
return [
'source_shop' => $sourceShop,
'order_id' => $order->get_id(),
'status' => $order->get_status(),
'total' => $order->get_total(),
'currency' => $order->get_currency(),
'erp_reference' => $order->get_meta('_erp_export_ref', true),
];
}La clé _erp_export_ref est fictive : identifiez celle que votre extension possède réellement et son format. Ce lecteur conserve montant et devise ensemble. Son mapping vers le payload ERP doit préserver ces deux valeurs. Il ne conclut ni que le paiement est encaissé, ni que la commande doit être expédiée. Sa première responsabilité est de fournir une représentation cohérente au composant qui applique ces règles métier.
Tester les valeurs et les extensions autour de l’objet
Sur votre environnement de recette, comparez le résultat avec les commandes du dossier d’incident, puis avec les métadonnées ajoutées par vos extensions. Les accesseurs ne certifient pas qu’un champ propriétaire est disponible au moment choisi par votre hook. Un calcul différé, un cache ou une extension peut encore modifier le résultat attendu ; ces dépendances doivent figurer dans le scénario testé.
Vérifiez aussi le comportement d’un identifiant inconnu et celui d’un remboursement présenté au même adaptateur. Un retour inattendu doit remonter avec une raison lisible. Transformer ces cas en tableau vide donnerait au traitement aval une fausse impression de succès et compliquerait le rapprochement des commandes absentes de l’ERP.
Vérifier la sélection des lots et les filtres spécifiques à votre stockage
Ne pas remplacer seulement la lecture d’un identifiant
Les interfaces wc_get_orders et WC_Order_Query fournissent les mécanismes de sélection de commandes. La documentation actuelle décrit notamment limit, paged et paginate. Avec la pagination activée, le résultat expose les commandes, un total et un nombre de pages. Conservez les identifiants parcourus pour rapprocher le lot ; ne validez pas la couverture à partir du seul nombre affiché.
Un parcours paginé reste sensible aux modifications qui surviennent pendant la lecture. Pour une reprise, définissez la cohorte à traiter et un point de contrôle persistant. Les webhooks peuvent signaler une commande à relire, tandis qu’un traitement de rapprochement vérifie les omissions. HPOS ne donne pas, à lui seul, un export exactement une fois entre WooCommerce et votre ERP.
Recetter les paramètres et hooks personnalisés
Les filtres avancés meta_query, field_query et date_query décrits par la référence actuelle dépendent de HPOS. Les hooks de requête personnalisée diffèrent également entre les deux stockages. Une extension qui ajoutait son propre paramètre de sélection doit donc vérifier son traitement sur chacun des modes qu’elle revendique prendre en charge.
Par exemple, si votre sélection attend une métadonnée « exportable », testez une commande qui la possède et une qui ne la possède pas, puis comparez les identifiants retenus dans chaque configuration supportée. La correction doit expliquer l’écart de sélection observé. Ne remplacez pas le filtre manquant par l’export de toutes les commandes sans qualification de leur éligibilité métier.
Écrire et relire l’accusé ERP sans dépendre d’une métadonnée ancienne
L’effet distant et sa preuve locale sont deux étapes
Une commande peut avoir été créée dans l’ERP avant que son accusé soit enregistré dans WooCommerce. Si le connecteur écrit cet accusé dans la mauvaise copie, le prochain worker peut la considérer comme non traitée. Le banc local reproduit cette situation : une ligne ERP existe, la copie ancienne porte sa référence, mais la représentation active ne la voit toujours pas.
La journalisation doit relier en entrée l’identité boutique-commande et l’opération envoyée ; en sortie, la référence distante confirmée et l’état de l’accusé. La file de retry distingue alors un envoi incertain d’un simple accusé à réparer. Cette séparation est nécessaire même lorsqu’une contrainte d’idempotence protège déjà l’import ERP, car le support doit pouvoir expliquer pourquoi la commande reste en attente.
Passer par l’objet pour les métadonnées de commande
Dans une extension, la recette HPOS préconise les méthodes de métadonnées de l’objet puis sa sauvegarde, plutôt qu’un update_post_meta direct sur une commande. Testez ce chemin en recette, puis rechargez l’objet dans un autre processus pour relire l’accusé. La valeur présente uniquement dans l’instance PHP qui vient d’être modifiée ne prouve pas sa persistance.
Ne changez pas à cette occasion la sémantique de la référence : son propriétaire, sa valeur et le moment où elle devient définitive restent contractuels. Une clé d’export ne remplace pas une preuve de facturation ou de paiement. Vérifiez enfin les hooks déclenchés par la sauvegarde pour éviter qu’une simple correction d’accusé réactive un autre traitement de commande.
Exercice local : observer la copie obsolète et l’accusé invisible
Exécuter 25 contrôles sur des données fictives
Téléchargez le banc local d’export à deux stockages, puis exécutez-le avec Python 3.10 ou supérieur et SQLite 3.24 ou supérieur. Il crée des tables pédagogiques nommées hpos_fixture, posts_fixture et erp_fixture. Ce ne sont pas les tables natives de WooCommerce ; le programme ne se connecte ni à WordPress ni à un ERP et ne modifie aucune option de boutique.
python3 hpos_export_inventory.py
PASS legacy export misses changed and newly created orders
PASS missing identities diagnosed separately from counts
PASS current fixture still has no receipt
PASS local ERP effect already exists despite absent current receipt
CHECKS 25
WooCommerce calls: 0; ERP API calls: 0; WordPress options changed: 0.Dans ce cas concret, le stockage actif contient trois commandes éligibles selon une règle de fixture ; l’ancienne copie n’en exporte qu’une. Les identifiants 501 et 503 manquent pour des raisons différentes : ancien statut pour l’une, ligne absente pour l’autre. L’exercice conserve aussi une différence de montant de 10,00 en calcul décimal exact et une devise CHF qui ne doit pas être remplacée par la devise d’une autre commande.
Séparer ce que le banc prouve de ce qu’il reste à recetter
Les 25 contrôles exécutés vérifient ces projections locales, la séparation des boutiques, l’accusé écrit dans une copie inadéquate et la correspondance ERP après réouverture de la base. Le seuil choisi pour bloquer un changement de stockage est la présence d’une synchronisation en attente. Le programme renvoie seulement une décision de préparation ; il n’effectue aucune bascule ni migration.
L’unicité de la fixture ERP provient d’une contrainte SQLite propre au programme. Elle ne garantit pas l’idempotence de l’API de votre logiciel de gestion. De même, aucune fonction WooCommerce n’est exécutée dans ce banc. Les appels PHP, les filtres d’extension et le cycle de sauvegarde doivent être testés sur un WordPress de recette représentant votre configuration.
| Cas local | Résultat constaté | Contrôle natif à prévoir |
|---|---|---|
| Statut changé | Ancien export incomplet | Lecteur et filtre du plugin |
| Nouvelle commande | Copie sans ligne | Création après bascule |
| Accusé dans la copie | Référence active absente | Sauvegarde puis relecture |
| Effet ERP déjà présent | Référence locale retrouvée | Lecture ERP |
| Copie en attente | Plan de bascule bloqué | État HPOS réel |
Utiliser les diagnostics HPOS avant toute décision de bascule
Contrôler l’état et les différences d’une commande
La référence CLI actuelle utilise wp wc hpos ; l’ancien espace wp wc cot est déprécié. Vérifiez l’aide de la version installée, puis le statut et les différences d’une commande du dossier dans le contexte de la bonne boutique. La commande diff sert au diagnostic entre stockages lorsqu’une comparaison pertinente est disponible ; elle ne réconcilie pas elle-même les données.
Les fonctions de synchronisation, de réécriture et de nettoyage constituent d’autres opérations. Elles ne doivent pas être intégrées au même script de diagnostic en supposant que le stockage source est toujours le bon. Une différence récente dans l’ancienne copie peut venir d’une écriture de plugin incompatible ; copiez-la vers la source active seulement après qualification de sa valeur métier et de son origine.
Recetter avec et sans copie de compatibilité
Sur un environnement isolé, testez les modes que votre extension doit supporter, avec les mêmes parcours de paiement, remboursement et export. La procédure officielle pour les boutiques importantes demande aussi d’inclure les systèmes externes lisant directement la base. La déclaration de compatibilité d’un plugin ne réalise pas ces tests ; elle doit refléter un audit et des résultats obtenus.
WooCommerce interdit le changement des tables faisant autorité lorsqu’il reste des commandes à synchroniser. Même avec un compteur à zéro, il faut encore vérifier les extensions, les données rapprochées et le plan de retour. Une bascule de stockage n’est pas le premier correctif à appliquer à une commande ERP absente : corrigez le chemin d’accès qui a produit cet écart.
Erreurs fréquentes : des contournements qui rétablissent seulement l’apparence
Lire la copie ou réécrire les tables à la main
Une requête SQL retournant les bons totaux sur des commandes anciennes ne démontre pas la compatibilité HPOS. Ajoutez une commande nouvellement créée et une modification récente, puis rapprochez leurs identifiants. Le test doit vérifier l’accès du connecteur, pas seulement l’état de la copie au moment où un administrateur l’observe.
Évitez également les corrections manuelles dans les deux stockages pour les rendre « identiques ». Vous perdriez l’origine de la divergence et pourriez écraser une valeur plus récente. Gardez la décision, le composant fautif et la valeur autorisée avant une opération de réparation native testée en recette.
Déclarer la compatibilité avant de traiter le sélectionneur
Changer get_post_meta dans le détail de commande ne suffit pas si le lot reste construit par une ancienne requête ou un hook qui n’est plus appelé. La recette doit déclencher le traitement planifié complet. Fournir manuellement un identifiant au nouveau lecteur ne teste que la seconde moitié du parcours.
Le diagnostic des limites WooCommerce vers ERP aide à cadrer les extensions et objets métier hors standard. Le contrat d’échange ERP complète la définition de l’accusé et de la reprise. Conservez ces règles lorsque vous changez l’accès au stockage, au lieu de redéfinir silencieusement une commande exportable.
Sources WooCommerce et preuves à conserver pour votre version
Vérifier le stockage, les accesseurs et les requêtes
Consultées le 15 octobre 2026 : architecture et autorité des stockages HPOS, recette de compatibilité des extensions, requêtes de commandes et référence de WC_Order. Les fragments PHP sont à qualifier dans votre environnement ; le banc Python reste une démonstration séparée.
Conservez avec la recette la version du plugin d’intégration, ses paramètres de sélection et les métadonnées dont il est propriétaire. Les liens officiels décrivent les interfaces ; ils ne prouvent pas que votre extension les utilise ou que le dernier déploiement a chargé le code attendu.
Vérifier l’aide CLI réellement disponible
La référence CLI HPOS distingue diagnostic, synchronisation, réécriture et nettoyage. Le préparation des boutiques importantes précise les parcours à tester. Certaines pages générales conservent d’anciens noms de commandes : confrontez-les à l’aide de votre installation avant d’écrire une procédure.
Le dossier de validation doit montrer un exemple de commande relue, un lot sélectionné et un accusé persistant après rechargement. Ajoutez un effet ERP déjà présent pour vérifier le refus de doublon. Ces preuves répondent directement à l’incident initial, contrairement à une simple capture de l’option HPOS activée.
Conclusion : corriger le chemin de commande avant de relancer les imports
Lorsqu’une commande existe dans WooCommerce mais manque dans l’ERP, retrouvez la source réellement lue par le connecteur. HPOS peut révéler un accès direct resté dépendant d’une copie ancienne. La correction doit couvrir la sélection du lot, le détail de commande et la persistance de l’accusé, avec des preuves distinctes pour chaque étape.
Le banc local montre pourquoi une copie plausible peut omettre une commande modifiée ou une identité nouvelle, et pourquoi un accusé absent ne prouve pas l’absence de vente distante. Pour qualifier votre extension, le relais WooCommerce et ERP permet d’examiner les modes de stockage et les parcours particuliers de votre boutique.
Notre équipe d’intégration API peut vous accompagner pour auditer l’export existant, adapter le plugin ou le middleware et recetter une reprise limitée aux commandes rapprochées. Le résultat attendu est une transmission explicable depuis la boutique jusqu’à la référence ERP, avec un accusé que les prochains traitements relisent effectivement.
