Checkout Guard REST API Referenz

Manchmal möchten Sie einen Kunden blockieren, ohne den WordPress-Admin zu öffnen. Vielleicht markiert ein Betrugsbewertungsdienst eine Bestellung, oder ein Helpdesk-Tool markiert jemanden als missbräuchlich. Checkout Guard bietet eine REST-API, damit Ihre eigenen Skripte und Tools Ihre blockierten Einträge lesen und verwalten und überprüfen können, ob ein Kunde blockiert würde.

Alle Routen befinden sich unter einem Namespace, cgfw/v1. Dieser Artikel listet jede Route für blockierte Einträge und Einstellungen auf, was sie akzeptiert, was sie zurückgibt und welche Fehler auftreten können. Der Namespace hat auch zwei Lizenzrouten, die der Einstellungsbildschirm des Plugins selbst verwendet. Dieser Artikel behandelt sie nicht.

Dies ist eine Entwicklerreferenz. Es wird davon ausgegangen, dass Sie mit HTTP-Anfragen mit einem Tool wie curl vertraut sind. Wenn Sie nur einen blockierten Eintrag von Hand hinzufügen oder entfernen möchten, gehen Sie zu WooCommerce → Checkout Guard in Ihrem Adminbereich. Informationen zu häufigen Blockierungsproblemen finden Sie im Checkout Guard-Fehlerbehebungsleitfaden.

Voraussetzungen

Anforderung	Details
Plugin	Checkout Guard 1.0.2 oder neuer. Die Routen /check und /entries/batch sowie die Wildcard-Übereinstimmung sind Teil von 1.0.2.
WordPress	5.6 oder neuer zur Verwendung von Anwendungspasswörtern. Checkout Guard selbst unterstützt WordPress 5.2 und höher, aber Websites unter 5.2 bis 5.5 können die unten beschriebene Authentifizierungsmethode nicht verwenden.
Benutzerrolle	Ein Benutzer mit der Berechtigung manage_woocommerce, wie z. B. ein Administrator oder Shop-Manager.
Verbindung	HTTPS. WordPress aktiviert Anwendungspasswörter nur auf HTTPS-Websites oder auf Websites, auf denen WP_ENVIRONMENT_TYPE auf local gesetzt ist.

Basis-URL und Anfrageformat

Jede Route beginnt mit der REST-Basis-URL Ihrer Website, gefolgt vom Namespace:

https://your-store.example.com/wp-json/cgfw/v1

Ersetzen Sie in jedem der folgenden Beispiele your-store.example.com durch Ihre eigene Domain.

Wenn Ihre Website einfache Permalinks verwendet, funktioniert /wp-json/ nicht. Verwenden Sie stattdessen die Form rest_route:

https://your-store.example.com/?rest_route=/cgfw/v1/entries

Senden Sie Anfragetextkörper als JSON und setzen Sie den Header Content-Type: application/json. Antworten sind ebenfalls JSON. Wenn eine URL einen 404-Fehler zurückgibt, überprüfen Sie zuerst die REST-Basis Ihrer Website.

Authentifizierung

Jede Route erfordert die Berechtigung manage_woocommerce, sodass nur Administratoren und Shop-Manager die API aufrufen können. Verwenden Sie für Skripte und andere automatisierte Aufrufer ein WordPress-Anwendungspasswort. Es meldet jede Anfrage als bestimmter Benutzer mit HTTP Basic-Authentifizierung an. Sie benötigen keinen Cookie oder Nonce.

So erstellen Sie ein Anwendungspasswort:

1. Melden Sie sich als Administrator oder Shop-Manager an und gehen Sie zu Benutzer → Profil.
2. Scrollen Sie nach unten zum Abschnitt Anwendungspasswörter.
3. Geben Sie einen Namen ein, z. B. Checkout Guard Automatisierung, in das Feld Name des neuen Anwendungspassworts.
4. Klicken Sie auf Anwendungspasswort hinzufügen.
5. Kopieren Sie das Passwort jetzt, da WordPress es nur einmal anzeigt. Es sieht aus wie xxxx xxxx xxxx xxxx xxxx xxxx. Sie können es mit oder ohne Leerzeichen senden.

Verwenden Sie den Anmeldenamen dieses Benutzers als Benutzernamen und das Anwendungspasswort als Passwort:

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Die API antwortet auf Authentifizierungsprobleme auf zwei Arten:

