Usare la REST API di Reward Points

Aggiungi punti premio agli utenti tramite un endpoint REST sicuro fornito dal plugin.

Cosa fa questa API?

Fornisce un endpoint REST che aggiunge punti premio a un utente WooCommerce e restituisce il nuovo totale dell’utente.
Internamente riusa la logica manually_add_user_points() del plugin, quindi totali, log e hook funzionano come un’aggiunta manuale dall’amministrazione.

Qual è l’endpoint?

• Metodo: POST
• Route: /wp-json/wc-reward-points/v1/add-points

Quali permessi servono?

Solo gli utenti autenticati con la capacità manage_woocommerce possono chiamare questo endpoint (di solito amministratori o shop manager). Le richieste non autorizzate vengono rifiutate.

Quali parametri servono nella richiesta?

Tutti i parametri sono obbligatori e vengono validati sul server:

Campo	Tipo	Regole	Scopo
user_id	intero	Deve esistere in WordPress	Utente a cui accreditare i punti
points	intero	Deve essere un intero positivo (> 0)	Quanti punti aggiungere
message	stringa	Sanificato lato server (sanitize_text_field)	Mostrato nel log / nella nota dei punti

Esempio di body JSON

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

Com’è una risposta riuscita?

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

Nota: new_total viene letto dai meta dell’utente dopo l’aggiunta.

Quali errori posso vedere?

HTTP	Codice	Quando succede
400	invalid_user	user_id manca / non è valido o l’utente non esiste
400	invalid_points	points è <= 0 o manca
401	n/d	Non autenticato
403	n/d	Autenticato ma senza la capacità manage_woocommerce
404	n/d	Route non registrata (plugin disattivato o API non attiva)

Come mi autentico?

1. Password per le applicazioni (consigliate da server a server): WordPress 5.6+ → Profilo utente → Password per le applicazioni → Crea nuova. Usa HTTP Basic Auth (user:application-password).
2. Cookie di login + nonce (per chiamate dalla dashboard di wp-admin).
3. JWT/OAuth (tramite plugin di autenticazione separati), se li usi.

Esempio cURL (password per le applicazioni)

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"}'

Configurazione rapida con Postman/Insomnia

1. Metodo/URL: POST https://your-site/wp-json/wc-reward-points/v1/add-points
2. Auth: Basic → username: il tuo utente WP, password: la password per le applicazioni
3. Header: Content-Type: application/json
4. Body (JSON grezzo): vedi l’esempio sopra

Esempio PHP (lato server con password per le applicazioni)

<?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
}

Esempio con nonce WP + cookie di login (AJAX da wp-admin)

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);

L’endpoint si basa sul controllo delle capacità (current_user_can('manage_woocommerce')), quindi in questo contesto bastano i cookie e una sessione di amministratore attiva per l’autenticazione.

Funziona in un multisite?

Sì. Se valgono entrambe le condizioni (WordPress è multisite e l’impostazione del plugin multisiteSplitPoints è attiva), i punti vengono salvati in una meta key specifica per sito:

woocommerce_reward_points_<BLOG_ID>

Altrimenti la meta key è:

woocommerce_reward_points

È importante se leggi i totali direttamente dai meta dell’utente altrove.

Perché la route potrebbe mancare (404)?

• Il plugin (o la sua funzione API) è disattivato.
• L’opzione del plugin enable è false (le route vengono registrate solo se attivo).
• Il livello di cache blocca /wp-json o le richieste POST.
• Un plugin di sicurezza / firewall interferisce con le chiamate REST.

Cosa succede internamente quando chiamo l’API?

1. Gli input vengono sanificati e validati.
2. Il codice imposta $_POST['userId'], $_POST['points'], $_POST['text'] e $_POST['action']='woocommerce_reward_points_add_points'.
3. Inizializza WooCommerce_Reward_Points_Earning e chiama manually_add_user_points().
4. Legge il totale aggiornato dai meta dell’utente e lo restituisce nella risposta.

Posso usarla per togliere punti?

No: questo endpoint aggiunge soltanto punti (richiede points > 0). Per toglierli crea un endpoint separato o estendi questo con un flusso di sottrazione sicuro.

C’è un limite di frequenza o l’idempotenza?

Non sono integrati. Se ti colleghi a sistemi esterni, implementa l’idempotenza lato client (ad es. un ID univoco per operazione) per evitare assegnazioni doppie.

Come posso fare un test veloce?

1. Attiva l’impostazione API del plugin (enable = true).
2. Verifica che il tuo utente abbia la capacità manage_woocommerce.
3. Esegui l’esempio cURL.
4. Verifica i punti dell’utente nell’amministrazione oppure con:

   get_user_meta(123, 'woocommerce_reward_points', true);

   (o la chiave per multisite, se serve)

Checklist per la risoluzione dei problemi

• 401/403: non autenticato o senza la capacità richiesta. Usa le password per le applicazioni o una sessione di amministratore.
• 404: verifica che la funzione sia attiva e che nessun firewall blocchi /wp-json.
• 400 invalid_user: user_id deve essere un utente WP esistente.
• 400 invalid_points: usa un intero positivo.
• I totali non cambiano: controlla hook personalizzati o livelli di object cache che potrebbero annullare / trattenere le modifiche.

Buone pratiche di sicurezza

• Per le chiamate da server a server preferisci le password per le applicazioni; se possibile, limita l’accesso a un account amministrativo con pochi privilegi.
• Usa solo HTTPS.
• Registra ogni assegnazione con un message chiaro e leggibile.
• Valuta limiti di frequenza o regole WAF se esponi l’endpoint oltre i sistemi interni.