Checkout Guard REST API-referentie

Soms wilt u een klant blokkeren zonder de WordPress-admin te openen. Misschien markeert een fraudescoringsservice een bestelling, of markeert een helpdesktool iemand als misbruik. Checkout Guard wordt geleverd met een REST API, zodat uw eigen scripts en tools uw geblokkeerde vermeldingen kunnen lezen en beheren, en kunnen controleren of een klant zou worden geblokkeerd.

Alle routes bevinden zich onder één naamruimte, cgfw/v1. Dit artikel somt elke route op voor geblokkeerde vermeldingen en instellingen, wat deze accepteert, wat deze retourneert en de fouten die u kunt tegenkomen. De naamruimte heeft ook twee licentieroutes die het instellingenscherm van de plugin zelf gebruikt. Dit artikel behandelt deze niet.

Dit is een ontwikkelaarsreferentie. Het gaat ervan uit dat u comfortabel bent met het maken van HTTP-verzoeken met een tool zoals curl. Als u alleen handmatig een geblokkeerde vermelding wilt toevoegen of verwijderen, ga dan naar WooCommerce → Checkout Guard in uw admin. Raadpleeg voor veelvoorkomende blokkeringsproblemen de Checkout Guard-handleiding voor probleemoplossing.

Vereisten

Vereiste	Details
Plugin	Checkout Guard 1.0.2 of hoger. De routes /check en /entries/batch, en wildcard-matching, maken deel uit van 1.0.2.
WordPress	5.6 of hoger om Application Passwords te gebruiken. Checkout Guard zelf ondersteunt WordPress 5.2 en hoger, maar sites op 5.2 tot 5.5 kunnen de onderstaande authenticatiemethode niet gebruiken.
Gebruikersrol	Een gebruiker met de manage_woocommerce-mogelijkheid, zoals een beheerder of winkelmanager.
Verbinding	HTTPS. WordPress schakelt Application Passwords alleen in op HTTPS-sites, of op sites waar WP_ENVIRONMENT_TYPE is ingesteld op local.

Basis-URL en aanvraagformaat

Elke route begint met de REST-basis-URL van uw site, gevolgd door de naamruimte:

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

Vervang in elk voorbeeld hieronder your-store.example.com door uw eigen domein.

Als uw site platte permalinks gebruikt, werkt /wp-json/ niet. Gebruik in plaats daarvan de rest_route-vorm:

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

Verzend aanvraagbody's als JSON en stel de header Content-Type: application/json in. Antwoorden zijn ook JSON. Als een URL een 404 retourneert, controleer dan eerst de REST-basis van uw site.

Authenticatie

Elke route vereist de manage_woocommerce-mogelijkheid, dus alleen beheerders en winkelmanagers kunnen de API aanroepen. Gebruik voor scripts en andere geautomatiseerde aanroepers een WordPress Application Password. Het tekent elke aanvraag aan als een specifieke gebruiker met HTTP Basic-authenticatie. U hebt geen cookie of nonce nodig.

Een Application Password maken:

1. Log in als beheerder of winkelmanager en ga naar Gebruikers → Profiel.
2. Scroll naar beneden naar de sectie Application Passwords.
3. Voer een naam in, zoals Checkout Guard-automatisering, in het veld New Application Password Name.
4. Klik op Add Application Password.
5. Kopieer nu het wachtwoord, want WordPress toont het maar één keer. Het ziet eruit als xxxx xxxx xxxx xxxx xxxx xxxx. Je kunt het met of zonder spaties sturen.

Gebruik de inlognaam van die gebruiker als gebruikersnaam en het Applicatiewachtwoord als wachtwoord:

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

De API beantwoordt authenticatieproblemen op twee manieren:

• Geen inloggegevens: je krijgt 401 Unauthorized.
• Geldige inloggegevens, maar de gebruiker mist manage_woocommerce: je krijgt 403 Forbidden. Een Applicatiewachtwoord voor een Klant- of Editoraccount logt prima in, maar wordt toch geweigerd.

Het Checkout Guard admin-scherm gebruikt deze zelfde routes. Het authenticeert met je ingelogde sessiecookie plus een X-WP-Nonce header. Je hebt die aanpak alleen nodig als je eigen code binnen de WordPress-admin draait.

Route-overzicht

Paden zijn relatief ten opzichte van /wp-json/cgfw/v1.

Methode	Route	Doel
GET	/entries	Blokkeer vermeldingen, optioneel gefilterd.
POST	/entries	Maak een vermelding aan. Kan herhaald worden.
POST	/entries/batch	Maak en verwijder veel vermeldingen in één verzoek.
PUT	/entries/{id}	Werk een vermelding bij.
DELETE	/entries/{id}	Verwijder een vermelding.
POST	/check	Zoek uit of een klant geblokkeerd zou worden.
GET	/settings	Lees de plugininstellingen.
POST	/settings	Werk de plugininstellingen bij.