• Keine Anmeldeinformationen: Sie erhalten 401 Unauthorized.
• Gültige Anmeldeinformationen, aber dem Benutzer fehlt manage_woocommerce: Sie erhalten 403 Forbidden. Ein Anwendungspasswort für ein Kunden- oder Redakteurskonto wird zwar ordnungsgemäß angemeldet, aber dennoch abgelehnt.

Der Checkout Guard Admin-Bildschirm verwendet dieselben Routen. Er authentifiziert sich mit Ihrem angemeldeten Sitzungscookie plus einem X-WP-Nonce-Header. Sie benötigen diesen Ansatz nur, wenn Ihr eigener Code innerhalb des WordPress-Adminbereichs ausgeführt wird.

Routenübersicht

Pfade sind relativ zu /wp-json/cgfw/v1.

Methode	Route	Zweck
GET	/entries	Blockierte Einträge auflisten, optional gefiltert.
POST	/entries	Einen Eintrag erstellen. Wiederholungen sind sicher.
POST	/entries/batch	Viele Einträge in einer Anfrage erstellen und löschen.
PUT	/entries/{id}	Einen Eintrag aktualisieren.
DELETE	/entries/{id}	Einen Eintrag löschen.
POST	/check	Herausfinden, ob ein Kunde blockiert würde.
GET	/settings	Die Plugin-Einstellungen lesen.
POST	/settings	Die Plugin-Einstellungen aktualisieren.

Wie ein blockierter Eintrag funktioniert

Jeder blockierte Eintrag hat diese Felder:

Feld	Typ	Details
ID	string	Eine UUID, die Checkout Guard bei der Erstellung des Eintrags zuweist.
Vorname	string	Optional. Unterstützt einen *-Platzhalter, z. B. jo*.
Nachname	string	Optional. Unterstützt einen *-Platzhalter, z. B. sm*th.
E-Mail	string	Optional. Unterstützt einen *-Platzhalter, z. B. *@example.com.
IP-Adresse	string	Optional. Eine einzelne IPv4- oder IPv6-Adresse oder ein IPv4-Platzhalter wie 192.168.1.*.
notizen	string	Optional. Auf 140 Bytes begrenzt, was 140 Zeichen für einfachen lateinischen Text und weniger für andere Schriftsysteme bedeutet.
created_by_user_id	integer	Der Benutzer, der den Eintrag erstellt hat.
quelle	string	api, wenn der Eintrag mit einem Anwendungspasswort erstellt wurde, andernfalls admin.

Sie müssen mindestens eine der Angaben first_name, last_name, email oder ip_address senden. Ein Name blockiert nur, wenn der Eintrag sowohl einen Vor- als auch einen Nachnamen hat.

Ein Eintrag blockiert einen Kunden, wenn eine der folgenden Bedingungen zutrifft:

• Sein Vor- und Nachname stimmen mit dem Namen des Kunden überein.
• Seine E-Mail-Adresse stimmt mit der E-Mail-Adresse des Kunden überein.
• Seine IP-Adresse stimmt mit der IP-Adresse des Kunden beim Checkout überein.

Die Übereinstimmung von Name und E-Mail ignoriert Groß- und Kleinschreibung. Die Übereinstimmung der IP-Adresse ist exakt.

Checkout Guard liest die IP-Adresse des Kunden so, wie es WooCommerce tut, und folgt daher gängigen Proxy-Headern.

Wildcard-Regeln

Namen und E-Mail-Werte können * verwenden, um null oder mehr Zeichen abzugleichen. Die Übereinstimmung ist am gesamten Wert verankert, sodass john* mit johnny übereinstimmt, aber nicht mit ajohn. Jedes andere Zeichen, einschließlich ., wird buchstäblich abgeglichen.

IP-Adressen akzeptieren Wildcards nur in IPv4-Form. Verwenden Sie genau vier Segmente, wobei jedes Segment entweder nur aus Ziffern oder genau * besteht und mindestens ein Segment eine Ziffer ist.

Jedes Ziffernsegment muss 0 bis 255 ohne führende Nullen sein, daher werden 192.168.01.* und 256.1.1.* mit 400 abgelehnt.

Wert	Ergebnis
192.168.1.*, 192.168.*.1, 192.*.*.1	Akzeptiert
*.*.*.*	Abgelehnt mit 400. Kein Ziffernsegment.
19*.168.1.1	Abgelehnt mit 400. Gemischtes Segment.
1.2.3.*.5	Abgelehnt mit 400. Fünf Segmente.
2001:db8::*	Abgelehnt mit 400. IPv6-Wildcards werden nicht unterstützt.

Einige weitere Einschränkungen gelten für jedes Feld:

