La marque de cosmétiques souhaitait un site vitrine et un tunnel d’achat entièrement construits en Next.js, pour des raisons de performance perçue et de cohérence avec le reste de leur écosystème front-end, tout en conservant WooCommerce comme moteur de gestion des commandes, du catalogue et des stocks, déjà connecté à leur système de facturation. Ce découplage, souvent qualifié de « headless », pose une question d’architecture précise dès qu’il s’agit du panier et du paiement : quelle API interroger, et avec quelle gestion de session côté front.
La réponse a fini par tenir dans un seul acronyme, moins connu que l’API REST classique de WooCommerce : la Store API, conçue dès l’origine pour servir de socle aux blocs Panier et Paiement, mais parfaitement utilisable telle quelle depuis n’importe quel front-end, y compris hors de l’écosystème WordPress.
Pourquoi pas l’API REST classique pour le panier
L’API REST v3 de WooCommerce, exposée sous /wp-json/wc/v3/, a été conçue pour des opérations d’administration ou d’intégration serveur à serveur : gestion du catalogue, création de commandes par un système tiers, synchronisation ERP. Elle exige une authentification par clé consommateur, peu adaptée à un panier public manipulé directement par le navigateur d’un visiteur anonyme, sans compte ni authentification préalable.
La Store API, pensée pour ce cas précis
La Store API, exposée sous /wp-json/wc/store/v1/, répond directement à ce besoin : elle permet d’ajouter un produit au panier, de consulter son contenu, d’appliquer un code promotionnel et de finaliser une commande, sans nécessiter de clé d’API, en s’appuyant sur la session du visiteur identifiée par un cookie. Chaque réponse de cette API renvoie un jeton transmis dans l’en-tête Nonce, qu’il faut faire circuler à chaque appel suivant via l’en-tête X-WC-Store-API-Nonce, sous peine de voir les requêtes suivantes rejetées.
Vue d’ensemble de l’architecture retenue
Navigateur (Next.js, rendu côté serveur et client)
│
├── Lecture catalogue ─────► Store API /products (public, sans clé)
│
├── Panier et paiement ───► Store API /cart, /checkout
│ (cookie de session + nonce)
│
└── Contenu éditorial ────► API REST WordPress /wp/v2/
(pages, articles, pas de session)
WordPress + WooCommerce (backend headless)
│
├── Gestion du catalogue, des stocks, des tarifs
├── Traitement des commandes, webhooks vers la facturation
└── Emails transactionnels natifs conservés tels quels
Le point délicat : faire vivre le cookie de session entre deux domaines
Le front Next.js et l’installation WordPress ne partageaient pas le même nom de domaine, ce qui a nécessité une attention particulière sur la configuration des cookies. Le cookie de session WooCommerce doit circuler entre les deux origines pour que le panier reste cohérent d’un appel à l’autre, ce qui a demandé de configurer explicitement les en-têtes Access-Control-Allow-Credentials côté WordPress, et de systématiser l’option credentials: 'include' sur chaque appel fetch effectué depuis le front.
Sans cette précaution, chaque appel Store API générait une nouvelle session vierge côté serveur, ce qui se traduisait par un panier systématiquement vide après un premier ajout de produit, un symptôme trompeur qui a d’abord fait suspecter un problème côté Store API elle-même avant que l’origine réelle, purement liée aux cookies inter-domaines, ne soit identifiée.
Ce que la Store API ne couvre pas
La Store API se limite volontairement au parcours d’achat côté visiteur : elle ne permet pas de gérer le catalogue en écriture, ni d’administrer les commandes après leur création, ce qui reste du ressort de l’API REST v3 classique, utilisée ici uniquement depuis des scripts serveur internes, jamais exposée au front public. De la même manière, le contenu éditorial du site (pages, articles de blog) transitait par l’API REST standard de WordPress, sans lien avec la session panier.
- Store API : panier, paiement, produits en lecture publique, sans clé d’API.
- API REST v3 WooCommerce : administration et intégrations serveur à serveur, avec clé consommateur.
- API REST WordPress standard : contenu éditorial, sans notion de session panier.
Sur un projet headless, la question n’est presque jamais « quelle API choisir » dans l’absolu, mais « quelle API correspond à quel acteur » : un visiteur anonyme avec un panier n’a rien à voir avec un script serveur qui synchronise un catalogue.
Bilan de cette architecture
Cette séparation claire entre Store API pour le parcours d’achat et API REST classique pour l’administration a permis de livrer un front Next.js performant, tout en conservant l’intégralité de la logique métier WooCommerce côté serveur : calcul des taxes, règles de livraison, emails transactionnels, rien de tout cela n’a dû être réimplémenté côté front. Le principal point de vigilance, la gestion du cookie de session inter-domaines, mérite d’être anticipé dès la phase de cadrage technique plutôt que découvert après les premiers tests utilisateurs.
