Quels hooks WooCommerce utiliser dans le tunnel de commande ?

Une demande fonctionnelle sur une boutique se traduit presque toujours par la même question technique : à quel moment exact du parcours faut il intervenir. Poser un traitement au mauvais endroit du tunnel de commande WooCommerce donne un code qui fonctionne en apparence et qui casse dans les cas particuliers, un paiement différé, une commande créée depuis l'administration, une relance après abandon. La différence entre une intégration solide et une intégration qui produira des tickets pendant deux ans tient moins à la qualité du code qu'au choix du point d'entrée. Cette carte des crochets disponibles, étape par étape, sert à faire ce choix en connaissance de cause plutôt qu'en recopiant le premier exemple trouvé.

Où se placent les points d'entrée du tunnel

Avant de choisir un crochet, il faut savoir ce que WooCommerce considère comme un panier, une commande et un paiement, ces trois objets ayant des cycles de vie distincts. Nous abordons régulièrement ces mécanismes dans la rubrique WooCommerce consacrée à l'exploitation des boutiques.

Trois étapes, trois frontières

Le parcours se divise en trois zones aux règles très différentes : le panier, qui vit dans la session du visiteur et n'existe nulle part en base de façon durable ; la validation, qui transforme ce panier en commande enregistrée ; l'après commande, où la commande change de statut au gré du paiement et de la logistique. Chaque zone dispose de ses propres crochets, et un traitement placé dans la mauvaise zone ne verra tout simplement pas les données dont il a besoin, ce qui se manifeste par des valeurs vides plutôt que par une erreur explicite.

Le panier n'est pas une commande

Tant que la validation n'a pas eu lieu, rien n'est enregistré : les montants sont recalculés à chaque requête, les articles vivent en session, et une modification effectuée sur le panier disparaît au rechargement si elle n'est pas rejouée à chaque calcul. C'est la source d'erreur la plus fréquente sur les remises appliquées par code personnalisé, qui fonctionnent au premier affichage puis se volatilisent. Toute intervention sur le panier doit donc être écrite comme un recalcul reproductible et non comme une action ponctuelle.

Ce qui se joue à la validation

La validation enchaîne en quelques millisecondes le contrôle des champs, la création de l'objet commande, l'enregistrement des lignes avec leurs prix figés, la réservation du stock puis la transmission à la passerelle de paiement. Chacune de ces sous étapes offre un point d'accroche, et la différence entre deux crochets voisins peut être décisive : agir avant la création de la commande permet de bloquer, agir après permet d'enrichir mais plus d'empêcher. Le choix se fait donc selon que l'on veut interdire ou compléter.

L'après commande et ses statuts

Une fois la commande créée, tout se joue sur les changements de statut. Une commande passe successivement par un statut d'attente de paiement, un statut de traitement, puis un statut terminé, avec des variantes selon la passerelle et le mode de livraison. Les crochets liés aux transitions de statut sont les plus fiables de tout le système, parce qu'ils se déclenchent quelle que soit l'origine du changement : paiement en ligne, validation manuelle depuis l'administration, appel par une interface de programmation ou traitement par lot.

Le cas du tunnel par blocs

Le tunnel de commande construit avec les blocs de l'éditeur ne fonctionne pas comme le tunnel historique : l'interface est produite côté navigateur et communique avec le serveur par des appels dédiés, ce qui rend inopérants la plupart des crochets d'affichage. Les traitements côté serveur, en revanche, restent valables. Avant d'écrire la moindre ligne, il faut donc savoir lequel des deux tunnels est en place, sous peine d'écrire un code parfaitement correct qui ne s'exécutera jamais. La vérification prend dix secondes : il suffit de regarder le contenu de la page de commande dans l'éditeur, la présence d'un bloc dédié tranchant la question sans ambiguïté.

Intercepter le panier

Les besoins portant sur le panier sont les plus courants et les plus piégeux, précisément à cause de son caractère recalculé. Le suivi de ces étapes dans les outils de mesure suit la même logique, comme nous le détaillons à propos du suivi du tunnel de conversion avec Google Analytics 4.

Modifier un prix à la volée

Une remise conditionnelle, un tarif par quantité ou un prix négocié se posent en parcourant les articles du panier au moment du calcul des totaux et en fixant le prix de chaque ligne. Le traitement doit être écrit pour s'exécuter à chaque calcul, sans dépendre d'un état enregistré ailleurs, et il doit rester rapide puisqu'il tourne à chaque affichage. C'est aussi le seul endroit où le prix peut être changé de façon cohérente, un prix modifié après création de la commande n'étant plus répercuté sur les totaux ni sur les taxes. Il vaut également mieux conserver la trace de la remise appliquée sur la ligne concernée, sous forme de donnée ou de libellé, afin que le service client puisse expliquer un montant sans avoir à relire le code.

