Chapitre 10.6 — Store API & WooCommerce headless

⏱️ TL;DR — Pour un commerce headless (front Next.js), WooCommerce expose la Store API (/wp-json/wc/store/v1/…) : une API publique pensée pour le front (produits, panier, checkout) qui gère la session panier via des jetons/cookies — contrairement à l’API REST admin (wc/v3) qui, elle, exige une authentification et sert la gestion. Le pattern : Next.js affiche le catalogue (Store API ou WPGraphQL/WooGraphQL), gère le panier (Store API), et délègue le paiement à un flux sécurisé. Le commerce headless est puissant mais complexe (panier, sessions, paiement, taxes, stock) — un créneau premium mais exigeant.

🎯 Objectifs

• Distinguer Store API (front) et REST wc/v3 (admin).
• Comprendre la gestion du panier côté headless.
• Situer les options (Store API, WooGraphQL) pour un front Next.js.
• Peser les difficultés propres au commerce headless.

1. Deux APIs, deux usages

⚠️ Piège n°1 — confondre les deux. La Store API est faite pour être appelée par le navigateur (panier de la session), sans clés. La REST wc/v3 est une API de gestion qui exige une authentification (clés API à garder côté serveur, ch. 9.2) — jamais exposée au client. Utiliser wc/v3 depuis le front (avec des clés dans le bundle) est une faille grave.

2. Le panier en headless (le vrai défi)

Le panier WooCommerce est stateful (session serveur + cookie). La Store API expose des routes pour le manipuler :

GET  /wp-json/wc/store/v1/products         → catalogue (public)
GET  /wp-json/wc/store/v1/cart             → le panier courant
POST /wp-json/wc/store/v1/cart/add-item    → ajouter un article
POST /wp-json/wc/store/v1/cart/update-item → modifier une quantité

• La session panier est suivie par un jeton (en-tête Cart-Token / Nonce) et/ou un cookie : votre front doit propager ces jetons entre les requêtes pour garder « le même panier ».
• En SSR/Next, gérer cette session (côté client pour le panier interactif, ou via un proxy serveur) demande de la rigueur.

⚠️ Piège n°2 — le panier qui se « perd ». Si le front ne transmet pas le Cart-Token/nonce d’une requête à l’autre, chaque appel crée un nouveau panier vide. La gestion de la session panier est le point technique délicat du headless Woo — à cadrer dès le départ (où vit le panier : client, cookie, proxy serveur ?).

3. Les options de front

• Store API (natif) : suffisant pour catalogue + panier ; checkout via les routes Store API (et paiement, §4).
• WooGraphQL (extension WPGraphQL, ch. 9.4) : requêter produits/commandes en GraphQL (payloads précis, typage) — populaire pour des fronts riches ; le panier/checkout reste délicat.
• Solutions dédiées : des frameworks/starters de commerce headless (parfois avec adaptateurs WooCommerce) pré-câblent panier, checkout, session — utiles pour ne pas tout réinventer.

4. Le paiement en headless (le point dur)

Le checkout/paiement est la partie la plus complexe en headless : taxes, expédition, coupons, passerelles (ch. 10.5) souvent conçues pour le checkout serveur. Approches :

• Utiliser les routes checkout de la Store API (qui orchestrent une partie), avec un paiement tokenisé (Stripe côté client → confirmation serveur/webhook).
• Rediriger vers un checkout hébergé (prestataire) pour l’étape paiement, puis revenir.
• Confirmer toujours par webhook (ch. 10.5) — la règle ne change pas en headless.

⚠️ Piège n°3 — sous-estimer le checkout headless. Beaucoup de passerelles et de plugins (taxes, livraison, fraude) supposent le checkout serveur de WooCommerce. Les reproduire en headless est coûteux. Chiffrez cette complexité honnêtement (comme pour le headless en général, ch. 9.7) : un catalogue headless est simple, un checkout headless complet ne l’est pas.

5. Quand faire du commerce headless

• ✅ Oui : marque avec un fort besoin de front custom/perf, catalogue important, équipe front solide, budget pour la complexité checkout/session.
• ❌ Non/prudence : petite boutique standard → un thème WooCommerce (classique/bloc) livre plus vite, avec paiement/taxes/livraison déjà gérés. Le headless e-commerce cumule les coûts cachés du headless (ch. 9.7) et ceux du commerce (session, paiement).

💡 Pour un dev React — Le catalogue headless (produits en Server Components, ISR) est facile et vous êtes chez vous. Le panier/checkout headless est le vrai défi (session stateful, paiement, taxes) — c’est là que la mission devient premium et risquée. Positionnez-vous dessus en connaissance de cause : maîtriser le commerce headless Woo (Store API + panier + paiement) est rare et cher, mais exige de la rigueur. Souvent, un catalogue headless + checkout hébergé/classique est le compromis pragmatique.

✏️ Exercices

1. Quelle API pour afficher le catalogue et gérer le panier depuis le navigateur ? Laquelle pour la gestion des produits côté serveur ?
2. Pourquoi le panier peut-il « se perdre » en headless, et que faut-il gérer ?
3. Un client veut « juste » un catalogue moderne en Next.js mais garder un checkout WooCommerce classique. Est-ce raisonnable ?

🧠 Quiz de révision

Partie suivante : Partie 11 — Niveau expert.