Référence de l’API REST Checkout Guard

Parfois, vous souhaitez bloquer un client sans ouvrir l’administration WordPress. Peut-être qu’un service de notation de fraude signale une commande, ou qu’un outil de support marque quelqu’un comme abusif. Checkout Guard fournit une API REST afin que vos propres scripts et outils puissent lire et gérer vos entrées bloquées, et vérifier si un client serait bloqué.

Toutes les routes se trouvent sous un seul espace de noms, cgfw/v1. Cet article répertorie chaque route pour les entrées bloquées et les paramètres, ce qu’elle accepte, ce qu’elle renvoie et les erreurs que vous pouvez rencontrer. L’espace de noms contient également deux routes de licence que l’écran des paramètres du plugin utilise. Cet article ne les couvre pas.

Ceci est une référence développeur. Elle suppose que vous êtes à l’aise pour effectuer des requêtes HTTP avec un outil comme curl. Si vous souhaitez simplement ajouter ou supprimer une entrée bloquée manuellement, accédez à WooCommerce → Checkout Guard dans votre administration. Pour les problèmes de blocage courants, consultez le guide de dépannage de Checkout Guard.

Prérequis

Exigence	Détails
Plugin	Checkout Guard 1.0.2 ou version ultérieure. Les routes /check et /entries/batch, ainsi que la correspondance de caractères génériques, font partie de la version 1.0.2.
WordPress	5.6 ou version ultérieure pour utiliser les mots de passe d’application. Checkout Guard lui-même prend en charge WordPress 5.2 et supérieur, mais les sites de 5.2 à 5.5 ne peuvent pas utiliser la méthode d’authentification ci-dessous.
Rôle utilisateur	Un utilisateur avec la capacité manage_woocommerce, tel qu’un administrateur ou un responsable de boutique.
Connexion	HTTPS. WordPress n’active les mots de passe d’application que sur les sites HTTPS, ou sur les sites où WP_ENVIRONMENT_TYPE est défini sur local.

URL de base et format de requête

Chaque route commence par l’URL de base REST de votre site, suivie de l’espace de noms :

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

Dans chaque exemple ci-dessous, remplacez your-store.example.com par votre propre domaine.

Si votre site utilise des permaliens simples, /wp-json/ ne fonctionnera pas. Utilisez plutôt la forme rest_route :

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

Envoyez les corps de requête sous forme de JSON et définissez l’en-tête Content-Type: application/json. Les réponses sont également en JSON. Si une URL renvoie une erreur 404, vérifiez d’abord la base REST de votre site.

Authentification

Chaque route nécessite la capacité manage_woocommerce, donc seuls les administrateurs et les responsables de boutique peuvent appeler l’API. Pour les scripts et autres appelants automatisés, utilisez un mot de passe d’application WordPress. Il signe chaque requête comme un utilisateur spécifique avec l’authentification HTTP de base. Vous n’avez pas besoin de cookie ni de nonce.

Pour créer un mot de passe d’application :

1. Connectez-vous en tant qu’administrateur ou responsable de boutique et accédez à Utilisateurs → Profil.
2. Faites défiler jusqu’à la section Mots de passe d’application.
3. Entrez un nom, tel que Automatisation Checkout Guard, dans le champ Nom du nouveau mot de passe d’application.
4. Cliquez sur Ajouter un mot de passe d’application.
5. Copiez le mot de passe maintenant, car WordPress ne l'affiche qu'une seule fois. Il ressemble à xxxx xxxx xxxx xxxx xxxx xxxx. Vous pouvez l'envoyer avec ou sans les espaces.

Utilisez le nom d'utilisateur de cet utilisateur comme nom d'utilisateur et le mot de passe de l'application comme mot de passe :

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

L'API répond aux problèmes d'authentification de deux manières :

• Aucune identification : vous recevez 401 Unauthorized.
• Identification valide, mais l'utilisateur n'a pas manage_woocommerce : vous recevez 403 Forbidden. Un mot de passe d'application pour un compte Client ou Éditeur se connecte correctement mais est toujours refusé.

L'écran d'administration de Checkout Guard utilise ces mêmes routes. Il s'authentifie avec votre cookie de session connecté plus un en-tête X-WP-Nonce. Vous n'avez besoin de cette approche que si votre propre code s'exécute dans l'administration de WordPress.

Aperçu des routes

Les chemins sont relatifs à /wp-json/cgfw/v1.