Hoe een geblokkeerde vermelding werkt

Elke geblokkeerde vermelding heeft deze velden:

Veld	Type	Details
id	string	Een UUID die Checkout Guard toewijst wanneer je de vermelding aanmaakt.
first_name	string	Optioneel. Ondersteunt een * wildcard, zoals jo*.
achternaam	string	Optioneel. Ondersteunt een * wildcard, zoals sm*th.
e-mailadres	string	Optioneel. Ondersteunt een * wildcard, zoals *@example.com.
ip_adres	string	Optioneel. Een enkel IPv4- of IPv6-adres, of een IPv4-wildcard zoals 192.168.1.*.
notities	string	Optioneel. Afgekapt tot 140 bytes, wat 140 tekens is voor platte Latijnse tekst en minder voor andere scripts.
created_by_user_id	integer	De gebruiker die de vermelding heeft aangemaakt.
bron	string	api wanneer de vermelding is aangemaakt met een Applicatie Wachtwoord, anders admin.

U moet ten minste één van first_name, last_name, email of ip_address verzenden. Een naam blokkeert alleen wanneer de vermelding zowel een voornaam als een achternaam heeft.

Een vermelding blokkeert een klant wanneer een van de volgende voorwaarden waar is:

• Zowel de voor- als achternaam komen overeen met de naam van de klant.
• Het e-mailadres komt overeen met het e-mailadres van de klant.
• Het IP-adres komt overeen met het IP-adres van de klant tijdens het afrekenen.

Naam- en e-mailmatching negeert hoofdletters en kleine letters. IP-adres matching is exact.

Checkout Guard leest het IP-adres van de klant op dezelfde manier als WooCommerce, dus het volgt algemene proxy-headers.

Wildcard regels

Naam- en e-mailwaarden kunnen * gebruiken om nul of meer tekens te matchen. Matching is verankerd aan de hele waarde, dus john* matcht johnny maar niet ajohn. Elk ander teken, inclusief ., matcht letterlijk.

IP-adressen accepteren alleen wildcards in IPv4-vorm. Gebruik precies vier segmenten, waarbij elk segment ofwel alleen cijfers is ofwel precies *, en ten minste één segment een cijfer is.

Elk cijfersegment moet 0 tot 255 zijn zonder voorloopnullen, dus 192.168.01.* en 256.1.1.* worden afgewezen met 400.

Waarde	Resultaat
192.168.1.*, 192.168.*.1, 192.*.*.1	Geaccepteerd
*.*.*.*	Afgekeurd met 400. Geen cijfersegment.
19*.168.1.1	Afgekeurd met 400. Gemengd segment.
1.2.3.*.5	Afgekeurd met 400. Vijf segmenten.
2001:db8::*	Afgekeurd met 400. IPv6 wildcards worden niet ondersteund.

Een paar extra limieten zijn van toepassing op elk veld:

• Geen kale wildcards. Een waarde die alles matcht, zoals *, **, *@* of *.*, wordt afgewezen met 400. *@example.com is prima omdat er letterlijke tekst overblijft.
• Maximaal 5 wildcards. Een waarde met 6 of meer * tekens wordt afgewezen met 400.
• Batch aanmaken slaat ongeldige waarden over. In een batchverzoek wordt een afgewezen item niet opgeslagen. Het wordt meegeteld in het skipped totaal, en het verzoek zelf retourneert nog steeds 200.
• Lookups blijven letterlijk. Wanneer u GET /entries filtert of een herhaalde aanmaak verzendt, wordt * behandeld als een gewoon teken. Een wildcard regel en een letterlijke waarde met dezelfde tekens zijn altijd aparte vermeldingen.

Endpoints

Lijstvermeldingen

GET /entries retourneert een lijst met vermeldingen. Voeg email, first_name, last_name of ip_address toe als queryparameters om de lijst te filteren. Naam- en e-mailfilters zijn exacte, niet-hoofdlettergevoelige overeenkomsten. Het ip_address-filter is een exacte overeenkomst. Verschillende filters worden gecombineerd met AND. Een ongeldige email of ip_address retourneert 400.

Elke vermelding in de lijst bevat ook created_by_display_name en created_by_edit_url als de aanmakende gebruiker nog bestaat.

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"

Reactie:

[
  {
    "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"
  }
]

Maak een vermelding

