Checkout Guard ora ha un'API documentata per la block list di WooCommerce. Il tuo strumento antifrode, helpdesk o script di sincronizzazione può aggiungere, rimuovere e cercare regole di blocco senza una sessione del browser. Un cliente può essere bloccato nel momento in cui qualcos'altro nel tuo stack decide che dovrebbe esserlo.
L'API della block list di WooCommerce è documentata per la prima volta in Checkout Guard 1.0.2, che aggiunge anche gli endpoint /check e batch, sotto lo spazio dei nomi cgfw/v1. È lo stesso set di route che utilizza la schermata di amministrazione del plugin, il che è più importante di quanto sembri. Non esiste una seconda implementazione che possa andare fuori sincrono con ciò che accade effettivamente al checkout.
Indice dei contenuti
- A cosa serve l'API della block list di WooCommerce
- Autenticazione con una password per applicazioni
- Gli endpoint
- Cosa può contenere una regola
- Creazione di regole senza creare duplicati
- Sincronizzazione di un'intera lista in una richiesta
- Chiedere se un cliente verrebbe bloccato
- Ricerca di regole e sapere da dove provengono
- Cosa rifiuterà l'API
- Conclusione
- Domande Frequenti
A cosa serve l'API della block list di WooCommerce
La maggior parte delle block list inizia manualmente. Qualcuno effettua un ordine che non volevi, apri l'amministrazione e lo aggiungi.
Ci ò funziona finché il volume è basso e le decisioni spettano a te. Smette di funzionare quando il segnale vive altrove. Un servizio di punteggio frodi segnala un ordine. Il tuo agente dell'helpdesk chiude un ticket su un cliente abusivo. Un chargeback finisce nel tuo provider di pagamento. In ogni caso, qualcosa sa già che la persona dovrebbe essere bloccata, e l'unica parte mancante è un modo per dirlo senza che un umano apra WordPress.
Questo è il divario che questo colma. L'API della lista bloccati di WooCommerce è costruita per chiamanti automatici: nessun cookie, nessun nonce, nessuna schermata di amministrazione.
Autenticazione con una password per applicazioni
I chiamanti automatici si autenticano con una Password per Applicazioni di WordPress tramite autenticazione HTTP Basic. Non c'è una chiave separata di Checkout Guard da creare.
Secondo la documentazione di WordPress sulle password per applicazioni, ne crei una sotto Utenti → Profilo → Password per Applicazioni, le dai un nome come automazione Checkout Guard. Copia il valore generato. Viene mostrato una sola volta, nella forma xxxx xxxx xxxx xxxx xxxx xxxx, e gli spazi ne fanno parte. Usa il nome utente dell'account come nome utente Basic Auth e quella password come password Basic Auth.
Un requisito è facile da trascurare. Ogni route dell'API della lista bloccati di WooCommerce controlla la capacità manage_woocommerce, quindi l'account dietro la Password per Applicazioni deve essere un Amministratore o un Gestore del Negozio. Una password appartenente a qualsiasi altro utente si autentica perfettamente ma viene poi rifiutata con un 403. Credenziali mancanti ti danno invece un 401, che è un modo utile per distinguere i due fallimenti.
Le Password per Applicazioni richiedono WordPress 5.6 o più recente e un sito servito tramite HTTPS. Checkout Guard stesso supporta WordPress 5.2, quindi su un sito da 5.2 a 5.5 questo percorso di autenticazione non esiste.
Gli endpoint
Otto route compongono l'API della lista bloccati di WooCommerce, coprendo la lista bloccati e le sue impostazioni.
| Metodo | Route | Scopo |
|---|---|---|
| GET | /entries | Elenca le voci, opzionalmente filtrate |
| POST | /entries | Crea una voce, idempotente |
| POST | /entries/batch | Creazione e cancellazione in blocco |
| PUT | /entries/{id} | Aggiorna una voce tramite id |
| DELETE | /entries/{id} | Cancella una voce tramite id |
| POST | /check | Questo cliente verrebbe bloccato? |
| GET | /settings | Leggi le impostazioni |
| POST | /settings | Aggiorna le impostazioni |
L'URL di base è https://your-store.example.com/wp-json/cgfw/v1. Se quegli URL restituiscono un 404, controlla il prefisso REST del tuo sito, perché /wp-json/ è l'impostazione predefinita piuttosto che una garanzia. Un sito con permalink semplici usa invece la forma ?rest_route=.
Elencando lo spazio dei nomi vengono mostrate altre due route, /license e /license/activate. Quelle appartengono alla schermata di attivazione della licenza del plugin stesso piuttosto che alla lista bloccati, e non fanno parte dell'API descritta qui.
Cosa può contenere una regola
Una voce bloccata contiene un id, un nome e cognome opzionali, un'email opzionale, un indirizzo IP opzionale e note opzionali fino a 140 caratteri. Registra anche l'id dell'utente che l'ha creata e un campo di provenienza. Almeno uno dei campi nome, email o IP deve essere compilato.
Una voce blocca un cliente quando uno qualsiasi dei suoi campi popolati corrisponde. Entrambi i nomi corrispondono, o l'email corrisponde, o l'indirizzo IP corrisponde. Nomi ed email vengono confrontati senza distinzione tra maiuscole e minuscole. L'IP del cliente al momento del checkout viene risolto tramite l'helper di geolocalizzazione di WooCommerce, quindi un proxy o un CDN davanti al tuo negozio non interrompe il confronto.
I valori di nome, email e IP accettano ciascuno un carattere jolly *, quindi una regola può coprire un intero dominio email o un intervallo IPv4. I caratteri jolly IP sono più restrittivi degli altri: solo in formato segmento IPv4, quindi 192.168.1.* funziona e 2001:db8::* no.
Il campo notes merita una nota a sé. È un campo API. Appare come una colonna nella tabella delle Voci Bloccate, ed è da lì che la colonna ottiene il suo contenuto, ma non c'è un input per le note nella finestra di dialogo di aggiunta voce. Se vuoi che le tue regole si spieghino da sole in seguito, l'API è la strada da percorrere.
Creazione di regole senza creare duplicati
POST /entries è idempotente, che è la proprietà che lo rende sicuro da chiamare da qualcosa che non si controlla completamente.
Se una voce con la stessa email esiste già, viene aggiornata con qualsiasi campo non vuoto che invii e restituita. Senza email, lo stesso nome e cognome identificano la voce. Senza nessuno dei due, lo stesso indirizzo IP lo fa. Chiamarlo due volte con la stessa email ti dà esattamente una voce, non due.
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"}'Il blocco puramente sulla connessione funziona allo stesso modo.
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"}'Cosa abbiamo visto: le integrazioni che causano problemi sono quelle che presumono che una creazione sia una creazione. Un nuovo tentativo dopo un timeout di rete, un webhook consegnato due volte, un processo notturno che reinvia le righe di ieri, e improvvisamente una lista di blocchi ha quattro copie della stessa persona e nessuno può dire quale sia quella attuale. L'idempotenza su email, nome e IP è ciò che ferma tutto ciò, quindi invia il campo identificativo ogni volta piuttosto che solo alla prima chiamata.
Sincronizzazione di un'intera lista in una richiesta
POST /entries/batch accetta un array create e un array delete, che è la forma desiderata quando un altro sistema possiede la lista e WordPress è il follower.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Le creazioni vengono eseguite per prime, ognuna attraverso lo stesso percorso idempotente di una singola creazione, poi le eliminazioni per ID. Almeno uno dei due array deve essere non vuoto. La risposta ti dice cosa è successo piuttosto che farti confrontare la lista da solo:
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found raccoglie gli ID di eliminazione che non hanno trovato corrispondenze. skipped conta i payload di creazione che sono stati ignorati perché non contenevano nome, email o IP, o perché il loro IP non era vuoto e non valido. Un batch contenente righe errate restituisce comunque 200, quindi leggi skipped piuttosto che fidarti solo del codice di stato.
Chiedere se un cliente verrebbe bloccato
POST /check risponde direttamente alla domanda ed esegue lo stesso codice di corrispondenza del guardiano del checkout live. La risposta non può discostarsi da ciò che sperimenta un vero acquirente, che è il motivo della sua esistenza piuttosto che l'implementazione della logica da parte tua.
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 risposta è { "blocked": true, "matched_entry": { … } }, con matched_entry impostato su null quando nulla corrisponde. Sapere quale regola ha bloccato qualcuno è di solito più utile che sapere che qualcosa lo ha fatto.
Questo endpoint è volutamente più restrittivo degli altri. Un candidato è un valore cliente reale, mai un pattern, quindi un * in qualsiasi campo viene rifiutato con un 400. Le ricerche delle regole vanno nell'altro verso: GET /entries?email=*@example.com trova quella regola memorizzata esatta, perché le ricerche confrontano letteralmente e non espandono mai un carattere jolly.
Ricerca di regole e sapere da dove provengono
GET /entries senza parametri restituisce tutto. Aggiungi email, first_name, last_name o ip_address per filtrare, combinati con AND quando ne invii più di uno, e confrontati senza distinzione tra maiuscole e minuscole.
Ogni voce porta anche un campo source che registra da dove proviene: api quando è stata creata tramite una Password Applicazione, e admin altrimenti. Quando una lista di blocco è mantenuta sia da persone che da macchine, quella distinzione è ciò che ti permette di revisionare una senza disturbare l'altra.
Gli endpoint delle impostazioni completano il quadro, anche se c'è solo un'impostazione da leggere o scrivere. checkout_denial_message è il messaggio che un acquirente bloccato vede, e non può essere vuoto.
Cosa rifiuterà l'API
Quattro rifiuti sono degni di nota prima di collegare qualsiasi cosa, perché ognuno di essi è deliberato.
- Un indirizzo IP malformato viene rifiutato con un
400alla creazione e all'aggiornamento, e saltato e contato in un batch. - I caratteri jolly nudi sono rifiutati ovunque. Rimuovendo gli asterischi, gli spazi bianchi e i separatori da
*,*@*o*.*non rimane nulla, e una regola che corrisponde a ogni cliente è un'interruzione piuttosto che un blocco. - Più di cinque caratteri jolly in un singolo valore fallisce per lo stesso motivo.
- Viene rifiutata una voce senza nome, senza email e senza IP, poiché non ci sarebbe nulla su cui corrispondere.
Conclusione
L'API della lista di blocco di WooCommerce trasforma le tue regole da qualcosa che mantieni tu a qualcosa che il tuo stack mantiene per te. Stesse regole, stessa corrispondenza, stesso comportamento al checkout, raggiungibile da chiunque sappia già che un cliente è un problema.
Se sei nuovo al plugin, la nostra introduzione a Checkout Guard copre cosa fa la lista di blocco. Per un quadro più ampio, la nostra guida ai flussi di lavoro di automazione dei dati di WooCommerce e la nostra spiegazione su come esportare i dati di WooCommerce in Zapier coprono gli altri ambiti in cui l'automazione porta benefici.
Un'ultima cosa degna di essere detta chiaramente. Le voci bloccate sono dati personali e un indirizzo IP è un identificatore online ai sensi del GDPR, che il Considerando 30 nomina direttamente. Un'API rende facile accumularne molti rapidamente, quindi decidi quanto tempo li conservi prima di aprire il rubinetto.
L'API della lista di blocco di WooCommerce è disponibile in Checkout Guard 1.0.2.
Domande Frequenti
Come posso autenticarmi con l'API della block list di WooCommerce?
Usa una Password per l'applicazione WordPress invece dell'autenticazione HTTP Basic. Creane una da Utenti → Profilo → Password per l'applicazione, quindi invia il nome utente dell'account come nome utente e la password generata come password. Non sono necessari cookie o nonce.
Perché ricevo un 403 quando le mie credenziali sono corrette?
Ogni route richiede la capacità manage_woocommerce. Una Password per l'applicazione appartenente a un utente senza questa capacità si autentica con successo e viene poi rifiutata. Usa un account Amministratore o Responsabile del negozio. Un 401 indica che non sono arrivate credenziali.
Chiamare l'endpoint create due volte aggiungerà un duplicato?
No. POST /entries è idempotente. Una voce con la stessa email viene aggiornata e restituita anziché duplicata. Lo stesso vale per un nome e cognome corrispondenti quando non viene fornita un'email, o un indirizzo IP corrispondente quando nessuno dei due viene fornito.
Posso sincronizzare la mia intera block list da un altro sistema?
Sì. POST /entries/batch accetta un array create e un array delete in un'unica richiesta e restituisce un riepilogo di ciò che è stato creato, eliminato, non trovato e saltato. Le creazioni vengono eseguite prima delle eliminazioni.
L'API della block list di WooCommerce utilizza la stessa logica di blocco del checkout?
Sì. POST /check riutilizza lo stesso codice corrispondente della protezione del checkout live, quindi la sua risposta non può discostarsi da ciò che sperimenta un cliente reale. Restituisce se il cliente è bloccato e quale voce corrispondeva.
Posso usare caratteri jolly tramite l'API?
Sì, nei valori delle regole. I campi Nome, Email e IP accettano un carattere jolly * durante la creazione e l'aggiornamento. L'endpoint /check è l'eccezione e rifiuta i caratteri jolly, poiché un candidato al controllo è un valore di un cliente reale piuttosto che un modello.
