Checkout Guard heeft nu een gedocumenteerde WooCommerce-blokkeerlijst-API. Uw fraudetool, helpdesk of synchronisatiescript kan blokkeringsregels toevoegen, verwijderen en opzoeken zonder browsersessie. Een klant kan worden geblokkeerd op het moment dat iets anders in uw stack beslist dat dit moet gebeuren.
De WooCommerce-blokkeerlijst-API is voor het eerst gedocumenteerd in Checkout Guard 1.0.2, dat ook de /check- en batch-eindpunten toevoegt, onder de cgfw/v1-naamruimte. Het is dezelfde set routes die het eigen admin-scherm van de plugin gebruikt, wat belangrijker is dan het klinkt. Er is geen tweede implementatie die uit de pas loopt met wat er daadwerkelijk gebeurt bij de checkout.
Inhoudsopgave
- Waar de WooCommerce-blokkeerlijst-API voor is
- Authenticeren met een toepassingswachtwoord
- De eindpunten
- Wat een regel kan bevatten
- Regels aanmaken zonder duplicaten te creëren
- Een hele lijst synchroniseren in één verzoek
- Vragen of een klant zou worden geblokkeerd
- Regels vinden en weten waar ze vandaan kwamen
- Wat de API zal weigeren
- Conclusie
- Veelgestelde Vragen
Waar de WooCommerce-blokkeerlijst-API voor is
De meeste blokkeerlijsten beginnen handmatig. Iemand plaatst een bestelling die u niet wilde, u opent de admin en voegt deze toe.
Dat werkt zolang het volume laag is en de beslissingen van jou zijn. Het stopt met werken als het signaal ergens anders leeft. Een fraudescore service markeert een bestelling. Je helpdeskmedewerker sluit een ticket over een beledigende klant. Een terugboeking komt binnen bij je betaalprovider. In elk geval weet iets al dat de persoon geblokkeerd moet worden, en het enige ontbrekende stuk is een manier om dat te zeggen zonder dat een mens WordPress opent.
Dat is de kloof die dit dicht. De WooCommerce blokkeerlijst API is gebouwd voor machine-aanroepers: geen cookie, geen nonce, geen admin-scherm.
Authenticeren met een toepassingswachtwoord
Geautomatiseerde aanroepers authenticeren met een WordPress Application Password via HTTP Basic Auth. Er is geen aparte Checkout Guard sleutel om aan te maken.
Volgens de WordPress-documentatie over applicatiesleutels, maak je er een aan onder Gebruikers → Profiel → Applicatiesleutels, geef het een naam zoals Checkout Guard automatisering. Kopieer de gegenereerde waarde. Deze wordt eenmalig weergegeven, in de vorm xxxx xxxx xxxx xxxx xxxx xxxx, en de spaties maken er deel van uit. Gebruik de loginnaam van het account als de Basic Auth-gebruikersnaam en dat wachtwoord als het Basic Auth-wachtwoord.
Eén vereiste is gemakkelijk te missen. Elke route op de WooCommerce blokkeerlijst API controleert de manage_woocommerce-mogelijkheid, dus het account achter het Applicatiesleutel moet een Administrator of een Shop Manager zijn. Een wachtwoord van een andere gebruiker authenticeert prima, maar wordt vervolgens geweigerd met een 403. Ontbrekende inloggegevens geven je in plaats daarvan een 401, wat een nuttige manier is om de twee fouten uit elkaar te houden.
Applicatiesleutels vereisen WordPress 5.6 of nieuwer en een site die via HTTPS wordt geleverd. Checkout Guard zelf ondersteunt WordPress 5.2, dus op een 5.2 tot 5.5 site bestaat dit authenticatiepad niet.
De eindpunten
Acht routes vormen de WooCommerce blokkeerlijst API, die de blokkeerlijst en de instellingen ervan omvatten.
| Methode | Route | Doel |
|---|---|---|
| GET | /entries | Lijst vermeldingen, optioneel gefilterd |
| POST | /entries | Maak een vermelding, idempotente |
| POST | /entries/batch | Bulk aanmaken en verwijderen |
| PUT | /entries/{id} | Werk een vermelding bij op id |
| DELETE | /entries/{id} | Verwijder een vermelding op id |
| POST | /check | Zou deze klant geblokkeerd worden? |
| GET | /settings | Lees instellingen |
| POST | /settings | Werk instellingen bij |
De basis-URL is https://your-store.example.com/wp-json/cgfw/v1. Als die URL's een 404 retourneren, controleer dan het REST-prefix van je site, want /wp-json/ is de standaard in plaats van een garantie. Een site met platte permalinks gebruikt de ?rest_route= vorm in plaats daarvan.
Het weergeven van de namespace toont nog twee routes, /license en /license/activate. Die behoren tot het eigen licentieactiveringsscherm van de plugin in plaats van de blokkeerlijst, en maken geen deel uit van de hier beschreven API.
Wat een regel kan bevatten
Een geblokkeerde vermelding bevat een id, een optionele voor- en achternaam, een optioneel e-mailadres, een optioneel IP-adres en optionele notities van maximaal 140 tekens. Het registreert ook de id van de gebruiker die het heeft aangemaakt, en een provenance-veld. Minstens één van de naam-, e-mail- of IP-velden moet ingevuld zijn.
Een vermelding blokkeert een klant wanneer een van de ingevulde velden overeenkomt. Beide namen komen overeen, of het e-mailadres komt overeen, of het IP-adres komt overeen. Namen en e-mailadressen worden hoofdletterongevoelig vergeleken. Het IP-adres van de klant bij het afrekenen wordt opgelost via de geolocatiehulp van WooCommerce, zodat een proxy of CDN voor uw winkel de vergelijking niet verstoort.
Naam-, e-mail- en IP-waarden accepteren elk een * wildcard, zodat één regel een heel e-mail domein of een IPv4-bereik kan bestrijken. IP-wildcards zijn beperkter dan de andere: alleen in de vorm van een IPv4-segment, dus 192.168.1.* werkt en 2001:db8::* niet.
Het veld notes verdient een eigen opmerking. Het is een API-veld. Het verschijnt als een kolom in de tabel Geblokkeerde vermeldingen, en het is waar die kolom zijn inhoud vandaan haalt, maar er is geen invoer voor notities in het dialoogvenster vermelding toevoegen. Als u wilt dat uw regels zichzelf later uitleggen, is de API de manier om dat in te stellen.
Regels aanmaken zonder duplicaten te creëren
POST /entries is idempotent, wat de eigenschap is die het veilig maakt om aan te roepen vanuit iets dat u niet volledig beheerst.
Als een vermelding met hetzelfde e-mailadres al bestaat, wordt deze bijgewerkt met alle niet-lege velden die u verzendt en aan u geretourneerd. Zonder e-mailadres identificeert dezelfde voor- en achternaam de vermelding. Zonder beide doet hetzelfde IP-adres dat. Als u het twee keer met hetzelfde e-mailadres aanroept, krijgt u precies één vermelding, niet twee.
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"}'Blokkeren puur op een verbinding werkt op dezelfde manier.
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"}'Wat we hebben gezien: de integraties die problemen veroorzaken, zijn degene die ervan uitgaan dat een aanmaak een aanmaak is. Een herhaalpoging na een netwerkfout, een webhook die twee keer wordt geleverd, een nachtelijke taak die de rijen van gisteren opnieuw verzendt, en plotseling heeft een blokkeringslijst vier kopieën van dezelfde persoon en niemand kan vertellen welke actueel is. Idempotentie op e-mail, naam en IP is wat dat stopt, dus stuur het identificerende veld elke keer in plaats van alleen bij de eerste aanroep.
Een hele lijst synchroniseren in één verzoek
POST /entries/batch neemt een create array en een delete array, wat de vorm is die u wilt wanneer een ander systeem de lijst beheert en WordPress de volger is.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Aanmaken gebeurt eerst, elk via hetzelfde idempotente pad als een enkele aanmaak, daarna verwijderen op id. Ten minste één van de twee arrays moet niet-leeg zijn. De reactie vertelt u wat er is gebeurd in plaats van dat u de lijst zelf hoeft te vergelijken:
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found verzamelt verwijderings-id's die niets overeenkwamen. skipped telt aanmaak-payloads die werden genegeerd omdat ze geen naam, e-mailadres of IP-adres hadden, of omdat hun IP-adres niet-leeg en ongeldig was. Een batch met ongeldige rijen retourneert nog steeds 200, dus lees skipped in plaats van alleen op de statuscode te vertrouwen.
Vragen of een klant zou worden geblokkeerd
POST /check beantwoordt de vraag direct en voert dezelfde matching-code uit als de live checkout guard. Het antwoord kan niet afwijken van wat een echte shopper ervaart, wat het doel is van het bestaan ervan in plaats van dat u de logica opnieuw implementeert.
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]"}'De respons is { "blocked": true, "matched_entry": { … } }, met matched_entry ingesteld op null wanneer niets overeenkwam. Weten welke regel iemand heeft gevangen, is meestal nuttiger dan weten dat iets dat deed.
Dit eindpunt is opzettelijk strikter dan de andere. Een kandidaat is een echte klantwaarde, nooit een patroon, dus een * in een veld wordt afgewezen met een 400. Regelopzoekingen gaan de andere kant op: GET /entries?email=*@example.com vindt die exacte opgeslagen regel, omdat opzoekingen letterlijk vergelijken en nooit een wildcard uitbreiden.
Regels vinden en weten waar ze vandaan kwamen
GET /entries zonder parameters retourneert alles. Voeg email, first_name, last_name of ip_address toe om te filteren, gecombineerd met AND wanneer u er meer dan één verzendt, en vergeleken case-insensitief.
Elke vermelding draagt ook een source veld met zich mee dat vastlegt waar het vandaan kwam: api wanneer het werd gemaakt via een Application Password, en anders admin. Wanneer een blokkeerlijst wordt onderhouden door zowel mensen als machines, is dat onderscheid wat u toestaat het ene te auditen zonder het andere te verstoren.
De instellingen-eindpunten ronden de zaken af, hoewel er slechts één instelling is om te lezen of te schrijven. checkout_denial_message is het bericht dat een geblokkeerde shopper ziet, en het kan niet leeg zijn.
Wat de API zal weigeren
Vier afwijzingen zijn het waard om te weten voordat u iets aansluit, omdat elk ervan opzettelijk is.
- Een ongeldig IP-adres wordt afgewezen met een
400bij aanmaken en bijwerken, en overgeslagen en geteld bij een batch. - Blote wildcards worden overal geweigerd. Het strippen van de asterisken, witruimte en scheidingstekens van
*,*@*of*.*laat niets over, en een regel die elke klant matcht is een storing in plaats van een blokkade. - Meer dan vijf wildcards in één waarde mislukt om dezelfde reden.
- Een vermelding zonder naam, e-mailadres en IP-adres wordt afgewezen, aangezien er niets te matchen zou zijn.
Conclusie
De WooCommerce blokkeerlijst API verandert uw regels van iets dat u onderhoudt in iets dat uw stack voor u onderhoudt. Dezelfde regels, dezelfde matching, hetzelfde gedrag bij het afrekenen, bereikbaar vanaf alles wat al weet dat een klant problemen veroorzaakt.
Als u nieuw bent met de plugin, behandelt onze introductie tot Checkout Guard wat de blokkeerlijst doet. Voor het grotere plaatje behandelen onze gids over WooCommerce data-automatiseringsworkflows en onze walkthrough van het exporteren van WooCommerce data naar Zapier de andere plaatsen waar automatisering loont.
Nog één ding dat duidelijk gezegd moet worden. Geblokkeerde vermeldingen zijn persoonsgegevens, en een IP-adres is een online identificatie onder de AVG, die overweging 30 direct noemt. Een API maakt het gemakkelijk om er snel een groot aantal te verzamelen, dus bepaal hoe lang u ze bewaart voordat u de kraan opendraait.
De WooCommerce blokkeerlijst API is beschikbaar in Checkout Guard 1.0.2.
Veelgestelde Vragen
Hoe authenticeer ik met de WooCommerce-blokkeerlijst-API?
Gebruik een WordPress-toepassingswachtwoord boven HTTP Basic Auth. Maak er een aan onder Gebruikers → Profiel → Toepassingswachtwoorden, stuur vervolgens de aanmeldingsnaam van het account als de gebruikersnaam en het gegenereerde wachtwoord als het wachtwoord. Er is geen cookie of nonce nodig.
Waarom krijg ik een 403 terwijl mijn gegevens correct zijn?
Elke route vereist de manage_woocommerce-mogelijkheid. Een toepassingswachtwoord dat toebehoort aan een gebruiker zonder deze, wordt succesvol geauthenticeerd en vervolgens geweigerd. Gebruik een Administrator- of Shop Manager-account. Een 401 betekent dat er helemaal geen inloggegevens zijn aangekomen.
Voegt het tweemaal aanroepen van het create-eindpunt een duplicaten toe?
Nee. POST /entries is idempotent. Een vermelding met hetzelfde e-mailadres wordt bijgewerkt en geretourneerd in plaats van gedupliceerd. Hetzelfde geldt voor een overeenkomende voor- en achternaam wanneer er geen e-mailadres is opgegeven, of een overeenkomend IP-adres wanneer geen van beide is opgegeven.
Kan ik mijn hele blokkeerlijst synchroniseren vanuit een ander systeem?
Ja. POST /entries/batch accepteert een create-array en een delete-array in één verzoek en retourneert een samenvatting van wat is aangemaakt, verwijderd, niet gevonden en overgeslagen. Aanmaken gebeurt vóór verwijderen.
Gebruikt de WooCommerce-blokkeerlijst-API dezelfde blokkeerlogica als de checkout?
Ja. POST /check hergebruikt dezelfde overeenkomende code als de live checkout guard, dus het antwoord kan niet afwijken van wat een echte klant ervaart. Het retourneert of de klant wordt geblokkeerd en welke vermelding overeenkwam.
Kan ik wildcards gebruiken via de API?
Ja, in regelwaarden. Naam-, e-mail- en IP-velden accepteren een *-wildcard bij aanmaken en bijwerken. Het /check-eindpunt is de uitzondering en weigert wildcards, omdat een controlekandidaat een echte klantwaarde is in plaats van een patroon.