• Keine reinen Wildcards. Ein Wert, der alles abgleicht, wie z. B. *, **, *@* oder *.*, wird mit 400 abgelehnt. *@example.com ist in Ordnung, da noch literaler Text übrig bleibt.
• Maximal 5 Wildcards. Ein Wert mit 6 oder mehr *-Zeichen wird mit 400 abgelehnt.
• Batch-Erstellungen überspringen ungültige Werte. In einer Batch-Anfrage wird ein abgelehnter Eintrag nicht gespeichert. Er wird in der skipped-Gesamtzahl gezählt, und die Anfrage selbst gibt immer noch 200 zurück.
• Lookups bleiben literale. Wenn Sie GET /entries filtern oder eine wiederholte Erstellung senden, wird * als normales Zeichen behandelt. Eine Wildcard-Regel und ein literaler Wert mit denselben Zeichen sind immer separate Einträge.

Endpunkte

Eintragsliste

GET /entries gibt ein Array von Einträgen zurück. Fügen Sie email, first_name, last_name oder ip_address als Query-Parameter hinzu, um die Liste zu filtern. Namens- und E-Mail-Filter sind exakte, nicht beachtete Übereinstimmungen. Der ip_address-Filter ist eine exakte Übereinstimmung. Mehrere Filter werden mit AND kombiniert. Eine ungültige email oder ip_address gibt 400 zurück.

Jeder Eintrag in der Liste enthält auch created_by_display_name und created_by_edit_url, wenn der erstellende Benutzer noch existiert.

curl https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

# Look up one email
curl "https://your-store.example.com/wp-json/cgfw/v1/[email protected]" \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Antwort:

[
  {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api",
    "created_by_display_name": "Shop Manager",
    "created_by_edit_url": "https://your-store.example.com/wp-admin/user-edit.php?user_id=2"
  }
]

Eintrag erstellen

POST /entries erstellt einen Eintrag und gibt ihn zurück. Das Wiederholen derselben Anfrage erstellt kein Duplikat. Wenn ein Eintrag mit derselben email bereits existiert, aktualisiert Checkout Guard ihn mit allen nicht leeren Feldern, die Sie senden, und gibt ihn zurück. Wenn Sie keine E-Mail senden, wird nach demselben Vor- und Nachnamen gesucht. Wenn Sie keines von beiden senden, wird nach derselben ip_address gesucht.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","notes":"chargeback fraud"}'

Antwort:

{
  "id": "11112222-3333-4444-5555-666677778888",
  "first_name": "",
  "last_name": "",
  "email": "[email protected]",
  "ip_address": "",
  "notes": "chargeback fraud",
  "created_by_user_id": 2,
  "source": "api"
}

Um nur nach IP-Adresse zu blockieren, senden Sie {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Eine nicht leere ip_address, die ungültig ist, gibt 400 zurück.

Massenhaft erstellen und löschen

POST /entries/batch ermöglicht es Ihnen, eine ganze Liste in einer Anfrage zu synchronisieren. Senden Sie ein create-Array, ein delete-Array von Eintrags-IDs oder beides. Checkout Guard verarbeitet zuerst die Creates, jeder davon über denselben wiederholungsfreien Pfad wie ein einzelner Create. Dann verarbeitet es die Deletes. Mindestens eines der beiden Arrays muss etwas enthalten, sonst erhalten Sie 400.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/entries/batch \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "create": [
      { "email": "[email protected]", "notes": "ring leader" },
      { "first_name": "Jane", "last_name": "Doe" }
    ],
    "delete": [ "99998888-7777-6666-5555-444433332222" ]
  }'

Antwort:

{
  "created": [
    {
      "id": "aaaa1111-2222-3333-4444-555566667777",
      "first_name": "",
      "last_name": "",
      "email": "[email protected]",
      "ip_address": "",
      "notes": "ring leader",
      "created_by_user_id": 2,
      "source": "api"
    }
  ],
  "deleted": [ "99998888-7777-6666-5555-444433332222" ],
  "not_found": [],
  "skipped": 0
}

Antwortfeld	Bedeutung
erstellt	Die Einträge, die erstellt oder aktualisiert wurden.
gelöscht	Die IDs, die entfernt wurden.
nicht_gefunden	IDs löschen, die keinem Eintrag entsprachen.
übersprungen	Wie viele Erstellungselemente ignoriert wurden. Ein Element wird übersprungen, wenn es keinen Namen, keine E-Mail oder IP-Adresse hat oder wenn es eine ungültige IP-Adresse oder ein Wildcard-Zeichen hat.

Einen Eintrag aktualisieren oder löschen