Méthode	Route	Objectif
GET	/entries	Lister les entrées bloquées, éventuellement filtrées.
POST	/entries	Créer une entrée. Peut être répété sans risque.
POST	/entries/batch	Créer et supprimer plusieurs entrées en une seule requête.
PUT	/entries/{id}	Mettre à jour une entrée.
DELETE	/entries/{id}	Supprimer une entrée.
POST	/check	Déterminer si un client serait bloqué.
GET	/settings	Lire les paramètres du plugin.
POST	/settings	Mettre à jour les paramètres du plugin.

Comment fonctionne une entrée bloquée

Chaque entrée bloquée a ces champs :

Champ	Type	Détails
id	chaîne	Un UUID que Checkout Guard attribue lorsque vous créez l'entrée.
first_name	chaîne	Optionnel. Prend en charge un caractère générique *, tel que jo*.
last_name	chaîne	Optionnel. Prend en charge un caractère générique *, tel que sm*th.
courriel	chaîne	Optionnel. Prend en charge un caractère générique *, tel que *@example.com.
adresse_ip	chaîne	Optionnel. Une seule adresse IPv4 ou IPv6, ou un caractère générique IPv4 tel que 192.168.1.*.
notes	chaîne	Optionnel. Tronqué à 140 octets, ce qui correspond à 140 caractères pour du texte latin simple et moins pour d'autres scripts.
created_by_user_id	entier	L'utilisateur qui a créé l'entrée.
source	chaîne	api lorsque l'entrée a été créée avec un mot de passe d'application, sinon admin.

Vous devez envoyer au moins l'un des champs first_name, last_name, email ou ip_address. Un nom ne bloque que lorsque l'entrée a un prénom et un nom de famille.

Une entrée bloque un client lorsque l'une des conditions suivantes est remplie :

• Son prénom et son nom de famille correspondent au nom du client.
• Son e-mail correspond à l'e-mail du client.
• Son adresse IP correspond à l'adresse IP du client lors du paiement.

La correspondance du nom et de l'e-mail ignore la casse. La correspondance de l'adresse IP est exacte.

Checkout Guard lit l'adresse IP du client de la même manière que WooCommerce, il suit donc les en-têtes de proxy courants.

Règles de caractères génériques

Les valeurs de nom et d'e-mail peuvent utiliser * pour correspondre à zéro ou plusieurs caractères. La correspondance est ancrée à la valeur entière, donc john* correspond à johnny mais pas à ajohn. Tous les autres caractères, y compris ., correspondent littéralement.

Les adresses IP acceptent les caractères génériques uniquement sous forme IPv4. Utilisez exactement quatre segments, où chaque segment est soit entièrement composé de chiffres, soit exactement *, et au moins un segment est un chiffre.

Chaque segment de chiffre doit être compris entre 0 et 255 sans zéros non significatifs, donc 192.168.01.* et 256.1.1.* sont rejetés avec 400.

Valeur	Résultat
192.168.1.*, 192.168.*.1, 192.*.*.1	Accepté
*.*.*.*	Rejeté avec 400. Aucun segment de chiffre.
19*.168.1.1	Rejeté avec 400. Segment mixte.
1.2.3.*.5	Rejeté avec 400. Cinq segments.
2001:db8::*	Rejeté avec 400. Les caractères génériques IPv6 ne sont pas pris en charge.

Quelques limites supplémentaires s'appliquent à chaque champ :

• Pas de caractères génériques nus. Une valeur qui correspond à tout, comme *, **, *@* ou *.*, est rejetée avec 400. *@example.com est acceptable car il reste du texte littéral.
• Au plus 5 caractères génériques. Une valeur comportant 6 caractères * ou plus est rejetée avec 400.
• Les créations par lots ignorent les mauvaises valeurs. Dans une requête par lot, un élément rejeté n'est pas enregistré. Il est compté dans le total skipped, et la requête elle-même renvoie toujours 200.
• Les recherches restent littérales. Lorsque vous filtrez GET /entries ou envoyez une création répétée, * est traité comme un caractère normal. Une règle de caractère générique et une valeur littérale avec les mêmes caractères sont toujours des entrées distinctes.

Points de terminaison

Lister les entrées

GET /entries renvoie un tableau d'entrées. Ajoutez email, first_name, last_name ou ip_address en tant que paramètres de requête pour filtrer la liste. Les filtres de nom et d'e-mail sont des correspondances exactes, insensibles à la casse. Le filtre ip_address est une correspondance exacte. Plusieurs filtres se combinent avec AND. Un email ou ip_address invalide renvoie 400.

Chaque entrée de la liste inclut également created_by_display_name et created_by_edit_url lorsque l'utilisateur créateur existe toujours.

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"

Réponse :

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

Créer une entrée