Ajouter un article automatiquement

Offrir un cadeau au delà d'un montant ou imposer un accessoire obligatoire suppose d'ajouter une ligne au panier lors du calcul, puis de la retirer si la condition n'est plus remplie. Les deux mouvements sont indispensables : les implémentations qui n'écrivent que l'ajout produisent des paniers où le cadeau reste après suppression du produit déclencheur. Il faut également neutraliser les contrôles de stock et les notifications habituelles sur cette ligne, sous peine de messages incompréhensibles pour le client.

Bloquer une combinaison d'articles

Interdire l'achat simultané de deux produits incompatibles, ou imposer un minimum de commande, se fait par un contrôle exécuté lors de la validation du panier, qui ajoute une notification bloquante. Le message doit expliquer précisément ce qui coince et comment le résoudre, car un blocage sans explication produit un abandon immédiat. Le contrôle doit par ailleurs être rejoué à la validation finale, un panier pouvant être constitué puis validé plusieurs heures après, dans un état entre temps devenu invalide. Une rupture de stock survenue pendant ce délai relève exactement du même mécanisme, et les boutiques qui ne rejouent pas leurs contrôles à la validation finale enregistrent régulièrement des commandes qu'elles ne peuvent pas honorer.

Adapter les frais de livraison

Les frais dépendant du poids, du volume, de la zone ou de la nature des articles se calculent dans les méthodes de livraison plutôt que dans le panier. Écrire ce calcul ailleurs conduit à des montants incohérents entre l'estimation affichée dans le panier et le montant réellement facturé, écart que le client remarque toujours. Le cache des taux de livraison mérite une attention particulière : il conserve les résultats précédents et masque les modifications tant qu'il n'est pas invalidé, ce qui fait perdre un temps considérable en développement. Le réflexe à prendre consiste à vider ce cache après chaque modification du calcul, faute de quoi on corrige un code déjà correct pendant une heure avant de comprendre que le montant affiché date de la version précédente.

Afficher un message conditionnel

Un encart signalant qu'il manque quelques euros pour la livraison offerte se place dans les zones d'affichage prévues autour du panier et des totaux. Ce genre de message a un effet mesurable sur le panier moyen, à condition qu'il soit précis et actualisé à chaque modification. Sur un tunnel par blocs, l'affichage passe par un composant dédié plutôt que par un crochet, ce qui change complètement la méthode et demande de vérifier le type de tunnel avant de s'engager.

Recalculer sans casser le cache

Les pages contenant un panier ne doivent jamais être servies depuis un cache de page complet, sous peine d'afficher le panier d'un autre visiteur. Cette règle est connue mais régulièrement contournée par des configurations agressives destinées à améliorer les performances. Lorsqu'un fragment dynamique doit apparaître sur une page en cache, comme un compteur d'articles, il doit être chargé par un appel séparé, et non intégré au document mis en cache, faute de quoi le compteur affiche une valeur qui n'est celle de personne.

Intercepter la validation de commande

C'est l'étape la plus courte et la plus dense. Quelques millisecondes séparent le clic du client de la redirection vers la passerelle, et une demi douzaine de points d'accroche s'y succèdent dans un ordre qui compte.

Ajouter un champ au formulaire

Un numéro de commande interne, une mention de livraison ou une case à cocher se déclarent en modifiant la liste des champs du formulaire de validation. La déclaration porte le type, l'obligation, la position et le libellé, ce qui suffit dans la plupart des cas sans écrire d'affichage sur mesure. Sur un tunnel par blocs, la même chose passe par un mécanisme d'extension distinct, plus verbeux mais plus propre, qui déclare les champs auprès de l'interface plutôt que dans le gabarit.

Valider une saisie et bloquer proprement

Le contrôle des champs s'effectue juste avant la création de la commande et permet d'empêcher celle ci en ajoutant une erreur. C'est le dernier moment où bloquer reste possible sans conséquence : passé ce point, la commande existe, et l'annuler laisse une trace, décrémente parfois le stock et peut déclencher un courriel. La règle est donc de tout contrôler ici, y compris ce qui a déjà été contrôlé plus tôt dans le parcours, le panier ayant pu changer entre temps.

Enregistrer une donnée sur la commande

