Checkout Guard dispose désormais d'une API de liste de blocage WooCommerce documentée. Votre outil de fraude, votre helpdesk ou votre script de synchronisation peut ajouter, supprimer et rechercher des règles de blocage sans session de navigateur. Un client peut être bloqué dès que quelque chose d'autre dans votre pile décide qu'il devrait l'être.
L'API de liste de blocage WooCommerce est documentée pour la première fois dans Checkout Guard 1.0.2, qui ajoute également les points de terminaison /check et batch, sous l'espace de noms cgfw/v1. C'est le même ensemble de routes que celui utilisé par l'écran d'administration du plugin, ce qui est plus important qu'il n'y paraît. Il n'y a pas de deuxième implémentation pour dériver de ce qui se passe réellement à la caisse.
Table des matières
- À quoi sert l'API de liste de blocage WooCommerce
- Authentification avec un mot de passe d'application
- Les points de terminaison
- Ce qu'une règle peut contenir
- Créer des règles sans créer de doublons
- Synchroniser une liste entière en une seule requête
- Demander si un client serait bloqué
- Trouver des règles et savoir d'où elles viennent
- Ce que l'API refusera
- Conclusion
- Questions fréquemment posées
À quoi sert l'API de liste de blocage WooCommerce
La plupart des listes de blocage commencent manuellement. Quelqu'un passe une commande que vous ne vouliez pas, vous ouvrez l'administration et vous l'ajoutez.
Cela fonctionne lorsque le volume est faible et que les décisions vous appartiennent. Cela cesse de fonctionner lorsque le signal vit ailleurs. Un service de notation de fraude signale une commande. Votre agent du service d'assistance ferme un ticket concernant un client abusif. Un litige arrive chez votre fournisseur de paiement. Dans chaque cas, quelque chose sait déjà que la personne doit être bloquée, et la seule pièce manquante est un moyen de le dire sans qu'un humain n'ouvre WordPress.
C'est la lacune que cela comble. L'API de liste de blocage de WooCommerce est conçue pour les appelants machine : pas de cookie, pas de nonce, pas d'écran d'administration.
Authentification avec un mot de passe d'application
Les appelants automatisés s'authentifient avec un mot de passe d'application WordPress via l'authentification HTTP Basic. Il n'y a pas de clé Checkout Guard distincte à créer.
Conformément à la documentation WordPress sur les mots de passe d'application, vous en créez un sous Utilisateurs → Profil → Mots de passe d'application, donnez-lui un nom tel que Automatisation Checkout Guard. Copiez la valeur générée. Elle n'est affichée qu'une seule fois, sous la forme xxxx xxxx xxxx xxxx xxxx xxxx, et les espaces en font partie. Utilisez le nom d'utilisateur du compte comme nom d'utilisateur Basic Auth et ce mot de passe comme mot de passe Basic Auth.
Une exigence est facile à manquer. Chaque route de l'API de liste de blocage de WooCommerce vérifie la capacité manage_woocommerce, donc le compte derrière le mot de passe d'application doit être un administrateur ou un responsable de boutique. Un mot de passe appartenant à tout autre utilisateur s'authentifie parfaitement bien et est ensuite refusé avec un 403. Des identifiants manquants vous donnent un 401 à la place, ce qui est un moyen utile de distinguer les deux échecs.
Les mots de passe d'application nécessitent WordPress 5.6 ou plus récent et un site servi via HTTPS. Checkout Guard lui-même prend en charge WordPress 5.2, donc sur un site 5.2 à 5.5, ce chemin d'authentification n'existe pas.
Les points de terminaison
Huit routes composent l'API de liste de blocage de WooCommerce, couvrant la liste de blocage et ses paramètres.
| Méthode | Route | Objectif |
|---|---|---|
| GET | /entries | Lister les entrées, éventuellement filtrées |
| POST | /entries | Créer une entrée, idempotente |
| POST | /entries/batch | Création et suppression en masse |
| PUT | /entries/{id} | Mettre à jour une entrée par id |
| DELETE | /entries/{id} | Supprimer une entrée par id |
| POST | /check | Ce client serait-il bloqué ? |
| GET | /settings | Lire les paramètres |
| POST | /settings | Mettre à jour les paramètres |
L'URL de base est https://votre-magasin.exemple.com/wp-json/cgfw/v1. Si ces URL renvoient un 404, vérifiez le préfixe REST de votre site, car /wp-json/ est le défaut plutôt qu'une garantie. Un site avec des permaliens simples utilise la forme ?rest_route= à la place.
Lister l'espace de noms montre deux routes supplémentaires, /license et /license/activate. Celles-ci appartiennent à l'écran d'activation de licence du plugin lui-même plutôt qu'à la liste de blocage, et elles ne font pas partie de l'API décrite ici.
Ce qu'une règle peut contenir
Une entrée bloquée contient un id, un prénom et un nom facultatifs, un e-mail facultatif, une adresse IP facultative et des notes facultatives allant jusqu'à 140 caractères. Elle enregistre également l'id de l'utilisateur qui l'a créée et un champ de provenance. Au moins l'un des champs nom, e-mail ou IP doit être rempli.
Une entrée bloque un client lorsque l’un de ses champs renseignés correspond. Les deux noms correspondent, ou l’adresse e-mail correspond, ou l’adresse IP correspond. Les noms et les e-mails sont comparés sans tenir compte de la casse. L’adresse IP du client lors du paiement est résolue à l’aide de l’outil de géolocalisation de WooCommerce, de sorte qu’un proxy ou un CDN devant votre boutique ne casse pas la comparaison.
Les valeurs de nom, d’e-mail et d’IP acceptent chacune un caractère générique *, de sorte qu’une règle puisse couvrir un domaine d’e-mail entier ou une plage IPv4. Les caractères génériques IP sont plus restrictifs que les autres : uniquement sous forme de segment IPv4, donc 192.168.1.* fonctionne et 2001:db8::* non.
Le champ notes mérite une note à lui seul. C’est un champ d’API. Il apparaît comme une colonne dans le tableau des entrées bloquées, et c’est là que cette colonne tire son contenu, mais il n’y a pas de champ de notes dans la boîte de dialogue d’ajout d’entrée. Si vous souhaitez que vos règles s’expliquent d’elles-mêmes plus tard, l’API est la solution.
Créer des règles sans créer de doublons
POST /entries est idempotent, ce qui est la propriété qui le rend sûr à appeler à partir de quelque chose que vous ne contrôlez pas entièrement.
Si une entrée avec le même e-mail existe déjà, elle est mise à jour avec les champs non vides que vous envoyez et vous est retournée. Sans e-mail, le même prénom et nom identifie l’entrée. Sans aucun des deux, la même adresse IP le fait. L’appeler deux fois avec le même e-mail vous donne exactement une entrée, pas deux.
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"}'Le blocage basé uniquement sur une connexion fonctionne de la même manière.
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"}'Ce que nous avons vu : les intégrations qui causent des problèmes sont celles qui supposent qu’une création est une création. Une nouvelle tentative après un délai d’attente réseau, un webhook livré deux fois, un travail nocturne qui renvoie les lignes d’hier, et soudain une liste de blocage a quatre copies de la même personne et personne ne peut dire laquelle est actuelle. L’idempotence sur l’e-mail, le nom et l’IP est ce qui arrête cela, alors envoyez le champ d’identification à chaque fois plutôt que seulement lors du premier appel.
Synchroniser une liste entière en une seule requête
POST /entries/batch prend un tableau create et un tableau delete, ce qui est la forme que vous souhaitez lorsqu’un autre système possède la liste et que WordPress est le suiveur.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Les créations s’exécutent d’abord, chacune via le même chemin idempotent qu’une création unique, puis les suppressions par id. Au moins l’un des deux tableaux doit être non vide. La réponse vous indique ce qui s’est passé plutôt que de vous faire comparer la liste vous-même :
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found collecte les id de suppression qui n’ont rien trouvé. skipped compte les charges utiles de création qui ont été ignorées parce qu’elles ne contenaient ni nom, ni e-mail, ni IP, ou parce que leur IP était non vide et invalide. Un lot contenant des lignes incorrectes renvoie toujours 200, alors lisez skipped plutôt que de vous fier uniquement au code d’état.
Demander si un client serait bloqué
POST /check répond directement à la question, et il exécute le même code de correspondance que le garde de paiement en direct. La réponse ne peut pas dériver de ce qu’un acheteur réel expérimente, ce qui est le but de son existence plutôt que de réimplémenter la logique.
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]"}'La réponse est { "blocked": true, "matched_entry": { … } }, avec matched_entry défini sur null lorsque rien ne correspond. Savoir quelle règle a intercepté quelqu'un est généralement plus utile que de savoir que quelque chose l'a fait.
Ce point de terminaison est délibérément plus strict que les autres. Un candidat est une valeur client réelle, jamais un modèle, donc un * dans n'importe quel champ est rejeté avec un 400. Les recherches de règles vont dans l'autre sens : GET /entries?email=*@example.com trouve cette règle stockée exacte, car les recherches comparent littéralement et n'étendent jamais un joker.
Trouver des règles et savoir d'où elles viennent
GET /entries sans paramètres renvoie tout. Ajoutez email, first_name, last_name ou ip_address pour filtrer, combinés avec AND lorsque vous en envoyez plus d'un, et comparés sans tenir compte de la casse.
Chaque entrée porte également un champ source enregistrant d'où elle provient : api lorsqu'elle a été créée via un mot de passe d'application, et admin sinon. Lorsqu'une liste de blocage est maintenue par des personnes et des machines, cette distinction vous permet d'auditer l'une sans perturber l'autre.
Les points de terminaison de configuration complètent le tout, bien qu'il n'y ait qu'un seul paramètre à lire ou à écrire. checkout_denial_message est le message qu'un acheteur bloqué voit, et il ne peut pas être vide.
Ce que l'API refusera
Quatre rejets valent la peine d'être connus avant de tout connecter, car chacun est délibéré.
- Une adresse IP malformée est rejetée avec un
400lors de la création et de la mise à jour, et ignorée et comptée lors d'un traitement par lots. - Les jokers nus sont refusés partout. Supprimer les astérisques, les espaces blancs et les séparateurs de
*,*@*ou*.*ne laisse rien, et une règle correspondant à chaque client est une panne plutôt qu'un blocage. - Plus de cinq jokers dans une seule valeur échouent pour la même raison.
- Une entrée sans nom, sans e-mail et sans IP est rejetée, car il n'y aurait rien à faire correspondre.
Conclusion
L'API de liste de blocage WooCommerce transforme vos règles de quelque chose que vous maintenez en quelque chose que votre pile maintient pour vous. Mêmes règles, même correspondance, même comportement à la caisse, accessible depuis tout ce qui sait déjà qu'un client est un problème.
Si vous êtes nouveau dans le plugin, notre introduction à Checkout Guard explique ce que fait la liste de blocage. Pour une vue d'ensemble, notre guide sur les flux de travail d'automatisation des données WooCommerce et notre présentation de l'exportation des données WooCommerce vers Zapier couvrent les autres domaines où l'automatisation est rentable.
Une dernière chose qui vaut la peine d'être dite clairement. Les entrées bloquées sont des données personnelles, et une adresse IP est un identifiant en ligne en vertu du RGPD, que le considérant 30 nomme directement. Une API facilite l'accumulation d'un grand nombre d'entre elles rapidement, alors décidez combien de temps vous les conservez avant d'ouvrir le robinet.
L'API de liste de blocage WooCommerce est disponible dans Checkout Guard 1.0.2.
Questions fréquemment posées
Comment puis-je m'authentifier auprès de l'API de liste de blocage WooCommerce ?
Utilisez un mot de passe d'application WordPress sur l'authentification HTTP de base. Créez-en un sous Utilisateurs → Profil → Mots de passe d'application, puis envoyez le nom de connexion du compte comme nom d'utilisateur et le mot de passe généré comme mot de passe. Aucun cookie ni nonce n'est nécessaire.
Pourquoi reçois-je une erreur 403 alors que mes identifiants sont corrects ?
Chaque route nécessite la capacité manage_woocommerce. Un mot de passe d'application appartenant à un utilisateur sans celle-ci s'authentifie avec succès puis est refusé. Utilisez un compte Administrateur ou Gestionnaire de boutique. Un 401 signifie qu'aucun identifiant n'est arrivé.
Appeler le point de terminaison create deux fois ajoutera-t-il un doublon ?
Non. POST /entries est idempotent. Une entrée avec le même e-mail est mise à jour et renvoyée plutôt que dupliquée. Il en va de même pour un nom et un prénom correspondants lorsqu'aucun e-mail n'est donné, ou une adresse IP correspondante lorsque ni l'un ni l'autre n'est donné.
Puis-je synchroniser toute ma liste de blocage depuis un autre système ?
Oui. POST /entries/batch accepte un tableau create et un tableau delete en une seule requête et renvoie un résumé de ce qui a été créé, supprimé, non trouvé et ignoré. Les créations sont effectuées avant les suppressions.
L'API de liste de blocage WooCommerce utilise-t-elle la même logique de blocage que la caisse ?
Oui. POST /check réutilise le même code correspondant que le garde de paiement en direct, donc sa réponse ne peut pas dériver de ce qu'un client réel expérimente. Il renvoie si le client est bloqué et quelle entrée a correspondu.
Puis-je utiliser des caractères génériques via l'API ?
Oui, dans les valeurs des règles. Les champs Nom, e-mail et IP acceptent un joker * lors de la création et de la mise à jour. Le point de terminaison /check est l'exception et rejette les jokers, car un candidat de vérification est une valeur de client réelle plutôt qu'un modèle.
