Riferimento API REST di Checkout Guard

A volte si desidera bloccare un cliente senza aprire l'amministrazione di WordPress. Forse un servizio di punteggio frodi segnala un ordine, o uno strumento di helpdesk contrassegna qualcuno come offensivo. Checkout Guard fornisce un'API REST in modo che i tuoi script e strumenti possano leggere e gestire le tue voci bloccate, e verificare se un cliente verrebbe bloccato.

Tutti i percorsi si trovano sotto un unico namespace, cgfw/v1. Questo articolo elenca ogni percorso per voci bloccate e impostazioni, cosa accetta, cosa restituisce e gli errori che potresti incontrare. Il namespace ha anche due percorsi di licenza che la schermata Impostazioni del plugin utilizza. Questo articolo non li copre.

Questo è un riferimento per sviluppatori. Presuppone che tu sia a tuo agio nell'effettuare richieste HTTP con uno strumento come curl. Se vuoi solo aggiungere o rimuovere una voce bloccata manualmente, vai su WooCommerce → Checkout Guard nella tua amministrazione. Per problemi comuni di blocco, consulta la guida alla risoluzione dei problemi di Checkout Guard.

Prerequisiti

Requisito	Dettagli
Plugin	Checkout Guard 1.0.2 o versioni successive. I percorsi /check e /entries/batch, e la corrispondenza con caratteri jolly, fanno parte della versione 1.0.2.
WordPress	5.6 o versioni successive per utilizzare le Password per applicazioni. Checkout Guard stesso supporta WordPress 5.2 e versioni successive, ma i siti da 5.2 a 5.5 non possono utilizzare il metodo di autenticazione di seguito.
Ruolo utente	Un utente con la capacità manage_woocommerce, come un Amministratore o un Responsabile del negozio.
Connessione	HTTPS. WordPress abilita le Password per applicazioni solo sui siti HTTPS, o sui siti in cui WP_ENVIRONMENT_TYPE è impostato su local.

URL di base e formato della richiesta

Ogni percorso inizia con l'URL di base REST del tuo sito seguito dal namespace:

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

In ogni esempio seguente, sostituisci your-store.example.com con il tuo dominio.

Se il tuo sito utilizza permalink semplici, /wp-json/ non funzionerà. Usa invece il formato rest_route:

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

Invia i corpi delle richieste come JSON e imposta l'intestazione Content-Type: application/json. Anche le risposte sono in formato JSON. Se un URL restituisce un 404, controlla prima la base REST del tuo sito.

Autenticazione

Ogni percorso richiede la capacità manage_woocommerce, quindi solo Amministratori e Responsabili del negozio possono chiamare l'API. Per script e altri chiamanti automatizzati, utilizza una Password per applicazioni di WordPress. Firma ogni richiesta come un utente specifico con autenticazione HTTP Basic. Non hai bisogno di un cookie o di un nonce.

Per creare una Password per applicazioni:

1. Accedi come Amministratore o Responsabile del negozio e vai su Utenti → Profilo.
2. Scorri verso il basso fino alla sezione Password per applicazioni.
3. Inserisci un nome, ad esempio automazione Checkout Guard, nel campo Nome nuova Password per applicazioni.
4. Fai clic su Aggiungi Password per applicazioni.
5. Copia la password ora, perché WordPress la mostra solo una volta. Assomiglia a xxxx xxxx xxxx xxxx xxxx xxxx. Puoi inviarla con o senza spazi.

Usa il nome utente di quell'utente come nome utente e la Password dell'applicazione come password:

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

L'API risponde ai problemi di autenticazione in due modi:

• Nessuna credenziale: ottieni 401 Unauthorized.
• Credenziali valide, ma l'utente non ha manage_woocommerce: ottieni 403 Forbidden. Una Password dell'applicazione per un account Cliente o Editor si autentica correttamente ma viene comunque rifiutata.

La schermata di amministrazione di Checkout Guard utilizza queste stesse route. Si autentica con il cookie della tua sessione di accesso più un'intestazione X-WP-Nonce. Hai bisogno di questo approccio solo se il tuo codice viene eseguito all'interno dell'amministrazione di WordPress.

Panoramica delle route

I percorsi sono relativi a /wp-json/cgfw/v1.