Les informations complémentaires se stockent sur l'objet commande juste après sa création, en utilisant les méthodes fournies plutôt qu'un accès direct aux métadonnées. Cette distinction est devenue déterminante depuis que les commandes disposent de leurs propres tables : un code écrivant directement dans les anciennes tables fonctionne sur les installations en compatibilité et échoue silencieusement sur les autres. Utiliser les méthodes de l'objet garantit l'écriture au bon endroit quelle que soit la configuration en place.

Agir juste avant le paiement

Un dernier point d'accroche précède la transmission à la passerelle et convient aux traitements devant intervenir alors que la commande existe mais que le client n'a pas encore quitté le site : réserver une ressource, générer une référence externe, appeler un service de contrôle. Ce traitement doit être rapide et tolérant à la panne, puisqu'une erreur non gérée à cet instant laisse le client devant une page blanche avec une commande créée et non payée, situation particulièrement désagréable à rattraper.

Réagir au retour du paiement

Le retour de la passerelle emprunte deux chemins distincts : le retour du navigateur, où le client revient sur le site, et la notification serveur à serveur, envoyée indépendamment. Seule la seconde est fiable, le client pouvant fermer son navigateur avant la redirection. Tout traitement conditionné par le paiement doit donc s'accrocher à la notification serveur, ou mieux, à la transition de statut qu'elle provoque, ce qui couvre aussi les paiements validés manuellement.

Intercepter l'après commande

C'est la zone la plus stable et celle où placer tout ce qui n'a pas besoin d'être synchrone. La plupart des intégrations mal placées ailleurs y trouveraient leur point d'accroche naturel.

Les transitions de statut

Deux familles de crochets existent : ceux qui se déclenchent à l'entrée dans un statut donné, et celui qui se déclenche à tout changement en fournissant l'ancien et le nouveau statut. Le second est préférable dès que la logique dépend de l'état précédent, par exemple pour distinguer une commande passée directement au statut terminé d'une commande revenue à ce statut après un remboursement partiel. Le premier suffit pour les cas simples et se lit mieux.

Le bon crochet pour une intégration

Transmettre une commande à un système de gestion, à un service d'expédition ou à un outil comptable se déclenche sur le passage au statut de traitement, qui signale un paiement encaissé et une commande à préparer. C'est le point le plus fiable parce qu'il est atteint quelle que soit la façon dont la commande a été payée. Le traitement lui même doit être déporté en tâche de fond plutôt qu'exécuté dans la requête, un service distant lent ne devant jamais retarder l'affichage de la page de confirmation. La communication avec ces systèmes tiers passe souvent par l'interface décrite dans notre article sur la manière de lire et écrire le catalogue depuis un outil externe.

L'idempotence, condition indispensable

Un crochet de statut peut se déclencher plusieurs fois pour une même commande : rejeu d'une notification, modification manuelle, reprise après incident. Tout traitement à effet externe, envoi de facture, création de bon de préparation, débit d'un stock distant, doit donc vérifier qu'il n'a pas déjà été effectué, en posant un marqueur sur la commande. Sans cette précaution, un simple changement de statut dans l'administration peut envoyer deux fois la même expédition à un prestataire logistique.

Les courriels transactionnels

Les messages envoyés au client se personnalisent à trois niveaux : le contenu, par des crochets d'affichage placés dans les gabarits ; la structure, par surcharge des fichiers de gabarit dans le thème ; l'envoi lui même, en conditionnant le déclenchement. La surcharge de gabarit est la méthode la plus utilisée et la plus fragile, une mise à jour majeure pouvant modifier le fichier d'origine sans que la copie ne suive. Un contrôle des surcharges après chaque mise à jour importante évite les mauvaises surprises.

Les erreurs à ne pas commettre

Trois erreurs reviennent constamment : écrire du code dans le fichier de fonctions du thème, ce qui le fait disparaître au changement de thème ; effectuer des appels distants de façon synchrone dans le tunnel, ce qui rend la boutique dépendante d'un service tiers ; et modifier une commande après sa création en supposant que les totaux se recalculeront, ce qui n'arrive pas. Ces trois habitudes produisent des boutiques qui fonctionnent parfaitement jusqu'au jour où un élément extérieur change.

Tester ce genre de code

Un tunnel se teste avec au minimum quatre scénarios : un paiement réussi, un paiement échoué puis réessayé, une commande créée manuellement depuis l'administration, et un remboursement partiel. Ces quatre cas couvrent l'essentiel des chemins par lesquels une commande peut passer, et ils révèlent immédiatement les traitements accrochés au mauvais endroit. Les passerelles proposant toutes un environnement de test, ce parcours prend une demi heure et évite de découvrir un défaut sur une commande réelle. Elle se refait après chaque mise à jour majeure de la boutique, moment où les points d'accroche changent parfois de position sans que rien ne le signale dans les notes de version.