Checkout Guard ma teraz udokumentowane WooCommerce Block List API. Twoje narzędzie do wykrywania oszustw, helpdesk lub skrypt synchronizacji może dodawać, usuwać i wyszukiwać reguły blokowania bez sesji przeglądarki. Klient może zostać zablokowany w momencie, gdy coś innego w Twoim stosie zdecyduje, że powinien być.
WooCommerce Block List API jest po raz pierwszy udokumentowane w Checkout Guard 1.0.2, który dodaje również punkty końcowe /check i wsadowe, w przestrzeni nazw cgfw/v1. Jest to ten sam zestaw tras, którego używa własny ekran administracyjny wtyczki, co ma większe znaczenie, niż się wydaje. Nie ma drugiej implementacji, która mogłaby się rozjechać z tym, co faktycznie dzieje się przy kasie.
Spis treści
- Do czego służy WooCommerce Block List API
- Uwierzytelnianie za pomocą hasła aplikacji
- Punkty końcowe
- Co może zawierać reguła
- Tworzenie reguł bez tworzenia duplikatów
- Synchronizacja całej listy w jednym żądaniu
- Pytanie, czy klient zostałby zablokowany
- Wyszukiwanie reguł i wiedza, skąd pochodzą
- Czego API odmówi
- Wnioski
- Często zadawane pytania
Do czego służy WooCommerce Block List API
Większość list blokowanych jest tworzona ręcznie. Ktoś składa zamówienie, którego nie chcieliśmy, otwieramy panel administracyjny i dodajemy go.
Działa to, gdy wolumen jest niski, a decyzje należą do Ciebie. Przestaje działać, gdy sygnał znajduje się gdzie indziej. Usługa oceny ryzyka oszustwa oznacza zamówienie. Twój agent pomocy technicznej zamyka zgłoszenie dotyczące obraźliwego klienta. Obciążenie zwrotne trafia do Twojego dostawcy płatności. W każdym przypadku coś już wie, że osoba powinna zostać zablokowana, a jedynym brakującym elementem jest sposób, aby to powiedzieć bez człowieka otwierającego WordPress.
To jest luka, którą to zamyka. Interfejs API listy zablokowanych WooCommerce jest zbudowany dla wywoływaczy maszynowych: bez ciasteczek, bez nonce, bez ekranu administratora.
Uwierzytelnianie za pomocą hasła aplikacji
Automatyczni wywoływacze uwierzytelniają się za pomocą Hasła Aplikacji WordPress przez HTTP Basic Auth. Nie ma osobnego klucza Checkout Guard do utworzenia.
Zgodnie z dokumentacją WordPress dotyczącą haseł aplikacji, tworzysz je w sekcji Użytkownicy → Profil → Hasła aplikacji, nadając mu nazwę, taką jak automatyzacja Checkout Guard. Skopiuj wygenerowaną wartość. Jest ona wyświetlana raz, w formie xxxx xxxx xxxx xxxx xxxx xxxx, a spacje są jej częścią. Użyj nazwy logowania konta jako nazwy użytkownika Basic Auth i tego hasła jako hasła Basic Auth.
Jeden wymóg łatwo przeoczyć. Każda trasa w interfejsie API listy zablokowanych WooCommerce sprawdza uprawnienie manage_woocommerce, więc konto stojące za Hasłem Aplikacji musi być Administratorem lub Kierownikiem Sklepu. Hasło należące do innego użytkownika uwierzytelnia się doskonale, a następnie jest odrzucane z kodem 403. Brakujące dane uwierzytelniające zwracają zamiast tego 401, co jest użytecznym sposobem odróżnienia tych dwóch błędów.
Hasła aplikacji wymagają WordPress 5.6 lub nowszego oraz witryny obsługiwanej przez HTTPS. Sam Checkout Guard obsługuje WordPress 5.2, więc na witrynie 5.2 do 5.5 ta ścieżka uwierzytelniania nie istnieje.
Punkty końcowe
Osiem tras tworzy interfejs API listy zablokowanych WooCommerce, obejmujący listę zablokowanych i jej ustawienia.
| Metoda | Trasa | Cel |
|---|---|---|
| GET | /entries | Wyświetl wpisy, opcjonalnie filtrowane |
| POST | /entries | Utwórz wpis, idempotentny |
| POST | /entries/batch | Masowe tworzenie i usuwanie |
| PUT | /entries/{id} | Zaktualizuj wpis według id |
| DELETE | /entries/{id} | Usuń wpis według id |
| POST | /check | Czy ten klient zostałby zablokowany? |
| GET | /settings | Odczytaj ustawienia |
| POST | /settings | Zaktualizuj ustawienia |
Podstawowy adres URL to https://your-store.example.com/wp-json/cgfw/v1. Jeśli te adresy URL zwracają 404, sprawdź prefiks REST swojej witryny, ponieważ /wp-json/ jest domyślny, a nie gwarancją. Witryna z prostymi permalinkami używa zamiast tego formularza ?rest_route=.
Wyświetlenie przestrzeni nazw pokazuje dwie dodatkowe trasy, /license i /license/activate. Należą one do ekranu aktywacji licencji wtyczki, a nie do listy zablokowanych, i nie są częścią opisanego tutaj interfejsu API.
Co może zawierać reguła
Zablokowany wpis zawiera id, opcjonalne imię i nazwisko, opcjonalny adres e-mail, opcjonalny adres IP i opcjonalne notatki o długości do 140 znaków. Zapisuje również id użytkownika, który go utworzył, oraz pole pochodzenia. Należy wypełnić co najmniej jedno z pól imię, e-mail lub IP.
Wpis blokuje klienta, gdy dowolne z jego wypełnionych pól pasuje. Dopasowane są oba imiona, lub adres e-mail, lub adres IP. Nazwy i adresy e-mail są porównywane bez uwzględniania wielkości liter. Adres IP klienta podczas finalizacji zakupu jest pobierany za pomocą pomocnika geolokalizacji WooCommerce, więc proxy lub CDN przed Twoim sklepem nie zakłóci porównania.
Wartości nazwy, adresu e-mail i adresu IP akceptują symbol wieloznaczny *, dzięki czemu jedna reguła może obejmować cały domenę adresu e-mail lub zakres IPv4. Symbole wieloznaczne dla adresów IP są węższe niż pozostałe: tylko w formie segmentu IPv4, więc 192.168.1.* działa, a 2001:db8::* nie.
Pole notes zasługuje na osobną uwagę. Jest to pole API. Pojawia się jako kolumna w tabeli Zablokowane wpisy i stamtąd pobiera swoją zawartość, ale w oknie dialogowym dodawania wpisu nie ma pola na notatki. Jeśli chcesz, aby Twoje reguły wyjaśniały się później, API jest właściwym sposobem na ich ustawienie.
Tworzenie reguł bez tworzenia duplikatów
POST /entries jest idempotentny, co sprawia, że można go bezpiecznie wywoływać z poziomu czegoś, nad czym nie masz pełnej kontroli.
Jeśli wpis z tym samym adresem e-mail już istnieje, zostanie zaktualizowany o wszelkie niepuste pola, które wyślesz, i zwrócony do Ciebie. Bez adresu e-mail, to samo imię i nazwisko identyfikuje wpis. Bez żadnego z nich, ten sam adres IP. Dwukrotne wywołanie z tym samym adresem e-mail daje dokładnie jeden wpis, a nie dwa.
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"}'Blokowanie wyłącznie na podstawie połączenia działa w ten sam sposób.
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"}'Co zaobserwowaliśmy: integracje, które powodują problemy, to te, które zakładają, że utworzenie jest utworzeniem. Ponowna próba po przekroczeniu limitu czasu sieci, dwukrotnie dostarczony webhook, nocna praca, która ponownie wysyła wczorajsze wiersze, i nagle lista blokad zawiera cztery kopie tej samej osoby, a nikt nie jest w stanie określić, która jest aktualna. Idempotentność na podstawie adresu e-mail, nazwy i adresu IP zatrzymuje to, więc wysyłaj identyfikujące pole za każdym razem, zamiast tylko przy pierwszym wywołaniu.
Synchronizacja całej listy w jednym żądaniu
POST /entries/batch przyjmuje tablicę create i tablicę delete, co jest formatem, którego potrzebujesz, gdy inny system jest właścicielem listy, a WordPress jest obserwatorem.
{
"create": [
{ "email": "[email protected]", "notes": "ring leader" },
{ "first_name": "Jane", "last_name": "Doe" }
],
"delete": [ "11112222-3333-4444-5555-666677778888" ]
}Najpierw uruchamiane są tworzenia, każde przez tę samą ścieżkę idempotentną co pojedyncze tworzenie, a następnie usuwanie według identyfikatora. Co najmniej jedna z tych dwóch tablic musi być niepusta. Odpowiedź informuje, co się stało, zamiast zmuszać Cię do samodzielnego porównywania listy:
{
"created": [ { "id": "…", "email": "[email protected]" } ],
"deleted": [ "11112222-3333-4444-5555-666677778888" ],
"not_found": [],
"skipped": 0
}not_found zbiera identyfikatory usunięć, które niczego nie dopasowały. skipped zlicza ładunki tworzenia, które zostały zignorowane, ponieważ nie zawierały nazwy, adresu e-mail ani adresu IP, lub ponieważ ich adres IP był niepusty i nieprawidłowy. Paczka zawierająca błędne wiersze nadal zwraca 200, więc odczytaj skipped zamiast polegać wyłącznie na kodzie stanu.
Pytanie, czy klient zostałby zablokowany
POST /check odpowiada bezpośrednio na pytanie i uruchamia ten sam kod dopasowujący co rzeczywisty strażnik finalizacji zakupu. Odpowiedź nie może odbiegać od tego, czego doświadcza prawdziwy kupujący, co jest celem jej istnienia, zamiast Ty reimplementowałbyś logikę.
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]"}'Odpowiedź brzmi { "blocked": true, "matched_entry": { … } }, z matched_entry ustawionym na null, gdy nic nie pasowało. Wiedza, która reguła zablokowała kogoś, jest zazwyczaj bardziej użyteczna niż wiedza, że coś się stało.
Ten punkt końcowy jest celowo bardziej restrykcyjny niż inne. Kandydat to rzeczywista wartość klienta, nigdy wzorzec, więc * w jakimkolwiek polu jest odrzucany z kodem 400. Wyszukiwanie reguł działa w drugą stronę: GET /entries?email=*@example.com znajduje tę dokładnie zapisaną regułę, ponieważ wyszukiwania porównują dosłownie i nigdy nie rozszerzają symbolu wieloznacznego.
Wyszukiwanie reguł i wiedza, skąd pochodzą
GET /entries bez parametrów zwraca wszystko. Dodaj email, first_name, last_name lub ip_address, aby filtrować, łącząc je operatorem AND, gdy wysyłasz więcej niż jeden, i porównując bez uwzględniania wielkości liter.
Każdy wpis zawiera również pole source, rejestrujące jego pochodzenie: api, gdy został utworzony za pomocą Hasła Aplikacji, i admin w przeciwnym razie. Kiedy lista blokad jest utrzymywana zarówno przez ludzi, jak i maszyny, to rozróżnienie pozwala na audytowanie jednego bez zakłócania drugiego.
Punkty końcowe ustawień uzupełniają całość, chociaż jest tylko jedno ustawienie do odczytu lub zapisu. checkout_denial_message to komunikat, który widzi zablokowany kupujący, i nie może być pusty.
Czego API odmówi
Cztery odrzucenia są warte poznania, zanim cokolwiek podłączysz, ponieważ każde z nich jest celowe.
- Nieprawidłowy adres IP jest odrzucany z kodem
400podczas tworzenia i aktualizacji, a pomijany i liczony w partii. - Puste symbole wieloznaczne są odrzucane wszędzie. Usunięcie gwiazdek, białych znaków i separatorów z
*,*@*lub*.*nie pozostawia niczego, a reguła pasująca do każdego klienta jest awarią, a nie blokadą. - Więcej niż pięć symboli wieloznacznych w pojedynczej wartości kończy się niepowodzeniem z tego samego powodu.
- Wpis bez nazwy, bez adresu e-mail i bez adresu IP jest odrzucany, ponieważ nie byłoby niczego do dopasowania.
Wnioski
API listy blokad WooCommerce zamienia Twoje reguły z czegoś, co utrzymujesz, na coś, co Twoja infrastruktura utrzymuje za Ciebie. Te same reguły, to samo dopasowywanie, to samo zachowanie przy kasie, dostępne z dowolnego miejsca, które już wie, że klient jest problemem.
Jeśli dopiero zaczynasz korzystać z wtyczki, nasze wprowadzenie do Checkout Guard omawia, co robi lista blokad. Aby uzyskać szerszy obraz, nasz przewodnik po przepływach pracy automatyzacji danych WooCommerce i nasz samouczek dotyczący eksportowania danych WooCommerce do Zapier obejmują inne obszary, w których automatyzacja przynosi korzyści.
Jeszcze jedna rzecz, którą warto jasno powiedzieć. Zablokowane wpisy to dane osobowe, a adres IP jest identyfikatorem online zgodnie z RODO, który Motyw 30 wymienia bezpośrednio. API ułatwia szybkie gromadzenie wielu z nich, więc zdecyduj, jak długo je przechowujesz, zanim odkręcisz kurek.
API listy blokad WooCommerce jest dostępne w Checkout Guard 1.0.2.
Często zadawane pytania
Jak uwierzytelnić się w WooCommerce Block List API?
Użyj hasła aplikacji WordPress zamiast uwierzytelniania HTTP Basic. Utwórz je w sekcji Użytkownicy → Profil → Hasła aplikacji, a następnie wyślij nazwę logowania konta jako nazwę użytkownika i wygenerowane hasło jako hasło. Nie są potrzebne żadne pliki cookie ani nonce.
Dlaczego otrzymuję błąd 403, mimo że moje dane uwierzytelniające są poprawne?
Każda trasa wymaga uprawnienia manage_woocommerce. Hasło aplikacji należące do użytkownika bez tego uprawnienia uwierzytelnia się pomyślnie, a następnie jest odrzucane. Użyj konta Administratora lub Kierownika sklepu. Kod 401 oznacza, że żadne dane uwierzytelniające nie dotarły.
Czy dwukrotne wywołanie punktu końcowego tworzenia doda duplikat?
Nie. POST /entries jest idempotentne. Wpis o tym samym adresie e-mail jest aktualizowany i zwracany zamiast duplikowany. To samo dotyczy pasującego imienia i nazwiska, gdy nie podano adresu e-mail, lub pasującego adresu IP, gdy nie podano żadnego z nich.
Czy mogę zsynchronizować całą moją listę blokowanych z innego systemu?
Tak. POST /entries/batch akceptuje tablicę create i tablicę delete w jednym żądaniu i zwraca podsumowanie tego, co zostało utworzone, usunięte, nie znalezione i pominięte. Tworzenie odbywa się przed usuwaniem.
Czy WooCommerce Block List API używa tej samej logiki blokowania co przy kasie?
Tak. POST /check używa tego samego pasującego kodu co rzeczywisty Checkout Guard, więc jego odpowiedź nie może odbiegać od tego, czego doświadcza prawdziwy klient. Zwraca, czy klient jest zablokowany i który wpis pasował.
Czy mogę używać symboli wieloznacznych przez API?
Tak, w wartościach reguł. Pola Nazwa, e-mail i IP akceptują symbol wieloznaczny * podczas tworzenia i aktualizacji. Wyjątkiem jest punkt końcowy /check, który odrzuca symbole wieloznaczne, ponieważ kandydat do sprawdzenia jest wartością rzeczywistego klienta, a nie wzorcem.