Metodo	Percorso	Scopo
GET	/entries	Elenca le voci bloccate, opzionalmente filtrate.
POST	/entries	Crea una voce. Può essere ripetuta.
POST	/entries/batch	Crea ed elimina molte voci in una sola richiesta.
PUT	/entries/{id}	Aggiorna una voce.
DELETE	/entries/{id}	Elimina una voce.
POST	/check	Scopri se un cliente verrebbe bloccato.
GET	/settings	Leggi le impostazioni del plugin.
POST	/settings	Aggiorna le impostazioni del plugin.

Come funziona una voce bloccata

Ogni voce bloccata ha questi campi:

Campo	Tipo	Dettagli
id	stringa	Un UUID che Checkout Guard assegna quando crei la voce.
Nome	stringa	Opzionale. Supporta un carattere jolly *, come jo*.
cognome	stringa	Opzionale. Supporta un carattere jolly *, come sm*th.
email	stringa	Opzionale. Supporta un carattere jolly *, come *@example.com.
indirizzo_ip	stringa	Opzionale. Un singolo indirizzo IPv4 o IPv6, o un carattere jolly IPv4 come 192.168.1.*.
note	stringa	Opzionale. Tronca a 140 byte, che sono 140 caratteri per testo latino semplice e meno per altri script.
created_by_user_id	intero	L'utente che ha creato la voce.
source	stringa	api quando la voce è stata creata con una Password Applicazione, altrimenti admin.

Devi inviare almeno uno tra first_name, last_name, email o ip_address. Un nome blocca solo quando la voce ha sia il nome che il cognome.

Una voce blocca un cliente quando una qualsiasi delle seguenti condizioni è vera:

• Sia il nome che il cognome corrispondono al nome del cliente.
• La sua email corrisponde all'email del cliente.
• Il suo indirizzo IP corrisponde all'indirizzo IP del cliente al momento del checkout.

La corrispondenza di nome ed email ignora maiuscole e minuscole. La corrispondenza dell'indirizzo IP è esatta.

Checkout Guard legge l'indirizzo IP del cliente nel modo in cui lo fa WooCommerce, quindi segue le intestazioni proxy comuni.

Regole con caratteri jolly

I valori di nome ed email possono usare * per corrispondere a zero o più caratteri. La corrispondenza è ancorata all'intero valore, quindi john* corrisponde a johnny ma non a ajohn. Ogni altro carattere, incluso ., corrisponde letteralmente.

Gli indirizzi IP accettano caratteri jolly solo in formato IPv4. Usa esattamente quattro segmenti, dove ogni segmento è composto da tutte cifre o esattamente *, e almeno un segmento è una cifra.

Ogni segmento di cifre deve essere da 0 a 255 senza zeri iniziali, quindi 192.168.01.* e 256.1.1.* vengono rifiutati con 400.

Valore	Risultato
192.168.1.*, 192.168.*.1, 192.*.*.1	Accettato
*.*.*.*	Rifiutato con 400. Nessun segmento di cifre.
19*.168.1.1	Rifiutato con 400. Segmento misto.
1.2.3.*.5	Rifiutato con 400. Cinque segmenti.
2001:db8::*	Rifiutato con 400. I caratteri jolly IPv6 non sono supportati.

Alcuni limiti aggiuntivi si applicano a ogni campo:

• Nessun carattere jolly nudo. Un valore che corrisponde a tutto, come *, **, *@* o *.*, viene rifiutato con 400. *@example.com va bene perché ha testo letterale rimanente.
• Massimo 5 caratteri jolly. Un valore con 6 o più caratteri * viene rifiutato con 400.
• Le creazioni batch saltano i valori errati. In una richiesta batch, un elemento rifiutato non viene salvato. Viene conteggiato nel totale skipped e la richiesta stessa restituisce comunque 200.
• Le ricerche rimangono letterali. Quando filtri GET /entries o invii una creazione ripetuta, * viene trattato come un carattere normale. Una regola con caratteri jolly e un valore letterale con gli stessi caratteri sono sempre voci separate.

Endpoint

Elenca le voci

GET /entries restituisce un array di voci. Aggiungi uno qualsiasi tra email, first_name, last_name o ip_address come parametri di query per filtrare l'elenco. I filtri per nome ed email sono corrispondenze esatte, insensibili alle maiuscole/minuscole. Il filtro ip_address è una corrispondenza esatta. Diversi filtri si combinano con AND. Un email o ip_address non valido restituisce 400.

Ogni voce nell'elenco include anche created_by_display_name e created_by_edit_url quando l'utente che l'ha creata esiste ancora.

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"

Risposta:

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

Crea una voce