PUT /entries/{id} ändert einen Eintrag. Senden Sie nur die Felder, die Sie ändern möchten. Die Antwort ist der vollständige aktualisierte Eintrag. Sie können nicht jedes identifizierende Feld löschen. Der Eintrag muss mindestens eines der Felder Name, E-Mail oder IP behalten, sonst erhalten Sie 400.

DELETE /entries/{id} entfernt einen Eintrag und gibt { "success": true } zurück. Wenn die ID keinem Eintrag entspricht, geben beide Routen 404 zurück.

curl -X PUT https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"notes":"confirmed fraud"}'

curl -X DELETE https://your-store.example.com/wp-json/cgfw/v1/entries/11112222-3333-4444-5555-666677778888 \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

Einen Kunden prüfen

POST /check teilt Ihnen mit, ob ein Kunde beim Checkout blockiert würde. Es verwendet dieselbe Abgleichlogik wie der Live-Checkout, sodass die Antwort mit dem übereinstimmt, was eine echte Bestellung erhalten würde. Senden Sie mindestens eine der Angaben email, first_name, last_name oder ip_address, sonst erhalten Sie 400.

Diese Route ist streng bei Wildcards. Die von Ihnen gesendeten Werte sind die Details eines echten Kunden, kein Muster. Ein * in einem beliebigen Feld gibt 400 zurück.

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/check \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Antwort:

{
  "blocked": true,
  "matched_entry": {
    "id": "11112222-3333-4444-5555-666677778888",
    "first_name": "",
    "last_name": "",
    "email": "[email protected]",
    "ip_address": "",
    "notes": "chargeback fraud",
    "created_by_user_id": 2,
    "source": "api"
  }
}

Wenn kein Eintrag übereinstimmt, ist blocked false und matched_entry ist null.

Einstellungen lesen und aktualisieren

GET /settings gibt die Plugin-Einstellungen zurück. Die einzige Einstellung ist checkout_denial_message, welche die Nachricht ist, die ein blockierter Kunde beim Checkout sieht. POST /settings ändert sie und gibt die gespeicherten Einstellungen zurück. Die Nachricht darf nicht leer sein, sonst erhalten Sie 400.

curl https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx"

curl -X POST https://your-store.example.com/wp-json/cgfw/v1/settings \
  --user "shopmanager:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"checkout_denial_message":"Sorry, you cannot place an order right now."}'

Antwort:

{ "checkout_denial_message": "Sorry, you cannot place an order right now." }

Fehlerantworten

Fehler verwenden das Standard-WordPress-Format mit einem code, einer message und einem HTTP-Status.

Status	Code	Wann es passiert
400	invalid_entry	Ein Create oder Update hat keinen Namen, keine E-Mail-Adresse oder keine IP-Adresse.
400	invalid_check	Eine /check-Anfrage hat keines der Felder email, first_name, last_name oder ip_address.
400	invalid_batch	Eine Batch-Anfrage hat leere create- und delete-Arrays.
400	invalid_ip_address	Eine IP-Adresse oder ein IP-Wildcard ist ungültig.
400	invalid_wildcard_value	Ein Wildcard-Wert ist ein reiner Wildcard oder hat mehr als 5 *-Zeichen.
400	invalid_settings	Die Nachrichteneinstellung ist leer.
400	rest_invalid_param	Ein Abfrage- oder /check-Parameter ist ungültig, z. B. eine ungültige E-Mail-Adresse oder ein * in einem /check-Feld.
401	rest_forbidden	Die Anfrage hat keine Anmeldeinformationen.
403	rest_forbidden	Der Benutzer hat nicht die Berechtigung manage_woocommerce.
404	entry_not_found	Kein Eintrag entspricht der ID in der URL.

Ein 404 ohne Code bedeutet, dass die REST-Basis-URL Ihrer Website von der von Ihnen verwendeten abweicht.

Datenschutz

Blockierte Einträge sind personenbezogene Daten. Wenn Sie Kunden-E-Mails, Namen oder IP-Adressen speichern, sind Sie für deren Handhabung gemäß Ihren Datenschutzverpflichtungen, wie z. B. der DSGVO, verantwortlich.

Fehlerbehebung

Häufig gestellte Fragen

Benötigen Sie Hilfe?

Checkout Guard ist ein lizenziertes Plugin. Wenn Sie immer noch nicht weiterkommen, öffnen Sie ein Support-Ticket und fügen Sie die Route, die gesendete Anfrage und die erhaltene Antwort bei. Das hilft unserem Team, Ihre Einrichtung direkt zu überprüfen.