POST /entries maakt een vermelding aan en retourneert deze. Het herhalen van dezelfde aanvraag creëert geen duplicaten. Als er al een vermelding bestaat met dezelfde email, werkt Checkout Guard deze bij met alle niet-lege velden die u verzendt en retourneert deze. Wanneer u geen e-mail verzendt, wordt er gematcht op dezelfde voor- en achternaam. Wanneer u geen van beide verzendt, wordt er gematcht op hetzelfde ip_address.

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

Reactie:

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

Om alleen op IP-adres te blokkeren, verzendt u {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Een niet-leeg ip_address dat ongeldig is, retourneert 400.

Maak en verwijder in bulk

POST /entries/batch laat u een hele lijst synchroniseren in één aanvraag. Stuur een create-array, een delete-array met vermelding-ID's, of beide. Checkout Guard verwerkt eerst de aanmaken, elk via hetzelfde herhalingsveilige pad als een enkele aanmaak. Daarna verwerkt het de verwijderingen. Minstens één van de twee arrays moet iets bevatten, anders krijgt u 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" ]
  }'

Reactie:

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

Reactieveld	Betekenis
aangemaakt	De vermeldingen die zijn aangemaakt of bijgewerkt.
verwijderd	De ID's die zijn verwijderd.
niet_gevonden	Verwijder ID's die niet overeenkwamen met een vermelding.
overgeslagen	Hoeveel aanmaakitems zijn genegeerd. Een item wordt overgeslagen wanneer het geen naam, e-mail of IP-adres heeft, of wanneer het een ongeldig IP-adres of wildcard heeft.

Werk één vermelding bij of verwijder deze

PUT /entries/{id} wijzigt een vermelding. Stuur alleen de velden die u wilt wijzigen. De reactie is de volledige bijgewerkte vermelding. U kunt niet elk identificerend veld wissen. De vermelding moet ten minste één van de naam-, e-mail- of IP-velden behouden, anders krijgt u 400.

DELETE /entries/{id} verwijdert een vermelding en retourneert { "success": true }. Als de ID niet overeenkomt met een vermelding, retourneren beide routes 404.

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"

Controleer een klant

POST /check vertelt u of een klant zou worden geblokkeerd bij het afrekenen. Het gebruikt dezelfde matchinglogica als de live checkout, dus het antwoord komt overeen met wat een echte bestelling zou krijgen. Stuur ten minste één van email, first_name, last_name of ip_address, anders krijgt u 400.

Deze route is strikt met wildcards. De waarden die u verzendt, zijn de gegevens van een echte klant, geen patroon. Een * in een veld retourneert 400.

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

Reactie:

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

Wanneer er geen vermelding overeenkomt, is blocked false en matched_entry is null.

Instellingen lezen en bijwerken

GET /settings retourneert de plugininstellingen. De enige instelling is checkout_denial_message, wat het bericht is dat een geblokkeerde klant ziet bij het afrekenen. POST /settings wijzigt deze en retourneert de opgeslagen instellingen. Het bericht mag niet leeg zijn, anders krijg je 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."}'

Reactie:

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

Foutreacties

Fouten gebruiken het standaard WordPress-formaat, met een code, een message en een HTTP-status.

Status	Code	Wanneer het gebeurt
400	invalid_entry	Een aanmaak of update heeft geen naam, e-mailadres of IP-adres.
400	invalid_check	Een /check-verzoek heeft geen van email, first_name, last_name of ip_address.
400	invalid_batch	Een batchverzoek heeft lege create en delete arrays.
400	invalid_ip_address	Een IP-adres of IP-wildcard is ongeldig.
400	invalid_wildcard_value	Een wildcardwaarde is een kale wildcard of heeft meer dan 5 *-tekens.
400	invalid_settings	Het instellingenbericht is leeg.
400	rest_invalid_param	Een query- of /check-parameter is ongeldig, zoals een ongeldig e-mailadres of een * in een /check-veld.
401	rest_forbidden	Het verzoek heeft geen inloggegevens.
403	rest_forbidden	De gebruiker heeft niet de manage_woocommerce-mogelijkheid.
404	entry_not_found	Geen enkele vermelding komt overeen met de ID in de URL.

Een 404 zonder code betekent dat de REST-basis-URL van uw site anders is dan degene die u hebt gebruikt.

Privacy

Geblokkeerde vermeldingen zijn persoonsgegevens. Als u e-mailadressen, namen of IP-adressen van klanten opslaat, bent u verantwoordelijk voor de verwerking ervan in overeenstemming met uw privacyverplichtingen, zoals de AVG.

Probleemoplossing

Veelgestelde vragen

Hulp nodig?

Checkout Guard is een gelicentieerde plugin. Als u nog steeds vastloopt, opent u een ondersteuningsticket en voegt u de route, het verzoek dat u hebt verzonden en de reactie die u hebt ontvangen toe. Dat helpt ons team om uw setup direct te controleren.