POST /entries crea una voce e la restituisce. Ripetere la stessa richiesta non crea un duplicato. Se una voce esiste già con la stessa email, Checkout Guard la aggiorna con eventuali campi non vuoti che invii e la restituisce. Quando non invii un'email, corrisponde per nome e cognome uguali. Quando non invii nessuno dei due, corrisponde per ip_address uguale.

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

Risposta:

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

Per bloccare solo per indirizzo IP, invia {"ip_address":"203.0.113.42","notes":"repeat spammer"}. Un ip_address non vuoto non valido restituisce 400.

Crea ed elimina in blocco

POST /entries/batch ti consente di sincronizzare un intero elenco in una richiesta. Invia un array create, un array delete di ID voce, o entrambi. Checkout Guard elabora prima le creazioni, ognuna attraverso lo stesso percorso a prova di ripetizione di una singola creazione. Poi elabora le eliminazioni. Almeno uno dei due array deve contenere qualcosa, altrimenti ottieni 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" ]
  }'

Risposta:

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

Campo di risposta	Significato
creato	Le voci che sono state create o aggiornate.
eliminato	Gli ID che sono stati rimossi.
non_trovato	Elimina gli ID che non corrispondevano a nessuna voce.
saltato	Quanti elementi di creazione sono stati ignorati. Un elemento viene saltato quando non ha nome, email o indirizzo IP, o quando ha un indirizzo IP o un carattere jolly non valido.

Aggiorna o elimina una voce

PUT /entries/{id} modifica una voce. Invia solo i campi che desideri modificare. La risposta è la voce completa aggiornata. Non puoi cancellare ogni campo identificativo. La voce deve mantenere almeno uno dei campi nome, email o IP, altrimenti ottieni 400.

DELETE /entries/{id} rimuove una voce e restituisce { "success": true }. Se l'ID non corrisponde a una voce, entrambi i percorsi restituiscono 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"

Controlla un cliente

POST /check ti dice se un cliente verrebbe bloccato al checkout. Esegue la stessa logica di corrispondenza del checkout live, quindi la risposta corrisponde a ciò che otterrebbe un ordine reale. Invia almeno uno tra email, first_name, last_name o ip_address, altrimenti ottieni 400.

Questo percorso è rigoroso riguardo ai caratteri jolly. I valori che invii sono i dettagli di un cliente reale, non un modello. Un * in qualsiasi campo restituisce 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]"}'

Risposta:

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

Quando nessuna voce corrisponde, blocked è false e matched_entry è null.

Leggi e aggiorna le impostazioni

GET /settings restituisce le impostazioni del plugin. L'unica impostazione è checkout_denial_message, che è il messaggio che un cliente bloccato vede al checkout. POST /settings la modifica e restituisce le impostazioni salvate. Il messaggio non può essere vuoto, altrimenti ottieni 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."}'

Risposta:

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

Risposte di errore

Gli errori utilizzano il formato standard di WordPress, con un code, un message e uno stato HTTP.

Stato	Codice	Quando succede
400	voce_non_valida	Una creazione o un aggiornamento non ha nome, email o indirizzo IP.
400	controllo_non_valido	Una richiesta /check non ha email, first_name, last_name o ip_address.
400	lotto_non_valido	Una richiesta batch ha array create e delete vuoti.
400	indirizzo_ip_non_valido	Un indirizzo IP o un wildcard IP non è valido.
400	valore_wildcard_non_valido	Un valore wildcard è un wildcard nudo o ha più di 5 caratteri *.
400	impostazioni_non_valide	Il messaggio delle impostazioni è vuoto.
400	rest_parametro_non_valido	Un parametro di query o /check non è valido, come un'email non valida o un * in un campo /check.
401	rest_proibito	La richiesta non ha credenziali.
403	rest_proibito	L'utente non ha la capacità manage_woocommerce.
404	voce_non_trovata	Nessuna voce corrisponde all'ID nell'URL.

Un 404 senza codice significa che l'URL di base REST del tuo sito è diverso da quello che hai usato.

Privacy

Le voci bloccate sono dati personali. Se memorizzi email, nomi o indirizzi IP dei clienti, sei responsabile della loro gestione in linea con i tuoi obblighi di privacy, come il GDPR.

Risoluzione dei problemi

Domande frequenti

Serve aiuto?

Checkout Guard è un plugin con licenza. Se sei ancora bloccato, apri un ticket di supporto e includi il percorso, la richiesta che hai inviato e la risposta che hai ricevuto. Ciò aiuta il nostro team a controllare direttamente la tua configurazione.