Démarrer un projet

Utiliser l’API REST de Reward Points

WooCommerce Reward Points Documentation

Créditez des points de fidélité aux utilisateurs via un endpoint REST sécurisé fourni par le plugin.

Que fait cette API ?

Elle fournit un endpoint REST qui ajoute des points de fidélité à un utilisateur WooCommerce et renvoie son nouveau total.
En interne, elle réutilise la logique manually_add_user_points() du plugin : totaux, journaux et hooks se comportent comme lors d’un ajout manuel dans l’administration.

Quel est l’endpoint ?

  • Méthode : POST
  • Route : /wp-json/wc-reward-points/v1/add-points

Quelles autorisations faut-il ?

Seuls les utilisateurs authentifiés disposant de manage_woocommerce peuvent appeler cet endpoint (en général les administrateurs ou les gestionnaires de boutique). Les requêtes non autorisées sont rejetées.

Quels paramètres sont requis ?

Tous les paramètres sont obligatoires et validés côté serveur :

Champ Type Règles Rôle
user_id integer Doit exister dans WordPress Utilisateur à créditer
points integer Doit être un entier positif (> 0) Nombre de points à ajouter
message string Nettoyé côté serveur (sanitize_text_field) Affiché dans le journal / la note des points

Exemple de corps JSON

{
  "user_id": 123,
  "points": 250,
  "message": "Customer service gesture for delayed shipment"
}

À quoi ressemble une réponse réussie ?

{
  "success": true,
  "user_id": 123,
  "points_added": 250,
  "new_total": 1420,
  "message": "Customer service gesture for delayed shipment"
}

Remarque : new_total est lu dans les métadonnées de l’utilisateur après l’ajout.

Quelles erreurs peuvent survenir ?

HTTP Code Quand
400 invalid_user user_id manque, est invalide ou l’utilisateur n’existe pas
400 invalid_points points vaut <= 0 ou manque
401 n/a Non authentifié
403 n/a Authentifié mais sans la capacité manage_woocommerce
404 n/a Route non enregistrée (plugin désactivé ou API non activée)

Comment s’authentifier ?

  1. Mots de passe d’application (recommandé de serveur à serveur) : WordPress 5.6+ → Profil → Mots de passe d’application → Créer. Utilisez l’authentification HTTP Basic (user:application-password).
  2. Cookies de connexion + nonce (pour les appels depuis wp-admin).
  3. JWT/OAuth (via des plugins d’authentification séparés) si votre système les utilise.

Exemple cURL (mots de passe d’application)

curl -X POST "https://example.com/wp-json/wc-reward-points/v1/add-points" \
  -u "admin:YOUR-APP-PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"user_id":123,"points":250,"message":"Promo: Spring bonus"}'

Configuration rapide dans Postman/Insomnia

  1. Méthode/URL : POST https://your-site/wp-json/wc-reward-points/v1/add-points
  2. Auth : Basic → nom d’utilisateur : votre utilisateur WP, mot de passe : mot de passe d’application
  3. En-têtes : Content-Type: application/json
  4. Corps (JSON brut) : voir l’exemple ci-dessus

Exemple PHP (côté serveur avec mots de passe d’application)

<?php
$url = site_url('/wp-json/wc-reward-points/v1/add-points');
$resp = wp_remote_post($url, array(
  'headers' => array(
    'Authorization' => 'Basic ' . base64_encode('admin:YOUR-APP-PASSWORD'),
    'Content-Type'  => 'application/json',
  ),
  'body' => wp_json_encode(array(
    'user_id' => 123,
    'points'  => 100,
    'message' => 'Welcome bonus',
  )),
  'timeout' => 20,
));
if (is_wp_error($resp)) {
  error_log($resp->get_error_message());
} else {
  $code = wp_remote_retrieve_response_code($resp);
  $body = json_decode(wp_remote_retrieve_body($resp), true);
  // Handle $code / $body
}
fetch('/wp-json/wc-reward-points/v1/add-points', {
  method: 'POST',
  credentials: 'include', // send auth cookies
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ user_id: 123, points: 50, message: 'Manual adjustment' })
}).then(r => r.json()).then(console.log);
The endpoint relies on capability checks (current_user_can('manage_woocommerce')), so cookies + a logged-in admin session are sufficient for auth in this context.

Cela fonctionne-t-il en multisite ?

Oui. Si les deux conditions sont remplies – WordPress est en multisite et le réglage multisiteSplitPoints du plugin est activé –, les points sont stockés sous une clé méta propre au site :

woocommerce_reward_points_<BLOG_ID>

Sinon, la clé méta est :

woocommerce_reward_points

C’est important si vous lisez les totaux directement dans les métadonnées utilisateur ailleurs.

Pourquoi la route est-elle introuvable (404) ?

  • Le plugin (ou sa fonction API) est désactivé.
  • L’option enable du plugin vaut false (les routes ne sont enregistrées que si le plugin est activé).
  • Votre couche de cache bloque /wp-json ou les requêtes POST.
  • Un plugin de sécurité / pare-feu perturbe les appels REST.

Que se passe-t-il en interne lors d’un appel ?

  1. Les entrées sont nettoyées et validées.
  2. Le code définit $_POST['userId'], $_POST['points'], $_POST['text'] et $_POST['action']='woocommerce_reward_points_add_points'.
  3. Il initialise WooCommerce_Reward_Points_Earning et appelle manually_add_user_points().
  4. Il lit le nouveau total dans les métadonnées de l’utilisateur et le renvoie dans la réponse.

Puis-je l’utiliser pour retirer des points ?

Non, cet endpoint ajoute uniquement des points (il exige points > 0). Pour en retirer, créez un endpoint séparé ou étendez celui-ci avec un processus de retrait sécurisé.

Y a-t-il une limitation de débit ou une idempotence ?

Pas en standard. Si vous connectez des systèmes externes, assurez l’idempotence côté client (p. ex. avec un identifiant d’opération unique) pour éviter les doubles crédits.

Comment tester rapidement ?

  1. Activez le réglage API du plugin (enable = true).
  2. Vérifiez que votre utilisateur dispose de manage_woocommerce.
  3. Exécutez l’exemple cURL.
  4. Verify the user’s points in the admin or via: 
    get_user_meta(123, 'woocommerce_reward_points', true);

    (ou la clé propre au site en multisite)

Liste de contrôle en cas de problème

  • 401/403 : non authentifié ou capacité manquante. Utilisez un mot de passe d’application ou une session administrateur.
  • 404 : vérifiez que la fonction est activée et qu’aucun pare-feu ne bloque /wp-json.
  • 400 invalid_user : user_id doit être un utilisateur WP existant.
  • 400 invalid_points : utilisez un entier positif.
  • Le total ne change pas : vérifiez les hooks personnalisés ou les caches d’objets qui pourraient annuler ou retenir les modifications.

Bonnes pratiques de sécurité

  • Privilégiez les mots de passe d’application pour les appels de serveur à serveur, si possible avec un compte administrateur aux droits limités.
  • N’utilisez que HTTPS.
  • Consignez chaque crédit avec un message clair et lisible.
  • Envisagez une limitation de débit ou des règles WAF si l’endpoint est accessible au-delà de vos systèmes internes.