Checkout Guard hat jetzt eine dokumentierte WooCommerce Block List API. Ihr Betrugs-Tool, Helpdesk oder Synchronisationsskript kann Blockierregeln ohne Browsersitzung hinzufügen, entfernen und nachschlagen. Ein Kunde kann in dem Moment blockiert werden, in dem etwas anderes in Ihrem Stack entscheidet, dass er blockiert werden sollte.
Die WooCommerce Block List API wird in Checkout Guard 1.0.2 zum ersten Mal dokumentiert. Diese Version fügt auch die Endpunkte /check und Batch unter dem Namespace cgfw/v1 hinzu. Es handelt sich um dieselbe Reihe von Routen, die auch die Admin-Oberfläche des Plugins verwendet, was wichtiger ist, als es klingt. Es gibt keine zweite Implementierung, die aus dem Tritt geraten könnte, was tatsächlich beim Checkout passiert.
Inhaltsverzeichnis
- Wofür die WooCommerce Block List API da ist
- Authentifizierung mit einem Anwendungspasswort
- Die Endpunkte
- Was eine Regel enthalten kann
- Regeln erstellen, ohne Duplikate zu erzeugen
- Eine ganze Liste in einer Anfrage synchronisieren
- Fragen, ob ein Kunde blockiert würde
- Regeln finden und wissen, woher sie stammen
- Was die API ablehnen wird
- Schlussfolgerung
- Häufig gestellte Fragen
Wofür die WooCommerce Block List API da ist
Die meisten Blockierlisten beginnen von Hand. Jemand gibt eine Bestellung auf, die Sie nicht wollten, Sie öffnen die Verwaltung und fügen ihn hinzu.
Das funktioniert, solange das Volumen gering ist und die Entscheidungen bei Ihnen liegen. Es funktioniert nicht mehr, wenn das Signal woanders lebt. Ein Betrugs-Scoring-Dienst markiert eine Bestellung. Ihr Helpdesk-Mitarbeiter schließt ein Ticket über einen missbräuchlichen Kunden. Eine Rückbuchung landet bei Ihrem Zahlungsanbieter. In jedem Fall weiß bereits etwas, dass die Person blockiert werden sollte, und das einzige fehlende Teil ist eine Möglichkeit, dies ohne menschliches Eingreifen in WordPress mitzuteilen.
Das ist die Lücke, die dies schließt. Die WooCommerce-Blocklisten-API ist für maschinelle Aufrufer konzipiert: kein Cookie, kein Nonce, kein Admin-Bildschirm.
Authentifizierung mit einem Anwendungspasswort
Automatisierte Aufrufer authentifizieren sich mit einem WordPress Application Password über HTTP Basic Auth. Es gibt keinen separaten Checkout Guard-Schlüssel, der erstellt werden muss.
Gemäß der WordPress-Dokumentation zu Anwendungs-Passwörtern erstellen Sie eines unter Benutzer → Profil → Anwendungs-Passwörter und geben ihm einen Namen wie Checkout Guard automation. Kopieren Sie den generierten Wert. Er wird einmal angezeigt, in der Form xxxx xxxx xxxx xxxx xxxx xxxx, und die Leerzeichen sind Teil davon. Verwenden Sie den Anmeldenamen des Kontos als Basic Auth-Benutzernamen und dieses Passwort als Basic Auth-Passwort.
Eine Anforderung kann leicht übersehen werden. Jede Route der WooCommerce-Blocklisten-API prüft die Berechtigung manage_woocommerce, sodass das Konto hinter dem Anwendungs-Passwort ein Administrator oder ein Shop-Manager sein muss. Ein Passwort eines anderen Benutzers authentifiziert sich einwandfrei und wird dann mit einem 403 abgelehnt. Fehlende Anmeldeinformationen ergeben stattdessen ein 401, was eine nützliche Möglichkeit ist, die beiden Fehler zu unterscheiden.
Anwendungs-Passwörter erfordern WordPress 5.6 oder neuer und eine über HTTPS bereitgestellte Website. Checkout Guard selbst unterstützt WordPress 5.2. Auf einer 5.2- bis 5.5-Website existiert dieser Authentifizierungspfad also nicht.
Die Endpunkte
Acht Routen bilden die WooCommerce-Blocklisten-API, die die Blockliste und ihre Einstellungen abdecken.
| Methode | Route | Zweck |
|---|---|---|
| GET | /entries | Einträge auflisten, optional gefiltert |
| POST | /entries | Eintrag erstellen, idempotent |
| POST | /entries/batch | Massenhaft erstellen und löschen |
| PUT | /entries/{id} | Eintrag nach ID aktualisieren |
| DELETE | /entries/{id} | Eintrag nach ID löschen |
| POST | /check | Würde dieser Kunde blockiert werden? |
| GET | /settings | Einstellungen lesen |
| POST | /settings | Einstellungen aktualisieren |
Die Basis-URL lautet https://your-store.example.com/wp-json/cgfw/v1. Wenn diese URLs einen 404 zurückgeben, überprüfen Sie das REST-Präfix Ihrer Website, da /wp-json/ der Standard ist und keine Garantie darstellt. Eine Website mit einfachen Permalinks verwendet stattdessen die Form ?rest_route=.
Das Auflisten des Namespace zeigt zwei weitere Routen, /license und /license/activate. Diese gehören zum Lizenzaktivierungsbildschirm des Plugins selbst und nicht zur hier beschriebenen API.
Was eine Regel enthalten kann
Ein blockierter Eintrag enthält eine ID, einen optionalen Vor- und Nachnamen, eine optionale E-Mail-Adresse, eine optionale IP-Adresse und optionale Notizen von bis zu 140 Zeichen. Er zeichnet auch die ID des Benutzers auf, der ihn erstellt hat, und ein Herkunftsfeld. Mindestens eines der Felder Name, E-Mail oder IP muss ausgefüllt sein.
Ein Eintrag blockiert einen Kunden, wenn eines seiner ausgefüllten Felder übereinstimmt. Beide Namen stimmen überein, oder die E-Mail stimmt überein, oder die IP-Adresse stimmt überein. Namen und E-Mails werden nicht zwischen Groß- und Kleinschreibung unterscheidend verglichen. Die IP-Adresse des Kunden beim Checkout wird über den Geolocation-Helfer von WooCommerce aufgelöst, sodass ein Proxy oder ein CDN vor Ihrem Shop den Vergleich nicht unterbricht.
Namen-, E-Mail- und IP-Werte akzeptieren jeweils ein *-Platzhalterzeichen, sodass eine Regel eine ganze E-Mail- Domäne oder einen IPv4-Bereich abdecken kann. IP-Platzhalter sind enger gefasst als die anderen: nur im IPv4-Segmentformat, sodass 192.168.1.* funktioniert und 2001:db8::* nicht.
Das Feld notes verdient eine eigene Anmerkung. Es ist ein API-Feld. Es erscheint als Spalte in der Tabelle der blockierten Einträge und ist der Ort, an dem diese Spalte ihren Inhalt erhält, aber es gibt kein Notizfeld im Dialog zum Hinzufügen von Einträgen. Wenn Ihre Regeln sich später selbst erklären sollen, ist die API der richtige Weg, dies festzulegen.
Regeln erstellen, ohne Duplikate zu erzeugen
POST /entries ist idempotent, was die Eigenschaft ist, die es sicher macht, von etwas aufgerufen zu werden, das Sie nicht vollständig kontrollieren.
Wenn ein Eintrag mit derselben E-Mail bereits existiert, wird er mit allen nicht leeren Feldern, die Sie senden, aktualisiert und an Sie zurückgegeben. Ohne E-Mail identifiziert derselbe Vor- und Nachname den Eintrag. Ohne beides tut dies dieselbe IP-Adresse. Wenn Sie ihn zweimal mit derselben E-Mail aufrufen, erhalten Sie genau einen Eintrag, nicht zwei.
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"}'Das Blockieren rein auf Basis einer Verbindung funktioniert auf die gleiche Weise.
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 '{"ip_address":"203.0.113.42","notes":"repeat spammer"}'Was wir gesehen haben: Die Integrationen, die Probleme verursachen, sind diejenigen, die davon ausgehen, dass eine Erstellung eine Erstellung ist. Ein erneuter Versuch nach einem Netzwerk-Timeout, ein doppelt zugestellter Webhook, ein nächtlicher Job, der die Zeilen von gestern erneut sendet, und plötzlich hat eine Blockierliste vier Kopien derselben Person und niemand kann sagen, welche die aktuelle ist. Idempotenz bei E-Mail, Name und IP ist das, was das verhindert. Senden Sie also das identifizierende Feld jedes Mal, anstatt nur beim ersten Aufruf.
Eine ganze Liste in einer Anfrage synchronisieren
POST /entries/batch nimmt ein create-Array und ein delete-Array entgegen, was die Form ist, die Sie wünschen, wenn ein anderes System die Liste besitzt und WordPress der Nachfolger ist.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Erstellungen werden zuerst ausgeführt, jede über denselben idempotenten Pfad wie eine einzelne Erstellung, dann Löschungen nach ID. Mindestens eines der beiden Arrays muss nicht leer sein. Die Antwort sagt Ihnen, was passiert ist, anstatt dass Sie die Liste selbst vergleichen müssen:
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found sammelt Lösch-IDs, die nichts übereinstimmten. skipped zählt Erstellungs-Payloads, die ignoriert wurden, weil sie keinen Namen, keine E-Mail oder keine IP enthielten oder weil ihre IP nicht leer und ungültig war. Ein Batch mit fehlerhaften Zeilen gibt immer noch 200 zurück, lesen Sie also skipped, anstatt sich allein auf den Statuscode zu verlassen.
Fragen, ob ein Kunde blockiert würde
POST /check beantwortet die Frage direkt und führt denselben Abgleichscode wie der Live-Checkout-Schutz aus. Die Antwort kann nicht von dem abweichen, was ein echter Käufer erlebt, was der Sinn seiner Existenz ist, anstatt dass Sie die Logik neu implementieren.
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]"}'Die Antwort lautet { "blocked": true, "matched_entry": { … } }, wobei matched_entry auf null gesetzt ist, wenn nichts übereinstimmte. Zu wissen, welche Regel jemanden erwischt hat, ist normalerweise nützlicher, als zu wissen, dass etwas übereingestimmt hat.
Dieser Endpunkt ist bewusst strenger als die anderen. Ein Kandidat ist ein echter Kundenwert, niemals ein Muster, daher wird ein * in einem beliebigen Feld mit einem 400 abgelehnt. Regel-Lookups gehen den anderen Weg: GET /entries?email=*@example.com findet diese exakte gespeicherte Regel, da Lookups buchstäblich vergleichen und niemals einen Platzhalter erweitern.
Regeln finden und wissen, woher sie stammen
GET /entries ohne Parameter gibt alles zurück. Fügen Sie email, first_name, last_name oder ip_address hinzu, um zu filtern, kombiniert mit AND, wenn Sie mehr als einen senden, und verglichen ohne Berücksichtigung der Groß- und Kleinschreibung.
Jeder Eintrag enthält auch ein source-Feld, das aufzeichnet, woher er stammt: api, wenn er über ein Anwendungspasswort erstellt wurde, und andernfalls admin. Wenn eine Sperrliste sowohl von Menschen als auch von Maschinen gepflegt wird, können Sie mit dieser Unterscheidung die eine überprüfen, ohne die andere zu stören.
Die Endpunkte für Einstellungen runden das Ganze ab, obwohl es nur eine Einstellung zum Lesen oder Schreiben gibt. checkout_denial_message ist die Nachricht, die ein blockierter Käufer sieht, und sie darf nicht leer sein.
Was die API ablehnen wird
Vier Ablehnungen sind es wert, zu kennen, bevor Sie etwas anschließen, da jede davon beabsichtigt ist.
- Eine falsch formatierte IP-Adresse wird bei Erstellung und Aktualisierung mit einem
400abgelehnt und bei einem Batch übersprungen und gezählt. - Leere Platzhalter werden überall abgelehnt. Das Entfernen der Sternchen, Leerzeichen und Trennzeichen von
*,*@*oder*.*hinterlässt nichts, und eine Regel, die jeden Kunden abgleicht, ist eher ein Ausfall als eine Sperre. - Mehr als fünf Platzhalter in einem einzelnen Wert schlagen aus demselben Grund fehl.
- Ein Eintrag ohne Namen, ohne E-Mail und ohne IP wird abgelehnt, da nichts zum Abgleichen vorhanden wäre.
Schlussfolgerung
Die WooCommerce-Blocklisten-API verwandelt Ihre Regeln von etwas, das Sie pflegen, in etwas, das Ihr Stack für Sie pflegt. Gleiche Regeln, gleicher Abgleich, gleiches Verhalten an der Kasse, erreichbar von allem, was bereits weiß, dass ein Kunde ein Problem darstellt.
Wenn Sie neu im Plugin sind, behandelt unsere Einführung in Checkout Guard, was die Blockliste tut. Für das Gesamtbild decken unser Leitfaden zu WooCommerce-Datenautomatisierungs-Workflows und unsere Anleitung zum Exportieren von WooCommerce-Daten nach Zapier die anderen Bereiche ab, in denen Automatisierung von Vorteil ist.
Eine letzte Sache, die offen gesagt werden sollte. Blockierte Einträge sind personenbezogene Daten, und eine IP-Adresse ist eine Online-Kennung gemäß der DSGVO, die Erwägungsgrund 30 direkt nennt. Eine API erleichtert das schnelle Sammeln einer großen Anzahl davon, also entscheiden Sie, wie lange Sie sie aufbewahren, bevor Sie den Hahn aufdrehen.
Die WooCommerce-Blocklisten-API ist in Checkout Guard 1.0.2 verfügbar.
Häufig gestellte Fragen
Wie authentifiziere ich mich bei der WooCommerce Block List API?
Verwenden Sie ein WordPress Application Password anstelle von HTTP Basic Auth. Erstellen Sie eines unter Benutzer → Profil → Anwendungspasswörter und senden Sie dann den Anmeldenamen des Kontos als Benutzernamen und das generierte Passwort als Passwort. Kein Cookie oder Nonce erforderlich.
Warum erhalte ich eine 403-Fehlermeldung, obwohl meine Anmeldedaten korrekt sind?
Jede Route erfordert die manage_woocommerce-Berechtigung. Ein Anwendungspasswort, das einem Benutzer ohne diese Berechtigung gehört, wird erfolgreich authentifiziert und dann abgelehnt. Verwenden Sie ein Administratoren- oder Shop-Manager-Konto. Eine 401 bedeutet, dass überhaupt keine Anmeldeinformationen angekommen sind.
Führt das zweimalige Aufrufen des Erstellungsendpunkts zu einem Duplikat?
Nein. POST /entries ist idempotent. Ein Eintrag mit derselben E-Mail-Adresse wird aktualisiert und zurückgegeben, anstatt dupliziert zu werden. Dasselbe gilt für einen übereinstimmenden Vor- und Nachnamen, wenn keine E-Mail-Adresse angegeben ist, oder eine übereinstimmende IP-Adresse, wenn beides nicht angegeben ist.
Kann ich meine gesamte Blockierliste aus einem anderen System synchronisieren?
Ja. POST /entries/batch akzeptiert ein create-Array und ein delete-Array in einer einzigen Anfrage und gibt eine Zusammenfassung dessen zurück, was erstellt, gelöscht, nicht gefunden und übersprungen wurde. Erstellungen erfolgen vor Löschungen.
Verwendet die WooCommerce Block List API dieselbe Blockierlogik wie die Kasse?
Ja. POST /check verwendet denselben übereinstimmenden Code wie der Live Checkout Guard, sodass seine Antwort nicht von dem abweichen kann, was ein echter Kunde erlebt. Es wird zurückgegeben, ob der Kunde blockiert ist und welcher Eintrag übereinstimmte.
Kann ich Wildcards über die API verwenden?
Ja, in Regelwerten. Die Felder Name, E-Mail und IP akzeptieren ein *-Wildcard beim Erstellen und Aktualisieren. Der Endpunkt /check ist die Ausnahme und lehnt Wildcards ab, da ein Prüfkandidat ein echter Kundenwert und kein Muster ist.
