# WooCommerce headless avec la Store API : panier et checkout découplés

> Construire un tunnel d'achat WooCommerce entièrement front-end grâce à la Store API, sans passer par les templates PHP du plugin.

- Auteur : Clément Hadrot
- Publié le : 2022-08-04
- Mis à jour le : 2022-08-04
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/woocommerce-headless-store-api-panier-checkout/

## L’essentiel

- Panier géré par jeton, sans session PHP classique
- Nonce dédié pour chaque écriture
- Checkout en une requête POST

Un client vendait du thé en vrac et voulait un front en Nuxt pour sa boutique, tout en gardant WooCommerce comme moteur de commande. Le problème est vite apparu : les endpoints REST classiques de WooCommerce (`wc/v3/products`, `wc/v3/orders`) exigent des clés API et ne savent rien faire d'un panier anonyme. Impossible de laisser un visiteur ajouter un article sans authentification serveur à serveur.

La réponse s'appelle Store API, un ensemble de routes sous `wc/store/v1` pensé dès le départ pour du JavaScript côté client, sans clé consommateur ni secret. Elle alimente les blocs Panier et Commande de WooCommerce, et elle est parfaitement utilisable depuis un front totalement séparé.

## Pourquoi ne pas rester sur les endpoints REST classiques

Les routes `wc/v3` sont conçues pour l'administration : gestion des produits, des commandes, de la boutique depuis un outil tiers authentifié. Elles ne gèrent pas de notion de panier public. La Store API, elle, expose des routes publiques comme `/wc/store/v1/cart`, `/wc/store/v1/cart/add-item` ou `/wc/store/v1/checkout`, pensées pour un visiteur non connecté.

Elle repose sur deux mécanismes qu'il faut comprendre avant d'écrire la moindre ligne de front : le jeton de panier et le nonce de la Store API.

## Récupérer et faire vivre le panier

Une première requête `GET` vers `/wc/store/v1/cart` renvoie l'état du panier (vide au départ) accompagné de deux en-têtes de réponse à conserver précieusement :

- `Cart-Token` : un jeton qui identifie le panier anonyme côté serveur, à renvoyer dans les requêtes suivantes.
- `Nonce` (transmis via `X-WC-Store-API-Nonce`) : obligatoire pour toute requête qui modifie le panier.

> L'essentiel à retenir : Panier géré par jeton, sans session PHP classique ; Nonce dédié pour chaque écriture ; Checkout en une requête POST

## Ajouter, modifier et supprimer des articles

Chaque écriture suit le même schéma : on rejoue le `Cart-Token` reçu et le nonce le plus récent, sinon WooCommerce répond une erreur d'autorisation.

```
const res = await fetch('/wp-json/wc/store/v1/cart/add-item', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cart-Token': cartToken,
    'Nonce': storeNonce,
  },
  body: JSON.stringify({ id: 1542, quantity: 2 }),
});
const cart = await res.json();
const newNonce = res.headers.get('Nonce');
```

Un piège classique : oublier de mettre à jour le nonce après chaque réponse. La Store API en émet un nouveau à chaque appel, et réutiliser l'ancien finit par déclencher des rejets intermittents difficiles à diagnostiquer.

Les routes `/cart/update-item` et `/cart/remove-item` suivent exactement la même mécanique, avec l'identifiant de ligne de panier (`key`) plutôt que l'identifiant produit.

## Passer à la caisse

Le tunnel d'achat se termine par un appel unique à `/wc/store/v1/checkout`, qui accepte les informations de facturation, de livraison et le mode de paiement choisi :

1. Récupérer les moyens de paiement disponibles via `/wc/store/v1/checkout` en `GET`.
2. Envoyer un `POST` avec adresses et `payment_method`.
3. Rediriger l'acheteur vers l'URL retournée si le moyen de paiement le demande (redirection bancaire).
4. Afficher la page de confirmation à partir de la réponse, qui contient déjà le récapitulatif de commande.

Pour les moyens de paiement hébergés (comme une redirection PayPal), la réponse contient un champ `payment_result` avec l'URL à suivre. Il faut prévoir ce cas dans le front dès la conception, sinon le paiement reste bloqué côté client.

## Gérer les erreurs de validation

La Store API renvoie des codes d'erreur explicites : rupture de stock détectée entre l'ajout au panier et le paiement, coupon expiré, adresse incomplète. Chacun arrive avec un code machine du type `woocommerce_rest_product_out_of_stock`, exploitable directement pour afficher un message ciblé plutôt qu'un message générique.

> Sur ce projet, on a fini par stocker le `Cart-Token` dans un cookie plutôt qu'en mémoire vive : ça évite de perdre le panier à chaque rafraîchissement de page, sans dépendre du tout des sessions PHP de WordPress.

## Ce qu'on retient

La Store API tient une promesse simple : un panier et un checkout WooCommerce complets, sans jamais toucher aux templates PHP ni imposer une authentification lourde à l'acheteur. Le prix à payer, c'est la discipline sur le couple jeton-nonce, qui doit vivre correctement dans le state du front, cookie ou stockage persistant selon le framework choisi. Une fois ce mécanisme posé, le reste du tunnel d'achat se code comme n'importe quel appel JSON classique.