POST /entries crée une entrée et la renvoie. Répéter la même requête ne crée pas de doublon. Si une entrée existe déjà avec le même email, Checkout Guard la met à jour avec tous les champs non vides que vous envoyez et la renvoie. Lorsque vous n'envoyez pas d'e-mail, il correspond au même prénom et nom de famille. Lorsque vous n'envoyez ni l'un ni l'autre, il correspond à la même 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"}'

Réponse :

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

Pour bloquer uniquement par adresse IP, envoyez {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Une ip_address non vide qui n'est pas valide renvoie 400.

Créer et supprimer en masse

POST /entries/batch vous permet de synchroniser une liste entière en une seule requête. Envoyez un tableau create, un tableau delete d'ID d'entrée, ou les deux. Checkout Guard traite d'abord les créations, chacune par le même chemin sécurisé contre les doublons qu'une création unique. Ensuite, il traite les suppressions. Au moins l'un des deux tableaux doit contenir quelque chose, sinon vous obtenez 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" ]
  }'

Réponse :

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

Champ de réponse	Signification
créé	Les entrées qui ont été créées ou mises à jour.
supprimé	Les ID qui ont été supprimés.
non_trouvé	Supprimer les ID qui ne correspondaient à aucune entrée.
ignoré	Combien d'éléments créés ont été ignorés. Un élément est ignoré lorsqu'il n'a pas de nom, d'e-mail ou d'adresse IP, ou lorsqu'il a une adresse IP ou un joker invalide.

Mettre à jour ou supprimer une entrée

PUT /entries/{id} modifie une entrée. Envoyez uniquement les champs que vous souhaitez modifier. La réponse est l'entrée complète mise à jour. Vous ne pouvez pas effacer tous les champs d'identification. L'entrée doit conserver au moins l'un des champs de nom, d'e-mail ou d'IP, sinon vous obtenez 400.

DELETE /entries/{id} supprime une entrée et renvoie { "success": true }. Si l'ID ne correspond à aucune entrée, les deux routes renvoient 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"

Vérifier un client

POST /check vous indique si un client serait bloqué lors du paiement. Il exécute la même logique de correspondance que le paiement en direct, de sorte que la réponse correspond à ce qu'une commande réelle obtiendrait. Envoyez au moins l'un des champs email, first_name, last_name ou ip_address, sinon vous obtenez 400.

Cette route est stricte concernant les jokers. Les valeurs que vous envoyez sont les détails d'un vrai client, pas un modèle. Un * dans n'importe quel champ renvoie 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]"}'

Réponse :

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

Lorsqu'aucune entrée ne correspond, blocked est false et matched_entry est null.

Lire et mettre à jour les paramètres

GET /settings renvoie les paramètres du plugin. Le seul paramètre est checkout_denial_message, qui est le message qu'un client bloqué voit lors du paiement. POST /settings le modifie et renvoie les paramètres enregistrés. Le message ne peut pas être vide, sinon vous obtenez 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."}'

Réponse :

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

Réponses d'erreur

Les erreurs utilisent le format WordPress standard, avec un code, un message et un statut HTTP.

Statut	Code	Quand cela arrive
400	invalid_entry	Une création ou une mise à jour n'a pas de nom, d'e-mail ou d'adresse IP.
400	invalid_check	Une requête /check n'a aucun des champs email, first_name, last_name ou ip_address.
400	invalid_batch	Une requête batch a des tableaux create et delete vides.
400	invalid_ip_address	Une adresse IP ou un wildcard IP n'est pas valide.
400	invalid_wildcard_value	Une valeur wildcard est un wildcard nu ou contient plus de 5 caractères *.
400	invalid_settings	Le message des paramètres est vide.
400	rest_invalid_param	Un paramètre de requête ou /check n'est pas valide, comme un e-mail invalide ou un * dans un champ /check.
401	rest_forbidden	La requête n'a pas d'identifiants.
403	rest_forbidden	L'utilisateur n'a pas la capacité manage_woocommerce.
404	entry_not_found	Aucune entrée ne correspond à l'ID dans l'URL.

Un 404 sans code signifie que l'URL de base REST de votre site est différente de celle que vous avez utilisée.

Confidentialité

Les entrées bloquées sont des données personnelles. Si vous stockez les e-mails, noms ou adresses IP des clients, vous êtes responsable de leur gestion conformément à vos obligations de confidentialité, telles que le RGPD.

Dépannage

Questions fréquemment posées

Besoin d'aide ?

Checkout Guard est un plugin sous licence. Si vous êtes toujours bloqué, ouvrez un ticket de support et incluez la route, la requête que vous avez envoyée et la réponse que vous avez reçue. Cela aide notre équipe à vérifier votre configuration directement.