Projekt starten

Die REST API von Reward Points nutzen

WooCommerce Reward Points Dokumentation

Vergeben Sie Prämienpunkte an Nutzer über einen gesicherten REST-Endpunkt des Plugins.

Was macht diese API?

Sie stellt einen REST-Endpunkt bereit, der einem WooCommerce-Nutzer Prämienpunkte gutschreibt und den neuen Punktestand zurückgibt.
Intern nutzt er die Plugin-Logik manually_add_user_points(), sodass Summen, Protokolle und Hooks wie bei einer manuellen Gutschrift im Admin funktionieren.

Wie lautet der Endpunkt?

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

Welche Berechtigungen sind nötig?

Nur angemeldete Nutzer mit der Berechtigung manage_woocommerce dürfen den Endpunkt aufrufen (meist Administratoren oder Shop-Manager). Nicht berechtigte Anfragen werden abgelehnt.

Welche Parameter sind erforderlich?

Alle Parameter sind Pflicht und werden auf dem Server geprüft:

Feld Typ Regeln Zweck
user_id integer Muss in WordPress existieren Welchem Nutzer gutgeschrieben wird
points integer Muss eine positive ganze Zahl sein (> 0) Wie viele Punkte gutgeschrieben werden
message string Wird serverseitig bereinigt (sanitize_text_field) Erscheint im Punkteprotokoll bzw. in der Notiz

Beispiel-JSON

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

Wie sieht eine erfolgreiche Antwort aus?

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

Hinweis: new_total wird nach der Gutschrift aus den Nutzer-Metadaten gelesen.

Welche Fehler können auftreten?

HTTP Code Wann er auftritt
400 invalid_user user_id fehlt, ist ungültig oder der Nutzer existiert nicht
400 invalid_points points ist <= 0 oder fehlt
401 n/a Nicht angemeldet
403 n/a Angemeldet, aber ohne Berechtigung manage_woocommerce
404 n/a Route nicht registriert (Plugin deaktiviert oder API nicht aktiviert)

Wie authentifiziere ich mich?

  1. Anwendungspasswörter (empfohlen für Server-zu-Server): WordPress 5.6+ → Benutzerprofil → Anwendungspasswörter → Neues erstellen. Nutzen Sie HTTP Basic Auth (user:application-password).
  2. Login-Cookies + Nonce (für Aufrufe aus dem wp-admin heraus).
  3. JWT/OAuth (über separate Auth-Plugins), falls Ihr System sie nutzt.

cURL-Beispiel (Anwendungspasswörter)

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

Schnelleinrichtung in Postman/Insomnia

  1. Methode/URL: POST https://your-site/wp-json/wc-reward-points/v1/add-points
  2. Auth: Basic → Benutzername: Ihr WP-Nutzer, Passwort: Anwendungspasswort
  3. Header: Content-Type: application/json
  4. Body (raw JSON): siehe Beispiel oben

PHP-Beispiel (serverseitig mit Anwendungspasswörtern)

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

Funktioniert das mit Multisite?

Ja. Wenn beides zutrifft – WordPress ist eine Multisite und die Plugin-Einstellung multisiteSplitPoints ist aktiv –, werden die Punkte unter einem websitespezifischen Meta-Schlüssel gespeichert:

woocommerce_reward_points_<BLOG_ID>

Andernfalls lautet der Meta-Schlüssel:

woocommerce_reward_points

Das ist wichtig, wenn Sie Punktestände an anderer Stelle direkt aus den Nutzer-Metadaten lesen.

Warum fehlt die Route (404)?

  • Das Plugin (oder seine API-Funktion) ist deaktiviert.
  • Die Plugin-Option enable ist false (Routen werden nur bei aktivem Plugin registriert).
  • Ihre Caching-Ebene blockiert /wp-json oder POST-Anfragen.
  • Ein Sicherheits- oder Firewall-Plugin stört REST-Aufrufe.

Was passiert intern beim API-Aufruf?

  1. Eingaben werden bereinigt und geprüft.
  2. Der Code setzt $_POST['userId'], $_POST['points'], $_POST['text'] und $_POST['action']='woocommerce_reward_points_add_points'.
  3. Er initialisiert WooCommerce_Reward_Points_Earning und ruft manually_add_user_points() auf.
  4. Er liest den neuen Punktestand aus den Nutzer-Metadaten und gibt ihn in der Antwort zurück.

Kann ich damit Punkte abziehen?

Nein – dieser Endpunkt schreibt nur Punkte gut (erfordert points > 0). Zum Abziehen erstellen Sie einen eigenen Endpunkt oder erweitern diesen um einen sicheren Abzugs-Ablauf.

Gibt es Ratenbegrenzung oder Idempotenz?

Nicht eingebaut. Wenn Sie externe Systeme anbinden, sorgen Sie auf Client-Seite für Idempotenz (z. B. mit einer eindeutigen Vorgangs-ID), um doppelte Gutschriften zu vermeiden.

Wie teste ich schnell?

  1. Aktivieren Sie die API-Einstellung des Plugins (enable = true).
  2. Prüfen Sie, ob Ihr Nutzer die Berechtigung manage_woocommerce hat.
  3. Führen Sie das cURL-Beispiel aus.
  4. Verify the user’s points in the admin or via: 
    get_user_meta(123, 'woocommerce_reward_points', true);

    (oder bei Multisite den websitespezifischen Schlüssel)

Checkliste zur Fehlersuche

  • 401/403: Nicht angemeldet oder fehlende Berechtigung. Nutzen Sie Anwendungspasswörter oder eine Admin-Sitzung.
  • 404: Prüfen Sie, ob die Funktion aktiv ist und keine Firewall /wp-json blockiert.
  • 400 invalid_user: user_id muss ein bestehender WP-Nutzer sein.
  • 400 invalid_points: Nutzen Sie eine positive ganze Zahl.
  • Punktestand ändert sich nicht: Prüfen Sie eigene Hooks oder Object-Caching, die Änderungen zurücksetzen oder puffern könnten.

Sicherheitsempfehlungen

  • Nutzen Sie für Server-zu-Server-Aufrufe bevorzugt Anwendungspasswörter und nach Möglichkeit ein Admin-Konto mit wenigen Rechten.
  • Nur über HTTPS ausliefern.
  • Protokollieren Sie jede Gutschrift mit einer klaren, gut lesbaren message.
  • Erwägen Sie Ratenbegrenzung oder WAF-Regeln, wenn der Endpunkt über interne Systeme hinaus erreichbar ist.